@ratio-mcp/dev-server 1.5.1 → 1.6.0

package/dist/schemas/app-distribution.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "topic": "app_distribution",
+  "summary": "Every Ratio app has a distribution type chosen at creation: public or private. It controls who can install the app, whether it is listed in the marketplace, and whether it goes through human review.",
+  "types": {
+    "public": {
+      "definition": "Available to ALL merchants via the marketplace.",
+      "distribution": "Listed in the public marketplace; any merchant can discover and install it.",
+      "review": "Each submitted version must pass admin (human) review before it can be published.",
+      "publication": "Published manually after approval (or via the app's auto-publish setting).",
+      "use_case": "Third-party integrations sold to many merchants.",
+      "create": "Default. create_app with app_type omitted or app_type: \"public\"."
+    },
+    "private": {
+      "definition": "Available ONLY to an explicit whitelist of merchants.",
+      "distribution": "Not listed in the marketplace; installable only by whitelisted merchant IDs.",
+      "review": "Skips human review — versions are auto-reviewed (system actor) and auto-published on upload.",
+      "publication": "Immediate on version upload.",
+      "requirement": "At least one merchant ID must be provided at creation time.",
+      "whitelist_management": "Add/remove merchants any time via the manage_private_merchants tool (or GET/POST/DELETE /applications/:id/private-merchants).",
+      "use_case": "Custom builds for specific enterprise clients or partner integrations.",
+      "create": "create_app with app_type: \"private\" and merchant_ids: [\"merchant-id-1\", ...] (at least one)."
+    }
+  },
+  "comparison": [
+    { "aspect": "Distribution",  "public": "All merchants",         "private": "Whitelisted merchants only" },
+    { "aspect": "Marketplace",   "public": "Listed",                "private": "Hidden" },
+    { "aspect": "Review",        "public": "Human review required", "private": "Auto-reviewed (system)" },
+    { "aspect": "Publication",   "public": "After approval",        "private": "Immediate on upload" },
+    { "aspect": "Merchant ID whitelist", "public": "N/A",          "private": "Required (>= 1)" }
+  ],
+  "mcp_support": {
+    "create_app": "Accepts app_type ('public' | 'private', default public) and merchant_ids. Private requires merchant_ids (>= 1).",
+    "manage_private_merchants": "list | add | remove whitelisted merchants for a private app."
+  }
+}

package/dist/schemas/customers.json

@@ -0,0 +1,26 @@
+{
+  "resource": "customers",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/api/v1/customers/:id",
+      "controller_order": 1,
+      "handler_name": "getCustomerById",
+      "required_scope": "read_customers",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/discounts.json

@@ -0,0 +1,81 @@
+{
+  "resource": "discounts",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "common_headers": {
+    "idempotency-key": "header"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/discounts",
+      "controller_order": 1,
+      "handler_name": "create",
+      "required_scope": "write_discounts",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": []
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/discounts",
+      "controller_order": 2,
+      "handler_name": "findAll",
+      "required_scope": "read_discounts",
+      "request_body": null
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 3,
+      "handler_name": "findOne",
+      "required_scope": "read_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 4,
+      "handler_name": "update",
+      "required_scope": "write_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": {
+        "content_type": "application/json",
+        "fields": []
+      }
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 5,
+      "handler_name": "remove",
+      "required_scope": "write_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/draft_orders.json

@@ -0,0 +1,112 @@
+{
+  "resource": "draft_orders",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "common_headers": {
+    "gk-merchant-id": "Required. Tenant/merchant context for the request."
+  },
+  "notes": "Paths carry a doubled /v1 segment (global /api/v1 prefix + controller 'v1/draft-orders'). Line-item / customer / address shapes mirror the orders resource.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 1,
+      "handler_name": "createDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Create a draft order",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          { "name": "email", "type": "string", "required": false, "description": "Customer email" },
+          { "name": "currency", "type": "string", "required": false, "description": "Currency code (e.g. INR)" },
+          { "name": "line_items", "type": "array", "required": false, "description": "Line items (same shape as orders: variant_id, product_id, title, quantity, sku, price)" },
+          { "name": "customer", "type": "object", "required": false, "description": "Customer details (same shape as orders)" },
+          { "name": "billing_address", "type": "object", "required": false, "description": "Billing address (same shape as orders)" },
+          { "name": "shipping_address", "type": "object", "required": false, "description": "Shipping address (same shape as orders)" },
+          { "name": "note", "type": "string", "required": false }
+        ]
+      },
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 2,
+      "handler_name": "updateDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Update a draft order",
+      "description": "Update a draft order. The draft order id is supplied in the request body (not the path).",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          { "name": "id", "type": "string", "required": true, "description": "The draft order ID to update (in body)" },
+          { "name": "email", "type": "string", "required": false },
+          { "name": "line_items", "type": "array", "required": false },
+          { "name": "customer", "type": "object", "required": false },
+          { "name": "shipping_address", "type": "object", "required": false },
+          { "name": "billing_address", "type": "object", "required": false }
+        ]
+      },
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 3,
+      "handler_name": "getDraftOrders",
+      "required_scope": "read_draft_orders",
+      "summary": "List draft orders",
+      "query_params": [
+        { "name": "limit", "type": "number", "required": false },
+        { "name": "offset", "type": "number", "required": false },
+        { "name": "status", "type": "string", "required": false }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrderListResponse"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/v1/draft-orders/:id",
+      "controller_order": 4,
+      "handler_name": "getDraftOrderById",
+      "required_scope": "read_draft_orders",
+      "summary": "Get a draft order by ID",
+      "path_params": [
+        { "name": "id", "type": "string", "required": true, "description": "The draft order ID" }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/v1/draft-orders/:id",
+      "controller_order": 5,
+      "handler_name": "deleteDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Delete a draft order",
+      "path_params": [
+        { "name": "id", "type": "string", "required": true, "description": "The draft order ID to delete" }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrder"
+    }
+  ],
+  "schemas": {
+    "DraftOrder": {
+      "id": "string — draft order identifier",
+      "email": "string | null",
+      "currency": "string",
+      "line_items": "LineItem[] — same shape as orders",
+      "customer": "Customer object",
+      "shipping_address": "Address | null",
+      "billing_address": "Address | null",
+      "note": "string | null",
+      "status": "string — draft status",
+      "created_at": "string — ISO 8601",
+      "updated_at": "string — ISO 8601"
+    }
+  }
+}

package/dist/schemas/loyalty.json

@@ -0,0 +1,147 @@
+{
+  "resource": "loyalty",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/loyalty/points/credit",
+      "controller_order": 1,
+      "handler_name": "credit",
+      "required_scope": "write_loyalty",
+      "summary": "Credit loyalty points to a customer (idempotent).",
+      "description": "Adds points to the customer’s balance. Same `idempotency_key` on retry returns the existing transaction without double-crediting.",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          {
+            "name": "phone",
+            "type": "string",
+            "required": true,
+            "description": "Customer phone number (loyalty key)"
+          },
+          {
+            "name": "points",
+            "type": "number",
+            "required": true,
+            "description": "Points to apply (positive integer, max 100000 per transaction)"
+          },
+          {
+            "name": "idempotency_key",
+            "type": "string",
+            "required": true,
+            "description": "Caller-supplied idempotency key. Same key on retry returns the existing transaction without double-applying."
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false,
+            "description": "Free-text description of the reason"
+          },
+          {
+            "name": "metadata",
+            "type": "object",
+            "required": false,
+            "description": "Arbitrary structured data attached to the ledger row"
+          }
+        ]
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/loyalty/points/debit",
+      "controller_order": 2,
+      "handler_name": "debit",
+      "required_scope": "write_loyalty",
+      "summary": "Debit loyalty points from a customer (idempotent).",
+      "description": "Deducts points from the customer’s balance. Returns 400 if the customer’s balance is insufficient.",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          {
+            "name": "phone",
+            "type": "string",
+            "required": true,
+            "description": "Customer phone number (loyalty key)"
+          },
+          {
+            "name": "points",
+            "type": "number",
+            "required": true,
+            "description": "Points to apply (positive integer, max 100000 per transaction)"
+          },
+          {
+            "name": "idempotency_key",
+            "type": "string",
+            "required": true,
+            "description": "Caller-supplied idempotency key. Same key on retry returns the existing transaction without double-applying."
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false,
+            "description": "Free-text description of the reason"
+          },
+          {
+            "name": "metadata",
+            "type": "object",
+            "required": false,
+            "description": "Arbitrary structured data attached to the ledger row"
+          }
+        ]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/loyalty/points/:phone/balance",
+      "controller_order": 3,
+      "handler_name": "getBalance",
+      "required_scope": "read_loyalty",
+      "summary": "Get a customer's current loyalty balance + lifetime stats.",
+      "description": "Returns the redeemable balance and lifetime earned/redeemed/expired/adjusted totals. A customer with no loyalty record yet returns a zero-balance response.",
+      "path_params": [
+        {
+          "name": "phone",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/loyalty/points/:phone/history",
+      "controller_order": 4,
+      "handler_name": "getHistory",
+      "required_scope": "read_loyalty",
+      "summary": "Get a customer's loyalty transaction history (paginated).",
+      "description": "Returns the full points ledger (earn, redeem, adjust, reversal, expire) for the customer, most recent first, with pagination metadata.",
+      "query_params": [
+        {
+          "name": "page",
+          "type": "number",
+          "required": false,
+          "description": "Page number (1-based); os-loyalty defaults to 1"
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "required": false,
+          "description": "Rows per page"
+        }
+      ],
+      "path_params": [
+        {
+          "name": "phone",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/oauth.json

@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "flows": {
+    "authorization_code": {
+      "description": "Standard OAuth 2.0 Authorization Code flow for installing apps on merchant stores",
+      "steps": [
+        {
+          "step": 1,
+          "name": "Request Authorization Code",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/authorize",
+          "description": "Request an authorization code by providing client_id, merchant_id, redirect_uri, and scopes. The app must be published before this step.",
+          "request_body": {
+            "clientId": "string — Your app's client ID",
+            "redirectUri": "string — Registered redirect URI",
+            "merchantId": "string — Merchant ID of the store installing the app",
+            "scopes": "string[] — Array of scopes to request (e.g. ['read_orders'])"
+          },
+          "response": {
+            "code": "string — Authorization code (expires quickly)",
+            "redirectUri": "string — The redirect URI",
+            "expiresAt": "string — ISO 8601 expiry timestamp"
+          }
+        },
+        {
+          "step": 2,
+          "name": "Exchange Code for Tokens",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/token",
+          "description": "Exchange the authorization code for access and refresh tokens. Must be called immediately — the code expires quickly.",
+          "request_body": {
+            "grant_type": "authorization_code",
+            "code": "string — The authorization code from step 1",
+            "clientId": "string — Your app's client ID",
+            "clientSecret": "string — Your app's client secret",
+            "redirectUri": "string — Must match step 1"
+          },
+          "response": {
+            "access_token": "string — Bearer token for API calls",
+            "token_type": "Bearer",
+            "expires_in": "number — Seconds until token expires",
+            "refresh_token": "string — Token for refreshing access",
+            "scope": "string — Granted scopes (comma-separated)",
+            "merchant_id": "string — Merchant ID"
+          }
+        },
+        {
+          "step": 3,
+          "name": "Refresh Token",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/token",
+          "description": "Use the refresh token to get a new access token when the current one expires.",
+          "request_body": {
+            "grant_type": "refresh_token",
+            "refresh_token": "string — The refresh token",
+            "clientId": "string — Your app's client ID",
+            "clientSecret": "string — Your app's client secret"
+          },
+          "response": {
+            "access_token": "string — New bearer token",
+            "token_type": "Bearer",
+            "expires_in": "number — Seconds until new token expires",
+            "refresh_token": "string — New refresh token",
+            "scope": "string — Granted scopes",
+            "merchant_id": "string — Merchant ID"
+          }
+        }
+      ]
+    }
+  }
+}