@ratio-mcp-qa/docs-server 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +16 -0
- package/dist/index.js.map +1 -0
- package/dist/schemas/oauth.json +71 -0
- package/dist/schemas/orders.json +167 -0
- package/dist/schemas/products.json +167 -0
- package/dist/schemas/schemas/oauth.json +71 -0
- package/dist/schemas/schemas/orders.json +167 -0
- package/dist/schemas/schemas/products.json +167 -0
- package/dist/schemas/schemas/scopes.json +52 -0
- package/dist/schemas/schemas/webhooks.json +69 -0
- package/dist/schemas/scopes.json +52 -0
- package/dist/schemas/webhooks.json +69 -0
- package/dist/server.d.ts +6 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +53 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/get-api-reference.d.ts +60 -0
- package/dist/tools/get-api-reference.d.ts.map +1 -0
- package/dist/tools/get-api-reference.js +53 -0
- package/dist/tools/get-api-reference.js.map +1 -0
- package/dist/tools/get-scope-map.d.ts +17 -0
- package/dist/tools/get-scope-map.d.ts.map +1 -0
- package/dist/tools/get-scope-map.js +102 -0
- package/dist/tools/get-scope-map.js.map +1 -0
- package/dist/tools/get-scopes.d.ts +63 -0
- package/dist/tools/get-scopes.d.ts.map +1 -0
- package/dist/tools/get-scopes.js +72 -0
- package/dist/tools/get-scopes.js.map +1 -0
- package/dist/tools/get-webhooks.d.ts +30 -0
- package/dist/tools/get-webhooks.d.ts.map +1 -0
- package/dist/tools/get-webhooks.js +32 -0
- package/dist/tools/get-webhooks.js.map +1 -0
- package/dist/tools/index.d.ts +15 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +110 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/lookup-docs.d.ts +58 -0
- package/dist/tools/lookup-docs.d.ts.map +1 -0
- package/dist/tools/lookup-docs.js +181 -0
- package/dist/tools/lookup-docs.js.map +1 -0
- package/dist/tools/validate-code.d.ts +12 -0
- package/dist/tools/validate-code.d.ts.map +1 -0
- package/dist/tools/validate-code.js +185 -0
- package/dist/tools/validate-code.js.map +1 -0
- package/dist/utils/logger.d.ts +16 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +85 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/schema-loader.d.ts +13 -0
- package/dist/utils/schema-loader.d.ts.map +1 -0
- package/dist/utils/schema-loader.js +61 -0
- package/dist/utils/schema-loader.js.map +1 -0
- package/dist/utils/zod-to-json.d.ts +7 -0
- package/dist/utils/zod-to-json.d.ts.map +1 -0
- package/dist/utils/zod-to-json.js +63 -0
- package/dist/utils/zod-to-json.js.map +1 -0
- package/package.json +26 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
3
|
+
import { createDocsServer } from './server.js';
|
|
4
|
+
import { logger } from './utils/logger.js';
|
|
5
|
+
async function main() {
|
|
6
|
+
logger.info('Starting Ratio Docs MCP Server...');
|
|
7
|
+
const server = createDocsServer();
|
|
8
|
+
const transport = new StdioServerTransport();
|
|
9
|
+
await server.connect(transport);
|
|
10
|
+
logger.info('Ratio Docs MCP Server is running on stdio');
|
|
11
|
+
}
|
|
12
|
+
main().catch((error) => {
|
|
13
|
+
logger.error('Fatal error:', error);
|
|
14
|
+
process.exit(1);
|
|
15
|
+
});
|
|
16
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAEjD,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;AAC3D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"flows": {
|
|
4
|
+
"authorization_code": {
|
|
5
|
+
"description": "Standard OAuth 2.0 Authorization Code flow for installing apps on merchant stores",
|
|
6
|
+
"steps": [
|
|
7
|
+
{
|
|
8
|
+
"step": 1,
|
|
9
|
+
"name": "Request Authorization Code",
|
|
10
|
+
"method": "POST",
|
|
11
|
+
"endpoint": "/api/v1/oauth/authorize",
|
|
12
|
+
"description": "Request an authorization code by providing client_id, merchant_id, redirect_uri, and scopes. The app must be published before this step.",
|
|
13
|
+
"request_body": {
|
|
14
|
+
"clientId": "string — Your app's client ID",
|
|
15
|
+
"redirectUri": "string — Registered redirect URI",
|
|
16
|
+
"merchantId": "string — Merchant ID of the store installing the app",
|
|
17
|
+
"scopes": "string[] — Array of scopes to request (e.g. ['read_orders'])"
|
|
18
|
+
},
|
|
19
|
+
"response": {
|
|
20
|
+
"code": "string — Authorization code (expires quickly)",
|
|
21
|
+
"redirectUri": "string — The redirect URI",
|
|
22
|
+
"expiresAt": "string — ISO 8601 expiry timestamp"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"step": 2,
|
|
27
|
+
"name": "Exchange Code for Tokens",
|
|
28
|
+
"method": "POST",
|
|
29
|
+
"endpoint": "/api/v1/oauth/token",
|
|
30
|
+
"description": "Exchange the authorization code for access and refresh tokens. Must be called immediately — the code expires quickly.",
|
|
31
|
+
"request_body": {
|
|
32
|
+
"grant_type": "authorization_code",
|
|
33
|
+
"code": "string — The authorization code from step 1",
|
|
34
|
+
"clientId": "string — Your app's client ID",
|
|
35
|
+
"clientSecret": "string — Your app's client secret",
|
|
36
|
+
"redirectUri": "string — Must match step 1"
|
|
37
|
+
},
|
|
38
|
+
"response": {
|
|
39
|
+
"access_token": "string — Bearer token for API calls",
|
|
40
|
+
"token_type": "Bearer",
|
|
41
|
+
"expires_in": "number — Seconds until token expires",
|
|
42
|
+
"refresh_token": "string — Token for refreshing access",
|
|
43
|
+
"scope": "string — Granted scopes (comma-separated)",
|
|
44
|
+
"merchant_id": "string — Merchant ID"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"step": 3,
|
|
49
|
+
"name": "Refresh Token",
|
|
50
|
+
"method": "POST",
|
|
51
|
+
"endpoint": "/api/v1/oauth/token",
|
|
52
|
+
"description": "Use the refresh token to get a new access token when the current one expires.",
|
|
53
|
+
"request_body": {
|
|
54
|
+
"grant_type": "refresh_token",
|
|
55
|
+
"refresh_token": "string — The refresh token",
|
|
56
|
+
"clientId": "string — Your app's client ID",
|
|
57
|
+
"clientSecret": "string — Your app's client secret"
|
|
58
|
+
},
|
|
59
|
+
"response": {
|
|
60
|
+
"access_token": "string — New bearer token",
|
|
61
|
+
"token_type": "Bearer",
|
|
62
|
+
"expires_in": "number — Seconds until new token expires",
|
|
63
|
+
"refresh_token": "string — New refresh token",
|
|
64
|
+
"scope": "string — Granted scopes",
|
|
65
|
+
"merchant_id": "string — Merchant ID"
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
{
|
|
2
|
+
"resource": "orders",
|
|
3
|
+
"base_url": "https://qa-os-ecosystem.dev.gokwik.io",
|
|
4
|
+
"auth": {
|
|
5
|
+
"type": "bearer",
|
|
6
|
+
"header": "Authorization",
|
|
7
|
+
"format": "Bearer <access_token>"
|
|
8
|
+
},
|
|
9
|
+
"endpoints": [
|
|
10
|
+
{
|
|
11
|
+
"method": "GET",
|
|
12
|
+
"path": "/api/v1/orders",
|
|
13
|
+
"controller_order": 1,
|
|
14
|
+
"handler_name": "getOrders",
|
|
15
|
+
"required_scope": "read_orders",
|
|
16
|
+
"summary": "List orders with pagination and filtering",
|
|
17
|
+
"description": "Retrieve a paginated list of orders from the merchant's store. Supports filtering by status, financial status, fulfillment status, and search.",
|
|
18
|
+
"query_params": [
|
|
19
|
+
{ "name": "limit", "type": "number", "required": false, "default": 50, "description": "Number of orders per page (max 100)" },
|
|
20
|
+
{ "name": "page", "type": "number", "required": false, "default": 1, "description": "Page number for pagination" },
|
|
21
|
+
{ "name": "status", "type": "string", "required": false, "enum": ["any", "open", "cancelled", "archived"], "description": "Filter by order status" },
|
|
22
|
+
{ "name": "financial_status", "type": "string", "required": false, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"], "description": "Filter by payment/financial status" },
|
|
23
|
+
{ "name": "fulfillment_status", "type": "string", "required": false, "enum": ["unfulfilled", "fulfilled", "partial", "partially_fulfilled", "restocked", "pending", "refunded", "returned"], "description": "Filter by fulfillment/shipping status" },
|
|
24
|
+
{ "name": "sort_field", "type": "string", "required": false, "enum": ["created_at", "updated_at", "processed_at", "order_number", "total_price", "items", "financial_status", "fulfillment_status"], "description": "Field to sort by" },
|
|
25
|
+
{ "name": "sort_direction", "type": "string", "required": false, "enum": ["asc", "desc"], "description": "Sort direction" },
|
|
26
|
+
{ "name": "search", "type": "string", "required": false, "description": "Search by order number, email, or phone" }
|
|
27
|
+
],
|
|
28
|
+
"request_body": null,
|
|
29
|
+
"response_schema": "OrderListResponse"
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"method": "GET",
|
|
33
|
+
"path": "/api/v1/orders/:id",
|
|
34
|
+
"controller_order": 2,
|
|
35
|
+
"handler_name": "getOrderById",
|
|
36
|
+
"required_scope": "read_orders",
|
|
37
|
+
"summary": "Get a single order by ID",
|
|
38
|
+
"description": "Retrieve the full details of a single order including line items, customer info, addresses, and payment status.",
|
|
39
|
+
"path_params": [
|
|
40
|
+
{ "name": "id", "type": "string", "required": true, "description": "The order ID" }
|
|
41
|
+
],
|
|
42
|
+
"request_body": null,
|
|
43
|
+
"response_schema": "Order"
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"method": "POST",
|
|
47
|
+
"path": "/api/v1/orders",
|
|
48
|
+
"controller_order": 3,
|
|
49
|
+
"handler_name": "createOrder",
|
|
50
|
+
"required_scope": "order-create",
|
|
51
|
+
"summary": "Create a new order",
|
|
52
|
+
"description": "Create an order in the merchant's store.",
|
|
53
|
+
"request_body": {
|
|
54
|
+
"content_type": "application/json",
|
|
55
|
+
"fields": [
|
|
56
|
+
{ "name": "payment_gateway_names", "type": "string[]", "required": true, "description": "Payment gateways used" },
|
|
57
|
+
{ "name": "financial_status", "type": "string", "required": true, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"], "description": "Payment status" },
|
|
58
|
+
{ "name": "currency", "type": "string", "required": true, "description": "Currency code (e.g. INR)" },
|
|
59
|
+
{ "name": "test", "type": "boolean", "required": true, "description": "Whether this is a test order" },
|
|
60
|
+
{ "name": "note", "type": "string", "required": false, "description": "Internal note for the order" },
|
|
61
|
+
{ "name": "tags", "type": "string", "required": false, "description": "Comma-separated tags" },
|
|
62
|
+
{ "name": "email", "type": "string", "required": false, "description": "Customer email" },
|
|
63
|
+
{ "name": "phone", "type": "string", "required": false, "description": "Customer phone" },
|
|
64
|
+
{ "name": "customer", "type": "object", "required": true, "description": "Customer details (id, email, first_name, last_name, state, phone, currency)" },
|
|
65
|
+
{ "name": "line_items", "type": "array", "required": true, "description": "Array of line items (variant_id, product_id, title, quantity, sku, price, taxable, requires_shipping, image)" },
|
|
66
|
+
{ "name": "billing_address", "type": "object", "required": true, "description": "Billing address (address1, city, country, first_name, last_name, phone, province, zip)" },
|
|
67
|
+
{ "name": "shipping_address", "type": "object", "required": true, "description": "Shipping address (same structure as billing_address)" }
|
|
68
|
+
]
|
|
69
|
+
},
|
|
70
|
+
"response_schema": "Order"
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"method": "PATCH",
|
|
74
|
+
"path": "/api/v1/orders/:id",
|
|
75
|
+
"controller_order": 4,
|
|
76
|
+
"handler_name": "updateOrder",
|
|
77
|
+
"required_scope": "order-create",
|
|
78
|
+
"summary": "Update an existing order",
|
|
79
|
+
"description": "Update order fields. Only provided fields are modified.",
|
|
80
|
+
"path_params": [
|
|
81
|
+
{ "name": "id", "type": "string", "required": true, "description": "The order ID to update" }
|
|
82
|
+
],
|
|
83
|
+
"request_body": {
|
|
84
|
+
"content_type": "application/json",
|
|
85
|
+
"fields": [
|
|
86
|
+
{ "name": "email", "type": "string", "required": false, "description": "Updated customer email" },
|
|
87
|
+
{ "name": "phone", "type": "string", "required": false, "description": "Updated customer phone" },
|
|
88
|
+
{ "name": "note", "type": "string", "required": false, "description": "Updated order note" },
|
|
89
|
+
{ "name": "tags", "type": "string", "required": false, "description": "Updated tags (comma-separated)" },
|
|
90
|
+
{ "name": "status", "type": "string", "required": false, "enum": ["open", "closed", "cancelled"], "description": "Order status" },
|
|
91
|
+
{ "name": "financial_status", "type": "string", "required": false, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"] },
|
|
92
|
+
{ "name": "fulfillment_status", "type": "string", "required": false, "enum": ["fulfilled", "partial", "partially_fulfilled", "unfulfilled", "restocked", "pending", "refunded", "returned"] },
|
|
93
|
+
{ "name": "shipping_address", "type": "object", "required": false, "description": "Updated shipping address" },
|
|
94
|
+
{ "name": "line_items", "type": "array", "required": false, "description": "Updated line items" }
|
|
95
|
+
]
|
|
96
|
+
},
|
|
97
|
+
"response_schema": "Order"
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
"method": "PATCH",
|
|
101
|
+
"path": "/api/v1/orders/:id/cancel",
|
|
102
|
+
"controller_order": 5,
|
|
103
|
+
"handler_name": "cancelOrder",
|
|
104
|
+
"required_scope": "order-create",
|
|
105
|
+
"summary": "Cancel an existing order",
|
|
106
|
+
"description": "Cancel an existing order with optional reason and restock settings.",
|
|
107
|
+
"path_params": [
|
|
108
|
+
{ "name": "id", "type": "string", "required": true, "description": "The order ID to cancel" }
|
|
109
|
+
],
|
|
110
|
+
"request_body": {
|
|
111
|
+
"content_type": "application/json",
|
|
112
|
+
"fields": [
|
|
113
|
+
{ "name": "cancel_reason", "type": "string", "required": false, "description": "Reason for cancellation" },
|
|
114
|
+
{ "name": "staff_note", "type": "string", "required": false, "description": "Internal note about the cancellation" },
|
|
115
|
+
{ "name": "restock_inventory", "type": "boolean", "required": false, "description": "Whether to restock inventory" },
|
|
116
|
+
{ "name": "send_notification", "type": "boolean", "required": false, "description": "Whether to send notification to customer" }
|
|
117
|
+
]
|
|
118
|
+
},
|
|
119
|
+
"response_schema": "Order"
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"method": "PATCH",
|
|
123
|
+
"path": "/api/v1/orders/:id/external-id",
|
|
124
|
+
"controller_order": 6,
|
|
125
|
+
"handler_name": "updateOrderExternalId",
|
|
126
|
+
"required_scope": "order-create",
|
|
127
|
+
"summary": "Update external ID for an order",
|
|
128
|
+
"description": "Updates the external_order_id field for a single order. Useful for syncing with external systems.",
|
|
129
|
+
"path_params": [
|
|
130
|
+
{ "name": "id", "type": "string", "required": true, "description": "The order ID" }
|
|
131
|
+
],
|
|
132
|
+
"request_body": {
|
|
133
|
+
"content_type": "application/json",
|
|
134
|
+
"fields": [
|
|
135
|
+
{ "name": "external_id", "type": "string", "required": true, "description": "External reference ID from your system" }
|
|
136
|
+
]
|
|
137
|
+
},
|
|
138
|
+
"response_schema": "Order"
|
|
139
|
+
}
|
|
140
|
+
],
|
|
141
|
+
"schemas": {
|
|
142
|
+
"Order": {
|
|
143
|
+
"id": "string — unique order identifier",
|
|
144
|
+
"order_number": "number — sequential order number",
|
|
145
|
+
"email": "string | null — customer email",
|
|
146
|
+
"phone": "string | null — customer phone",
|
|
147
|
+
"financial_status": "'pending' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'voided'",
|
|
148
|
+
"fulfillment_status": "'unfulfilled' | 'partial' | 'fulfilled' | 'partially_fulfilled' | 'restocked' | 'pending' | 'refunded' | 'returned'",
|
|
149
|
+
"status": "'open' | 'closed' | 'cancelled' | 'archived'",
|
|
150
|
+
"currency": "string — currency code (e.g. 'INR')",
|
|
151
|
+
"total_price": "number — final total price",
|
|
152
|
+
"subtotal_price": "number — subtotal before tax and discounts",
|
|
153
|
+
"total_tax": "number — total tax amount",
|
|
154
|
+
"total_discounts": "number — total discount amount",
|
|
155
|
+
"line_items": "LineItem[] — items in the order",
|
|
156
|
+
"customer": "Customer object",
|
|
157
|
+
"shipping_address": "Address | null",
|
|
158
|
+
"billing_address": "Address | null",
|
|
159
|
+
"note": "string | null — internal note",
|
|
160
|
+
"tags": "string — comma-separated tags",
|
|
161
|
+
"created_at": "string — ISO 8601 timestamp",
|
|
162
|
+
"updated_at": "string — ISO 8601 timestamp",
|
|
163
|
+
"cancelled_at": "string | null — ISO 8601 timestamp if cancelled"
|
|
164
|
+
}
|
|
165
|
+
},
|
|
166
|
+
"statuses": ["pending", "confirmed", "processing", "shipped", "delivered", "cancelled", "refunded"]
|
|
167
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
{
|
|
2
|
+
"resource": "products",
|
|
3
|
+
"base_url": "https://qa-os-ecosystem.dev.gokwik.io",
|
|
4
|
+
"auth": {
|
|
5
|
+
"type": "bearer",
|
|
6
|
+
"header": "Authorization",
|
|
7
|
+
"format": "Bearer <access_token>"
|
|
8
|
+
},
|
|
9
|
+
"endpoints": [
|
|
10
|
+
{
|
|
11
|
+
"method": "GET",
|
|
12
|
+
"path": "/api/v1/v1/products",
|
|
13
|
+
"controller_order": 1,
|
|
14
|
+
"handler_name": "getProducts",
|
|
15
|
+
"required_scope": "read_products",
|
|
16
|
+
"summary": "List products with pagination and filtering",
|
|
17
|
+
"description": "Retrieve a paginated list of products. Supports filtering by status, vendor, tags, category, collection, and search.",
|
|
18
|
+
"query_params": [
|
|
19
|
+
{ "name": "limit", "type": "number", "required": false, "default": 10, "description": "Number of products per page" },
|
|
20
|
+
{ "name": "page", "type": "number", "required": false, "default": 1, "description": "Page number for pagination" },
|
|
21
|
+
{ "name": "offset", "type": "number", "required": false, "default": 0, "description": "Offset for pagination" },
|
|
22
|
+
{ "name": "all", "type": "boolean", "required": false, "description": "Return all products (ignore pagination)" },
|
|
23
|
+
{ "name": "search", "type": "string", "required": false, "description": "Search products by title" },
|
|
24
|
+
{ "name": "status", "type": "string", "required": false, "enum": ["draft", "active", "archived"], "description": "Filter by product status" },
|
|
25
|
+
{ "name": "vendor", "type": "string", "required": false, "description": "Filter by vendor/brand name" },
|
|
26
|
+
{ "name": "categoryId", "type": "string", "required": false, "description": "Filter by category ID" },
|
|
27
|
+
{ "name": "collectionId", "type": "string", "required": false, "description": "Filter by collection ID" },
|
|
28
|
+
{ "name": "tagId", "type": "string", "required": false, "description": "Filter by tag ID" },
|
|
29
|
+
{ "name": "tags", "type": "string", "required": false, "description": "Filter by tags" },
|
|
30
|
+
{ "name": "published", "type": "boolean", "required": false, "description": "Filter by published status" },
|
|
31
|
+
{ "name": "show_variants", "type": "boolean", "required": false, "default": false, "description": "Include variant details in response" }
|
|
32
|
+
],
|
|
33
|
+
"request_body": null,
|
|
34
|
+
"response_schema": "ProductListResponse"
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"method": "GET",
|
|
38
|
+
"path": "/api/v1/v1/products/:id",
|
|
39
|
+
"controller_order": 2,
|
|
40
|
+
"handler_name": "getProductById",
|
|
41
|
+
"required_scope": "read_products",
|
|
42
|
+
"summary": "Get a single product by ID",
|
|
43
|
+
"description": "Retrieve the full details of a single product.",
|
|
44
|
+
"path_params": [
|
|
45
|
+
{ "name": "id", "type": "string", "required": true, "description": "The product ID" }
|
|
46
|
+
],
|
|
47
|
+
"query_params": [
|
|
48
|
+
{ "name": "show_variants", "type": "boolean", "required": false, "description": "Include variant details in response" }
|
|
49
|
+
],
|
|
50
|
+
"request_body": null,
|
|
51
|
+
"response_schema": "Product"
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"method": "POST",
|
|
55
|
+
"path": "/api/v1/v1/products",
|
|
56
|
+
"controller_order": 3,
|
|
57
|
+
"handler_name": "createProduct",
|
|
58
|
+
"required_scope": "write_products",
|
|
59
|
+
"summary": "Create a product",
|
|
60
|
+
"description": "Create a product in the merchant's store. The body must be wrapped in a { product: { ... } } object.",
|
|
61
|
+
"request_body": {
|
|
62
|
+
"content_type": "application/json",
|
|
63
|
+
"note": "The request body MUST be wrapped: { \"product\": { ... } }",
|
|
64
|
+
"fields": [
|
|
65
|
+
{ "name": "title", "type": "string", "required": true, "description": "Product title" },
|
|
66
|
+
{ "name": "body_html", "type": "string", "required": false, "description": "HTML description" },
|
|
67
|
+
{ "name": "handle", "type": "string", "required": false, "description": "URL-friendly slug" },
|
|
68
|
+
{ "name": "product_type", "type": "string", "required": false, "description": "Product type/category" },
|
|
69
|
+
{ "name": "vendor", "type": "string", "required": false, "description": "Manufacturer/brand" },
|
|
70
|
+
{ "name": "status", "type": "string", "required": false, "enum": ["draft", "active", "archived"], "description": "Product status" },
|
|
71
|
+
{ "name": "tags", "type": "string", "required": false, "description": "Comma-separated tags" },
|
|
72
|
+
{ "name": "price", "type": "number", "required": false, "description": "Price in paise (integer)" },
|
|
73
|
+
{ "name": "compare_at_price", "type": "number", "required": false, "description": "Compare-at price in paise" },
|
|
74
|
+
{ "name": "sku", "type": "string", "required": false, "description": "Stock keeping unit" },
|
|
75
|
+
{ "name": "barcode", "type": "string", "required": false, "description": "Barcode" },
|
|
76
|
+
{ "name": "weight", "type": "number", "required": false, "description": "Weight value" },
|
|
77
|
+
{ "name": "weight_unit", "type": "string", "required": false, "description": "Weight unit (kg, g, lb, oz)" },
|
|
78
|
+
{ "name": "charge_tax", "type": "boolean", "required": false, "description": "Charge tax on this product" },
|
|
79
|
+
{ "name": "track_inventory", "type": "boolean", "required": false, "description": "Track inventory" },
|
|
80
|
+
{ "name": "is_physical_product", "type": "boolean", "required": false, "description": "Is physical product" },
|
|
81
|
+
{ "name": "seo_title", "type": "string", "required": false, "description": "SEO title" },
|
|
82
|
+
{ "name": "seo_description", "type": "string", "required": false, "description": "SEO description" },
|
|
83
|
+
{ "name": "categoryId", "type": "string", "required": false, "description": "Category ID" },
|
|
84
|
+
{ "name": "collectionIds", "type": "string[]", "required": false, "description": "Collection IDs" },
|
|
85
|
+
{ "name": "tagIds", "type": "string[]", "required": false, "description": "Tag IDs" },
|
|
86
|
+
{ "name": "metadata", "type": "object", "required": false, "description": "Additional metadata" }
|
|
87
|
+
]
|
|
88
|
+
},
|
|
89
|
+
"response_schema": "Product"
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"method": "PUT",
|
|
93
|
+
"path": "/api/v1/v1/products/:id",
|
|
94
|
+
"controller_order": 4,
|
|
95
|
+
"handler_name": "updateProduct",
|
|
96
|
+
"required_scope": "write_products",
|
|
97
|
+
"summary": "Update a product",
|
|
98
|
+
"description": "Update product fields. Only provided fields are modified.",
|
|
99
|
+
"path_params": [
|
|
100
|
+
{ "name": "id", "type": "string", "required": true, "description": "The product ID to update" }
|
|
101
|
+
],
|
|
102
|
+
"request_body": {
|
|
103
|
+
"content_type": "application/json",
|
|
104
|
+
"fields": [
|
|
105
|
+
{ "name": "title", "type": "string", "required": false },
|
|
106
|
+
{ "name": "body_html", "type": "string", "required": false },
|
|
107
|
+
{ "name": "handle", "type": "string", "required": false },
|
|
108
|
+
{ "name": "product_type", "type": "string", "required": false },
|
|
109
|
+
{ "name": "vendor", "type": "string", "required": false },
|
|
110
|
+
{ "name": "status", "type": "string", "required": false, "enum": ["draft", "active", "archived"] },
|
|
111
|
+
{ "name": "tags", "type": "string", "required": false },
|
|
112
|
+
{ "name": "price", "type": "number", "required": false },
|
|
113
|
+
{ "name": "compare_at_price", "type": "number", "required": false },
|
|
114
|
+
{ "name": "sku", "type": "string", "required": false },
|
|
115
|
+
{ "name": "barcode", "type": "string", "required": false },
|
|
116
|
+
{ "name": "weight", "type": "number", "required": false },
|
|
117
|
+
{ "name": "weight_unit", "type": "string", "required": false },
|
|
118
|
+
{ "name": "seo_title", "type": "string", "required": false },
|
|
119
|
+
{ "name": "seo_description", "type": "string", "required": false },
|
|
120
|
+
{ "name": "categoryId", "type": "string", "required": false },
|
|
121
|
+
{ "name": "collectionIds", "type": "string[]", "required": false },
|
|
122
|
+
{ "name": "tagIds", "type": "string[]", "required": false },
|
|
123
|
+
{ "name": "metadata", "type": "object", "required": false }
|
|
124
|
+
]
|
|
125
|
+
},
|
|
126
|
+
"response_schema": "Product"
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"method": "DELETE",
|
|
130
|
+
"path": "/api/v1/v1/products/:id",
|
|
131
|
+
"controller_order": 5,
|
|
132
|
+
"handler_name": "deleteProduct",
|
|
133
|
+
"required_scope": "write_products",
|
|
134
|
+
"summary": "Delete a product",
|
|
135
|
+
"description": "Permanently delete a product from the merchant's store.",
|
|
136
|
+
"path_params": [
|
|
137
|
+
{ "name": "id", "type": "string", "required": true, "description": "The product ID to delete" }
|
|
138
|
+
],
|
|
139
|
+
"request_body": null,
|
|
140
|
+
"response_schema": null
|
|
141
|
+
}
|
|
142
|
+
],
|
|
143
|
+
"schemas": {
|
|
144
|
+
"Product": {
|
|
145
|
+
"id": "string — unique product identifier (UUID)",
|
|
146
|
+
"title": "string — product title",
|
|
147
|
+
"body_html": "string | null — HTML description",
|
|
148
|
+
"handle": "string — URL-friendly slug",
|
|
149
|
+
"product_type": "string | null — product type/category",
|
|
150
|
+
"vendor": "string | null — vendor/brand name",
|
|
151
|
+
"status": "'draft' | 'active' | 'archived'",
|
|
152
|
+
"tags": "string — comma-separated tags",
|
|
153
|
+
"price": "number — price in paise",
|
|
154
|
+
"compare_at_price": "number | null — compare-at price in paise",
|
|
155
|
+
"sku": "string | null — stock keeping unit",
|
|
156
|
+
"barcode": "string | null — barcode",
|
|
157
|
+
"weight": "number | null — weight value",
|
|
158
|
+
"weight_unit": "string | null — weight unit",
|
|
159
|
+
"published_at": "string | null — ISO 8601 timestamp",
|
|
160
|
+
"created_at": "string — ISO 8601 timestamp",
|
|
161
|
+
"updated_at": "string — ISO 8601 timestamp",
|
|
162
|
+
"variants": "Variant[] — product variants (when show_variants=true)",
|
|
163
|
+
"images": "Image[] — product images"
|
|
164
|
+
}
|
|
165
|
+
},
|
|
166
|
+
"statuses": ["draft", "active", "archived"]
|
|
167
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"flows": {
|
|
4
|
+
"authorization_code": {
|
|
5
|
+
"description": "Standard OAuth 2.0 Authorization Code flow for installing apps on merchant stores",
|
|
6
|
+
"steps": [
|
|
7
|
+
{
|
|
8
|
+
"step": 1,
|
|
9
|
+
"name": "Request Authorization Code",
|
|
10
|
+
"method": "POST",
|
|
11
|
+
"endpoint": "/api/v1/oauth/authorize",
|
|
12
|
+
"description": "Request an authorization code by providing client_id, merchant_id, redirect_uri, and scopes. The app must be published before this step.",
|
|
13
|
+
"request_body": {
|
|
14
|
+
"clientId": "string — Your app's client ID",
|
|
15
|
+
"redirectUri": "string — Registered redirect URI",
|
|
16
|
+
"merchantId": "string — Merchant ID of the store installing the app",
|
|
17
|
+
"scopes": "string[] — Array of scopes to request (e.g. ['read_orders'])"
|
|
18
|
+
},
|
|
19
|
+
"response": {
|
|
20
|
+
"code": "string — Authorization code (expires quickly)",
|
|
21
|
+
"redirectUri": "string — The redirect URI",
|
|
22
|
+
"expiresAt": "string — ISO 8601 expiry timestamp"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"step": 2,
|
|
27
|
+
"name": "Exchange Code for Tokens",
|
|
28
|
+
"method": "POST",
|
|
29
|
+
"endpoint": "/api/v1/oauth/token",
|
|
30
|
+
"description": "Exchange the authorization code for access and refresh tokens. Must be called immediately — the code expires quickly.",
|
|
31
|
+
"request_body": {
|
|
32
|
+
"grant_type": "authorization_code",
|
|
33
|
+
"code": "string — The authorization code from step 1",
|
|
34
|
+
"clientId": "string — Your app's client ID",
|
|
35
|
+
"clientSecret": "string — Your app's client secret",
|
|
36
|
+
"redirectUri": "string — Must match step 1"
|
|
37
|
+
},
|
|
38
|
+
"response": {
|
|
39
|
+
"access_token": "string — Bearer token for API calls",
|
|
40
|
+
"token_type": "Bearer",
|
|
41
|
+
"expires_in": "number — Seconds until token expires",
|
|
42
|
+
"refresh_token": "string — Token for refreshing access",
|
|
43
|
+
"scope": "string — Granted scopes (comma-separated)",
|
|
44
|
+
"merchant_id": "string — Merchant ID"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"step": 3,
|
|
49
|
+
"name": "Refresh Token",
|
|
50
|
+
"method": "POST",
|
|
51
|
+
"endpoint": "/api/v1/oauth/token",
|
|
52
|
+
"description": "Use the refresh token to get a new access token when the current one expires.",
|
|
53
|
+
"request_body": {
|
|
54
|
+
"grant_type": "refresh_token",
|
|
55
|
+
"refresh_token": "string — The refresh token",
|
|
56
|
+
"clientId": "string — Your app's client ID",
|
|
57
|
+
"clientSecret": "string — Your app's client secret"
|
|
58
|
+
},
|
|
59
|
+
"response": {
|
|
60
|
+
"access_token": "string — New bearer token",
|
|
61
|
+
"token_type": "Bearer",
|
|
62
|
+
"expires_in": "number — Seconds until new token expires",
|
|
63
|
+
"refresh_token": "string — New refresh token",
|
|
64
|
+
"scope": "string — Granted scopes",
|
|
65
|
+
"merchant_id": "string — Merchant ID"
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|