@crossly/mcp 0.0.0-stage → 0.1.0

package/dist/tools/offers.js

@@ -0,0 +1,76 @@
+import { apiGet, apiPost } from '../api.js';
+import { IDEMPOTENCY_PROP } from './types.js';
+/**
+ * Offers on the seller's OWN Crossly marketplace listings.
+ *
+ * Not the same thing as `respond_to_offer` in the inbox tools, which acts on
+ * an offer attached to a conversation on an external marketplace. Crossly
+ * offers are standalone rows and a buyer can build one covering several
+ * listings at once, which a conversation-scoped single-listing shape cannot
+ * represent.
+ */
+export const offersTools = [
+    {
+        name: 'list_crossly_offers',
+        description: "List buyer offers on the seller's own Crossly marketplace listings, newest first. " +
+            'Each offer may cover SEVERAL listings — a buyer-built bundle — in which case `isBundle` is true and ' +
+            '`items` holds every listing it covers. `amountCents` is the price offered for the WHOLE set, and ' +
+            '`listedTotalCents` is what those items were asking when the offer was made, so the two are directly ' +
+            'comparable. Filter with `status` to triage (e.g. "pending" for what needs a decision, "accepted" for ' +
+            'what is awaiting payment). An accepted offer with `consumedAt` set has already been paid for.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'accepted', 'declined', 'countered', 'expired', 'withdrawn'],
+                    description: 'Filter to one status. Omit for all.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 200,
+                    description: 'Max offers to return. Default 50.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: (args) => apiGet('/v1/offers', { status: args.status, limit: args.limit }),
+    },
+    {
+        name: 'respond_to_crossly_offer',
+        description: 'Accept, decline, or counter a PENDING offer on a Crossly marketplace listing. ' +
+            '`action="accept"` grants the buyer a one-time right to buy every item the offer covers at the agreed ' +
+            'price — it does not itself take payment; the buyer still has to complete checkout. ' +
+            '`action="counter"` requires `counterCents` and opens a new offer over the SAME set of items. ' +
+            '`action="decline"` closes it. Only pending, unexpired offers can be responded to. ' +
+            'Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Offer UUID (from list_crossly_offers).' },
+                action: {
+                    type: 'string',
+                    enum: ['accept', 'decline', 'counter'],
+                    description: 'What to do with the offer.',
+                },
+                counterCents: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Required when action="counter". Your asking price in cents for the whole set of items.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id', 'action'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, action, counterCents } = args;
+            // Only send counterCents on a counter — the route's union schema rejects
+            // it on accept/decline rather than ignoring it.
+            const body = action === 'counter' ? { action, counterCents } : { action };
+            return apiPost(`/v1/offers/${encodeURIComponent(id)}/respond`, body, idempotencyKey);
+        },
+    },
+];
+//# sourceMappingURL=offers.js.map

package/dist/tools/offers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offers.js","sourceRoot":"","sources":["../../src/tools/offers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAW,MAAM,YAAY,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC;QACE,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,oFAAoF;YACpF,sGAAsG;YACtG,mGAAmG;YACnG,sGAAsG;YACtG,uGAAuG;YACvG,+FAA+F;QACjG,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC;oBAC9E,WAAW,EAAE,qCAAqC;iBACnD;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,GAAG;oBACZ,WAAW,EAAE,mCAAmC;iBACjD;aACF;YACD,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;KACpF;IACD;QACE,IAAI,EAAE,0BAA0B;QAChC,WAAW,EACT,gFAAgF;YAChF,uGAAuG;YACvG,qFAAqF;YACrF,+FAA+F;YAC/F,oFAAoF;YACpF,oCAAoC;QACtC,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wCAAwC,EAAE;gBAC7E,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;oBACtC,WAAW,EAAE,4BAA4B;iBAC1C;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,CAAC;oBACV,WAAW,EACT,wFAAwF;iBAC3F;gBACD,GAAG,gBAAgB;aACpB;YACD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC;YAC1B,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,MAAM,EAAE,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAKpD,CAAC;YACF,yEAAyE;YACzE,gDAAgD;YAChD,MAAM,IAAI,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;YAC1E,OAAO,OAAO,CAAC,cAAc,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACvF,CAAC;KACF;CACF,CAAC"}

package/dist/tools/orders/actions.d.ts

@@ -0,0 +1,4 @@
+import { ToolDef } from '../types.js';
+/** Per-order actions that reach out to the marketplace: cancel, message, tracking, refund. */
+export declare const orderActions: ToolDef[];
+//# sourceMappingURL=actions.d.ts.map

package/dist/tools/orders/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/tools/orders/actions.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,8FAA8F;AAC9F,eAAO,MAAM,YAAY,EAAE,OAAO,EAyIjC,CAAC"}

package/dist/tools/orders/actions.js

@@ -0,0 +1,126 @@
+import { apiPost } from '../../api.js';
+import { IDEMPOTENCY_PROP } from '../types.js';
+/** Per-order actions that reach out to the marketplace: cancel, message, tracking, refund. */
+export const orderActions = [
+    {
+        name: 'cancel_order',
+        description: 'Cancel an order on its marketplace (eBay, Etsy, Shopify, OfferUp, Poshmark, Mercari). ' +
+            'DESTRUCTIVE and usually irreversible — confirm with the user first, and call check_cancel_eligibility ' +
+            'to pick a valid reason. ' +
+            'IMPORTANT: a 200 does NOT mean the marketplace cancelled anything. The Crossly order is always flipped ' +
+            'to cancelled; read `platformCancel` to see what actually happened — "sent" (marketplace confirmed), ' +
+            '"queued" (async job), "failed" (marketplace refused; `error` has its message verbatim), "unsupported" ' +
+            '(no wire — tell the user to cancel on the marketplace themselves), "no_platform_order_id", or ' +
+            '"already_cancelled". Report that outcome to the user rather than a blanket success.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Order UUID from list_orders.' },
+                reason: {
+                    type: 'string',
+                    description: 'Marketplace reason code, e.g. eBay OUT_OF_STOCK_OR_CANNOT_FULFILL / BUYER_ASKED_CANCEL / ' +
+                        'ADDRESS_ISSUES. Take it from check_cancel_eligibility rather than guessing.',
+                },
+                idempotencyKey: { type: 'string', description: 'Optional; prevents a double cancel on retry.' },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/cancel`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'message_buyer',
+        description: "Send a message to an order's buyer on the marketplace. eBay only — every other platform can only reply " +
+            'inside a thread the buyer started, so use the inbox tools there. The message is also saved to the Crossly ' +
+            "inbox on the same thread the buyer's reply will land on. Fails with buyer_username_pending if the buyer " +
+            "handle hasn't arrived yet (it lands moments after the sale).",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Order UUID from list_orders.' },
+                body: { type: 'string', description: 'Message text, max 2000 chars.' },
+                subject: { type: 'string', description: 'Optional subject; defaults to the order id.' },
+                idempotencyKey: { type: 'string', description: 'Optional; prevents a duplicate send on retry.' },
+            },
+            required: ['id', 'body'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/message`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'submit_tracking',
+        description: 'Mark an order shipped by submitting a tracking number + carrier to the originating marketplace. ' +
+            'Dispatches an async platform job (eBay Fulfillment API for eBay, extension job for cookie platforms, etc.). ' +
+            'Carrier must be a slug the platform recognises ("usps", "ups", "fedex", "dhl"). ' +
+            'ALWAYS pass an idempotencyKey on retries — duplicate submissions can confuse buyers.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. " +
+                        'The route looks the platform order id up itself before dispatching.',
+                },
+                trackingNumber: { type: 'string', description: 'Carrier tracking number exactly as the carrier issued it.' },
+                carrier: {
+                    type: 'string',
+                    description: 'Carrier slug, e.g. "usps", "ups", "fedex", "dhl". The dispatcher maps to per-platform codes.',
+                },
+                labelCost: {
+                    type: 'number',
+                    description: 'Optional. What the seller paid for this postage, in dollars (e.g. 4.85) — for a label bought outside ' +
+                        'Crossly. Recorded on the parcel and counted against the sale’s net profit.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id', 'trackingNumber', 'carrier'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/tracking`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'issue_refund',
+        description: 'Refund an order via the originating marketplace\'s API. Full refund if amount is omitted; partial otherwise. ' +
+            'Some platforms require a reason string. Returns the platform\'s refund response (or a refund_failed error). ' +
+            'IRREVERSIBLE on most platforms — confirm with the user before calling. Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId.",
+                },
+                amount: {
+                    type: 'number',
+                    description: 'Partial refund amount in DOLLARS, not cents — 12.5 means $12.50, matching the decimal ' +
+                        'dollars the linked sale row stores (order money lives on `sales`). Must be > 0 and is ' +
+                        'written back as the refunded amount. Omit for a FULL refund.',
+                    exclusiveMinimum: 0,
+                },
+                reason: {
+                    type: 'string',
+                    maxLength: 500,
+                    description: 'Free-text reason, max 500 chars. Some platforms require one (eBay) and map it onto their own ' +
+                        'reason enum; it is also stored on the order as refundReason.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/refund`, body, idempotencyKey);
+        },
+    },
+];
+//# sourceMappingURL=actions.js.map

package/dist/tools/orders/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../../src/tools/orders/actions.ts"],"names":[],"mappings":"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"}

package/dist/tools/orders/bulk.d.ts

@@ -0,0 +1,4 @@
+import { ToolDef } from '../types.js';
+/** Multi-select bar operations — every one takes a list of OUR order UUIDs. */
+export declare const orderBulk: ToolDef[];
+//# sourceMappingURL=bulk.d.ts.map

package/dist/tools/orders/bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.d.ts","sourceRoot":"","sources":["../../../src/tools/orders/bulk.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,+EAA+E;AAC/E,eAAO,MAAM,SAAS,EAAE,OAAO,EAuJ9B,CAAC"}

package/dist/tools/orders/bulk.js

@@ -0,0 +1,145 @@
+import { apiPost } from '../../api.js';
+import { IDEMPOTENCY_PROP } from '../types.js';
+/** Multi-select bar operations — every one takes a list of OUR order UUIDs. */
+export const orderBulk = [
+    {
+        name: 'orders_bulk_delete',
+        description: 'Bulk soft- or hard-delete orders by id. Default behaviour sets deleted_at = now() so the cookie-sales poller will not ' +
+            're-create them on its next tick; pass hardDelete=true to remove rows outright (rare — reserved for legitimate test data). ' +
+            'Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: 500,
+                    description: "Crossly order UUIDs from list_orders — OUR ids, not the marketplaces' platformOrderIds. " +
+                        '1-500 per call (the server rejects more). Ids the caller does not own are ignored; the ' +
+                        'response reports how many rows were actually affected.',
+                },
+                hardDelete: { type: 'boolean', default: false, description: 'true = DELETE row; false = soft delete (default).' },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['orderIds'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/bulk-delete', body, idempotencyKey);
+        },
+    },
+    {
+        name: 'orders_bulk_mark_shipped',
+        description: 'Bulk-flip a selection of orders to status=shipped. Does NOT call any platform API — use submit_tracking per order for ' +
+            'platform-side shipping. Optionally stamps tracking/carrier on each row. Fires order.shipped automation triggers and ' +
+            'pushes a WebSocket update. Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Crossly order UUIDs from list_orders (OUR ids, not platformOrderIds), 1-500 per call. ' +
+                        'Already-closed orders are skipped by the shared bulk-mark-shipped guard rather than flipped.',
+                },
+                trackingNumber: {
+                    type: 'string',
+                    description: 'Optional shared tracking number stamped on EVERY selected row, max 100 chars. Only ' +
+                        'meaningful when the whole selection really shipped in one parcel — otherwise leave it out ' +
+                        'and use submit_tracking per order.',
+                },
+                carrier: {
+                    type: 'string',
+                    description: 'Optional shared carrier slug ("usps", "ups", "fedex", "dhl"), max 40 chars, stamped on every selected row.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['orderIds'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/bulk-mark-shipped', body, idempotencyKey);
+        },
+    },
+    {
+        name: 'orders_bulk_mark_disputed',
+        description: 'Bulk flag orders as disputed with a shared reason. Sets isDisputed=true, status=disputed, and stores the reason. Does ' +
+            'NOT open a case on the marketplace — use the platform UI for that. Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Crossly order UUIDs from list_orders (OUR ids, not platformOrderIds), 1-500 per call.',
+                },
+                reason: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 1000,
+                    description: 'Why these orders are disputed — free text, 1-1000 chars, stored as disputeReason on every ' +
+                        'selected row. Not a marketplace reason code, and never sent to the marketplace.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['orderIds', 'reason'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/bulk-mark-disputed', body, idempotencyKey);
+        },
+    },
+    {
+        name: 'orders_bulk_export',
+        description: 'Export a selection of orders as CSV. Returns the CSV text body — caller should treat it as a string. Useful for ' +
+            'accounting handoffs. Read-only (no idempotency needed but accepted for forward-compat).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Crossly order UUIDs from list_orders (OUR ids, not platformOrderIds), 1-500 per call. ' +
+                        'Orders the caller does not own, and soft-deleted ones, are silently left out of the CSV. ' +
+                        'The money columns come off the linked sale row and are DOLLARS as decimal strings — Sale ' +
+                        'Price "45.99" is $45.99, likewise Platform Fee and Label Cost. Nothing in this CSV is cents.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['orderIds'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/bulk-export', body, idempotencyKey);
+        },
+    },
+    {
+        name: 'orders_bulk_packing_slips',
+        description: 'Generate one bulk PDF containing packing slips for every order in the selection (one slip per page). Pass an ' +
+            'idempotencyKey for cache-replay safety.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Crossly order UUIDs from list_orders (OUR ids, not platformOrderIds). 1-50 per call — this ' +
+                        'endpoint caps at 50, lower than the other bulk order tools, so split a bigger selection.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['orderIds'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/bulk-packing-slips', body, idempotencyKey);
+        },
+    },
+];
+//# sourceMappingURL=bulk.js.map

package/dist/tools/orders/bulk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.js","sourceRoot":"","sources":["../../../src/tools/orders/bulk.ts"],"names":[],"mappings":"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"}

package/dist/tools/orders/fulfillment.d.ts

@@ -0,0 +1,4 @@
+import { ToolDef } from '../types.js';
+/** Single-order verbs: patch, dispute, rates/labels, history import. */
+export declare const orderFulfillment: ToolDef[];
+//# sourceMappingURL=fulfillment.d.ts.map

package/dist/tools/orders/fulfillment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fulfillment.d.ts","sourceRoot":"","sources":["../../../src/tools/orders/fulfillment.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,EAAE,OAAO,EA6QrC,CAAC"}

package/dist/tools/orders/fulfillment.js

@@ -0,0 +1,240 @@
+import { apiPatch, apiPost } from '../../api.js';
+import { IDEMPOTENCY_PROP } from '../types.js';
+/** Single-order verbs: patch, dispute, rates/labels, history import. */
+export const orderFulfillment = [
+    {
+        name: 'order_update',
+        description: 
+        // Advertised "cancelled/returned" for a long time. Neither is in
+        // OrderStatusEnum (routes/orders.ts) — the route 400s on both — so an
+        // agent reading this description would pick a value it had just been
+        // told was supported and get a validation error it could not explain.
+        // The list below is that enum, verbatim.
+        'PATCH a single order — set status/notes/trackingNumber. Transitions to shipped/delivered/completed/disputed/refunded ' +
+            'fire the matching webhook and automation triggers. Submitting trackingNumber also dispatches platform-side ' +
+            'submit-tracking when a platformOrderId is present. Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. Must " +
+                        'be a real UUID or the call fails with invalid_order_id; a soft-deleted order reads as 404.',
+                },
+                status: {
+                    type: 'string',
+                    // Mirrors OrderStatusEnum. Stated as an enum as well as in prose so
+                    // a wrong value is impossible to construct, not merely documented.
+                    enum: [
+                        'needs_fulfillment',
+                        'label_purchased',
+                        'shipped',
+                        'in_transit',
+                        'delivered',
+                        'completed',
+                        'disputed',
+                        'refunded',
+                    ],
+                    description: 'New fulfillment status. This endpoint accepts exactly: "needs_fulfillment" (in the ship ' +
+                        'queue — the state a new sale lands in), "label_purchased" (label bought, parcel not handed ' +
+                        'over yet), "shipped" (stamps shippedAt, moves the item out of Reserved, and tells the ' +
+                        'marketplace when the order has a platformOrderId), "in_transit", "delivered" (stamps ' +
+                        'deliveredAt), "completed" (closed out), "disputed", "refunded" (also stamps the linked sale ' +
+                        'row so it stops counting as revenue). Any other value is rejected. Omit to leave status alone.',
+                },
+                notes: {
+                    type: 'string',
+                    description: "Internal seller note, max 2000 chars. REPLACES the existing note — it is not appended. " +
+                        'Private: never shown to the buyer or sent to the marketplace.',
+                },
+                trackingNumber: {
+                    type: 'string',
+                    description: 'Carrier tracking number, max 100 chars. Supplying it IMPLIES status=shipped even if status ' +
+                        'is omitted, and dispatches a platform-side submit-tracking job when the order has a ' +
+                        'platformOrderId.',
+                },
+                labelCost: {
+                    type: 'number',
+                    description: 'What the seller paid for postage they bought themselves, in dollars. With trackingNumber it is ' +
+                        'that parcel’s cost; alone, it sets the cost on the order’s existing tracking. Counted against ' +
+                        'the sale’s net profit.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPatch(`/v1/orders/${encodeURIComponent(id)}`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'order_dispute',
+        description: 'Flag a single order as disputed with a reason and optional platformCaseId. Sets isDisputed=true, status=disputed, ' +
+            'and pushes an ORDER_STATUS_UPDATE. Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. " +
+                        'Must be a real UUID or the call fails with invalid_order_id.',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Why the order is disputed — free text, 1-1000 chars (e.g. "buyer opened an item-not-as-' +
+                        'described case"). Stored on the order and fires the order.disputed trigger.',
+                },
+                platformCaseId: {
+                    type: 'string',
+                    description: "The MARKETPLACE's own case/claim identifier (eBay case id, PayPal dispute id, Etsy case " +
+                        'number), max 200 chars — a different id space from both the Crossly order UUID and ' +
+                        'platformOrderId. Omit when the dispute was not raised through a platform case.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id', 'reason'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/dispute`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'order_rates',
+        description: 'EasyPost rate quote for an order. Provide weightOz and (length/width/height in inches), or a presetId. The seller\'s ' +
+            'default ship-from address is used. Returns an array of available rates with carrier/service/price. Pass an ' +
+            'idempotencyKey on retries (rate fetches are cheap but rate-limited).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. The " +
+                        "buyer's address on that order is the ship-to.",
+                },
+                weightOz: {
+                    type: 'number',
+                    description: 'Total packed weight in OUNCES — not pounds, not grams. Greater than 0 and at most 1120 ' +
+                        '(~70 lb). Required: every quoted rate is priced off it.',
+                },
+                lengthIn: {
+                    type: 'number',
+                    description: 'Parcel length in INCHES, greater than 0 and at most 108. Omit all three dimensions and ' +
+                        'Crossly auto-picks the parcel it thinks the item ships in (smallest saved box that fits, ' +
+                        "else the item's own dimensions).",
+                },
+                widthIn: {
+                    type: 'number',
+                    description: 'Parcel width in INCHES, greater than 0 and at most 108. See lengthIn for the omit-all behaviour.',
+                },
+                heightIn: {
+                    type: 'number',
+                    description: 'Parcel height in INCHES, greater than 0 and at most 108. See lengthIn for the omit-all behaviour.',
+                },
+                presetId: {
+                    type: 'string',
+                    description: "UUID of one of the seller's saved package presets to source dimensions from. Must belong " +
+                        'to this seller or the call 404s with preset_not_found. Any dimension passed explicitly ' +
+                        'wins over the preset; the preset only fills the blanks.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id', 'weightOz'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/rates`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'order_label',
+        description: 'Purchase a shipping label via EasyPost using a rateId returned by order_rates. CHARGES the seller — confirm before ' +
+            'calling. Once the label is bought we automatically push the tracking number to the originating platform. Pass an ' +
+            'idempotencyKey to make retries safe.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. Must " +
+                        'be the SAME order the rate was quoted for.',
+                },
+                rateId: {
+                    type: 'string',
+                    description: 'The `id` of the chosen entry in the order_rates response (the carrier\'s rate object id, ' +
+                        'e.g. "rate_..."), NOT a carrier or service name. Buying it charges the seller\'s prepaid ' +
+                        "shipping wallet the rate's price in DOLLARS plus a 5% markup; too small a balance comes " +
+                        'back as an error carrying requiredCents and balanceCents, which are CENTS.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id', 'rateId'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/label`, body, idempotencyKey);
+        },
+    },
+    {
+        name: 'order_pull_platform_label',
+        description: 'Fetch a pre-paid label from cookie-platforms that ship one with the order (Poshmark, Mercari). Stores the URL on the ' +
+            'order row + pushes an ORDER_STATUS_UPDATE. Refuses with 400/platform_does_not_provide_label for platforms without ' +
+            'pre-paid labels — use order_rates + order_label instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: "Crossly order UUID from list_orders — OUR id, not the marketplace's platformOrderId. The " +
+                        'order must already carry a platformOrderId (400 missing_platform_order_id otherwise), ' +
+                        'since that is what the marketplace is asked for the label with.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { id, idempotencyKey } = args;
+            return apiPost(`/v1/orders/${encodeURIComponent(id)}/pull-platform-label`, {}, idempotencyKey);
+        },
+    },
+    {
+        name: 'import_order_history',
+        description: "Manually (re-)pull a connected platform's order history for a day-window. Independent of the " +
+            'one-time post-connect backfill (set_history_import_window) — safe to call repeatedly, since ' +
+            'sale detection dedupes on (platform, platformOrderId, userId): re-importing an already-known ' +
+            'order is a no-op, only genuinely new or previously-out-of-window ones land. days: null = All ' +
+            'time (no limit), a positive integer = days back. No zero/"None" — this call always means "go ' +
+            'get me something". Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    description: 'Marketplace slug to re-pull, e.g. "ebay", "etsy", "poshmark", "mercari" — one per call, and ' +
+                        'it must be a platform this seller has actually connected.',
+                },
+                days: {
+                    type: ['integer', 'null'],
+                    description: 'How far back to reach, in DAYS: a positive integer up to 3650 (10 years), or null for all ' +
+                        'time. Required and has no zero/"none" — this call always means "go get me something". ' +
+                        'Anything already known dedupes on (platform, platformOrderId, userId), so a repeat is a no-op.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['platform', 'days'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/orders/import', body, idempotencyKey);
+        },
+    },
+];
+//# sourceMappingURL=fulfillment.js.map