open-mercato-client (Rust)

Typed API client for the Open Mercato platform. This library provides code generation tools to create Rust types from your Open Mercato instance's OpenAPI specification.

Since Open Mercato allows custom modules and extensions, each instance has its own API specification. Therefore, you need to generate types specific to your Open Mercato instance using the provided generators.

Full product docs live at https://docs.openmercato.com and the hosted API explorer is available at https://demo.openmercato.com/docs/api.

⚠️ Important: Generate Types for Your Instance

This library does NOT include full, instance-specific types. You must generate types from your own Open Mercato instance's OpenAPI specification because:

• Each Open Mercato instance can have different modules enabled
• Custom modules extend the API
• The API specification is instance-specific

See GENERATION.md for detailed generation instructions. The generator lives in ../generator.

Installation

Add this to your Cargo.toml:

[dependencies]
open-mercato-client = { path = "../open-mercato-rust-client/rust-client" }
# Or when published to crates.io:
# open-mercato-client = "0.3.12"

Usage

use open_mercato_client::{Client, ClientBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new()
        .base_url("https://api.your-mercato.com/api")
        .access_token("your-token-here")
        .build()?;

    // Make a GET request
    let response: serde_json::Value = client
        .get_with_query(
            "/customers/customers/people",
            &[("page", "1"), ("pageSize", "20")]
        )
        .await?;

    println!("Response: {:?}", response);
    Ok(())
}

Base URL resolution

If base_url is omitted, the client defaults to http://localhost:3000/api. You can also set it via environment variables (to be implemented).

Authentication

Pass a string or async function via access_token. Values are normalized to Authorization: Bearer <token> automatically. API keys starting with omk_ are automatically prefixed with ApiKey scheme.

// Static token
let client = ClientBuilder::new()
    .access_token("your-token")
    .build()?;

// Dynamic token provider
let client = ClientBuilder::new()
    .access_token_provider(|| {
        Ok(std::env::var("OPEN_MERCATO_TOKEN")?)
    })
    .build()?;

Making requests

The client provides methods for all HTTP verbs:

// GET request
let data: ResponseType = client.get("/path/to/endpoint").await?;

// GET with query parameters
let data: ResponseType = client.get_with_query("/path", &query_params).await?;

// POST request
let data: ResponseType = client.post("/path", &request_body).await?;

// PUT request
let data: ResponseType = client.put("/path", &request_body).await?;

// PATCH request
let data: ResponseType = client.patch("/path", &request_body).await?;

// DELETE request
let data: ResponseType = client.delete("/path").await?;

Error handling

The client returns Result<T, ClientError> where ClientError can be:

• Http(reqwest::Error) - HTTP request errors
• Json(serde_json::Error) - JSON serialization/deserialization errors
• InvalidUrl(url::ParseError) - Invalid URL errors
• ApiError { status, message, body } - API returned an error response
• Configuration(String) - Configuration errors

Generating Types for Your Instance

⚠️ Important: Since Open Mercato allows custom modules, each instance has a unique API. You must generate types from your instance's OpenAPI specification.

See GENERATION.md for detailed instructions.

Quick Start

1. Get your OpenAPI spec from your instance (usually at /docs/api/openapi.json)
2. Generate types:

   cd ../generator
   yarn generate:rust-types:full <path-to-your-openapi.json>
   

3. Use the generated types in your code

Generation Methods

Types can be generated using three different approaches:

1. Full generation using openapi-generator-cli (Recommended for production)

Generates a complete Rust API client with full type definitions, client methods per endpoint, and domain modules:

cd ../generator
yarn generate:rust-types:full <path-to-openapi.json>

This approach uses openapi-generator-cli to generate:

• Full type definitions for all schemas (structs, enums)
• Client methods per endpoint with proper types
• Domain modules organized by resource (sales, customers, etc.)
• Complete request/response types (not serde_json::Value)

When to use:

• Production-ready client library
• Full type safety for all endpoints
• Complete API coverage
• Public library publication

2. Alternative: Using OpenAPI JSON directly

Generates simplified Rust type structures from OpenAPI JSON/YAML:

# From repo root
cd generator
yarn generate:rust-types:openapi <path-to-openapi.json>

# Or let it auto-detect from common locations
yarn generate:rust-types:openapi

This script reads the OpenAPI specification and generates Rust types with schema information. It will automatically look for OpenAPI files in common locations:

• ../open-mercato/openapi.json
• ../open-mercato/openapi.yaml
• ../open-mercato/docs/openapi.json
• ../open-mercato/packages/api/openapi.json

When to use:

• Quick prototyping with simplified types
• Limited API subset
• Manual type definitions

3. Alternative: Using TypeScript types file

You can also generate types from the TypeScript openapi.types.ts file:

# From repo root
cd generator
yarn generate:rust-types:typescript <path-to-openapi.types.ts>

Example:

yarn generate:rust-types:typescript ../open-mercato/packages/client/src/generated/openapi.types.ts

This script reads the TypeScript types file and generates the corresponding Rust type definitions in src/generated/.

Manual generation from TypeScript

If you need to regenerate types manually:

1. Ensure the TypeScript types file exists
2. Run the generation script with the file path:

   yarn generate:rust-types:typescript <path-to-openapi.types.ts>
   

3. Verify the generated files compile:

   cd rust-client
   cargo check
   

For complete type safety with all schema definitions, use the full generator (approach #1 above) which uses openapi-generator-cli internally.

Publishing to crates.io

1. Ensure artifacts are up to date and tests pass
2. Update version in Cargo.toml
3. Publish to crates.io:

   cd rust-client
   cargo publish