askell-mcp 0.4.6 → 0.4.9

package/README.md

@@ -126,7 +126,7 @@ Typical agent workflow:
 ## API notes (short)
 
 - **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
-- **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
+- **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs, fulfillment orders under `/v2/`
 - **v2 discounts** — coupons: `GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount` (one active). Quotes take `promotion_code` and, for an existing buyer, `customer` (id) so combo discounts + promo restrictions apply. First-period totals already include coupon + combo; `quote.recurring_*` include combo but not the coupon (`discount.recurring_final_amount` while the coupon is active). Recurring `finalize` needs a verified payment method even when due-now is 0. Not the v1 `discount` 0–100 field.
 - Paths use **trailing slashes**
 - Prefer **v2** for new integrations; v1 remains for existing ones

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.6",
+  "version": "0.4.9",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -67,6 +67,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.6.2"
+    "zod": "4.6.5"
   }
 }

package/spec/openapi-v2.json

@@ -55,6 +55,10 @@
     {
       "name": "V2 Billing Runs",
       "description": "Subscription V2 billing-run read and retry APIs, requires secret api key."
+    },
+    {
+      "name": "V2 Fulfillment",
+      "description": "Subscription V2 fulfillment order read APIs for warehouse integrations, requires secret api key."
     }
   ],
   "paths": {
@@ -1672,6 +1676,119 @@
           }
         ]
       }
+    },
+    "/v2/fulfillment-orders/": {
+      "get": {
+        "tags": [
+          "V2 Fulfillment"
+        ],
+        "summary": "List fulfillment orders",
+        "description": "Returns the authenticated account's fulfillment orders, newest first, with the same body the `fulfillment_order.*` webhooks carry. Intended for backfill and for polling-based reconciliation after a missed webhook delivery. Read-only. Requires a secret key, that the account uses subscription contracts, and that shipping is enabled for the account.",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "status",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "open",
+                "partially_fulfilled",
+                "fulfilled",
+                "cancelled"
+              ]
+            },
+            "description": "Filter by fulfillment status."
+          },
+          {
+            "in": "query",
+            "name": "contract",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Filter by subscription contract id."
+          },
+          {
+            "in": "query",
+            "name": "customer",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Filter by customer id."
+          },
+          {
+            "in": "query",
+            "name": "customer_reference",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by customer reference."
+          },
+          {
+            "in": "query",
+            "name": "updated_since",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "description": "Only orders changed at or after this ISO 8601 timestamp. A bare date means the start of that day. This is the reconciliation filter: poll it with the `updated_at` of the last order you processed."
+          },
+          {
+            "in": "query",
+            "name": "created_since",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "description": "Only orders created at or after this ISO 8601 timestamp. A bare date means the start of that day."
+          },
+          {
+            "$ref": "#/components/parameters/PageSizeFilter"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/V2FulfillmentOrderList"
+          },
+          "403": {
+            "$ref": "#/components/responses/V2PermissionDenied"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/fulfillment-orders/{fulfillmentOrderId}/": {
+      "get": {
+        "tags": [
+          "V2 Fulfillment"
+        ],
+        "summary": "Get a fulfillment order",
+        "description": "Returns one fulfillment order belonging to the authenticated account, with its lines, delivery address, shipping selection and booked shipments. Orders belonging to another account return `404`. Read-only. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2FulfillmentOrderId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/V2FulfillmentOrder"
+          },
+          "403": {
+            "$ref": "#/components/responses/V2PermissionDenied"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -3105,7 +3222,7 @@
         "properties": {
           "option": {
             "type": "integer",
-            "description": "Id of one of the account's active shipping options."
+            "description": "Id of one of the account's active shipping options. An option with a rate table is priced for the delivery address's zip code (the request's `delivery_address`, else the customer's address) and the weight of the goods; when the table has no rate for that delivery the request fails with `400`, `shipping` describing why and `shipping_code` `shipping_not_available`."
           },
           "location_id": {
             "type": "string",
@@ -3164,6 +3281,14 @@
           "currency": {
             "type": "string"
           },
+          "zone_name": {
+            "type": "string",
+            "description": "The shipping zone that priced the selection, or an empty string when the option is flat-priced or the rate applied to every zip code."
+          },
+          "weight_band": {
+            "type": "string",
+            "description": "The weight band that priced the selection as `min-max` in grams (`max` empty for an open-ended band), or an empty string for a flat-priced option."
+          },
           "location_id": {
             "type": "string"
           },
@@ -3172,6 +3297,51 @@
           },
           "location_address": {
             "type": "string"
+          },
+          "location": {
+            "$ref": "#/components/schemas/V2PickupLocation"
+          }
+        }
+      },
+      "V2PickupLocation": {
+        "type": "object",
+        "nullable": true,
+        "description": "The chosen pickup location as a structured block an external fulfillment system can book against, or null when the selection has none (home delivery, freight, store pickup without an address). Derived from the shipping provider's own payload, with the flat `location_*` values as the fallback.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The provider's id for the location."
+          },
+          "name": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string",
+            "description": "One-line address, composed from street, zip code and town when the provider does not supply one."
+          },
+          "street": {
+            "type": "string"
+          },
+          "zip_code": {
+            "type": "string"
+          },
+          "town": {
+            "type": "string"
+          },
+          "external_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "The location's id in the provider's upstream system, when it exposes one."
+          },
+          "latitude": {
+            "type": "number",
+            "format": "double",
+            "nullable": true
+          },
+          "longitude": {
+            "type": "number",
+            "format": "double",
+            "nullable": true
           }
         }
       },
@@ -3765,6 +3935,25 @@
             "type": "string",
             "format": "decimal"
           },
+          "shipping_fee": {
+            "type": "object",
+            "nullable": true,
+            "description": "Sendingargjald sem er hluti af checkout-samtölunum, eða null.",
+            "properties": {
+              "amount": {
+                "type": "string"
+              },
+              "subtotal_amount": {
+                "type": "string"
+              },
+              "tax_amount": {
+                "type": "string"
+              },
+              "total_amount": {
+                "type": "string"
+              }
+            }
+          },
           "contract_id": {
             "type": "integer",
             "nullable": true
@@ -3932,6 +4121,25 @@
             "type": "string",
             "format": "decimal"
           },
+          "shipping_fee": {
+            "type": "object",
+            "nullable": true,
+            "description": "Sendingargjald sem er hluti af tilboðinu (samtölur innihalda það), eða null.",
+            "properties": {
+              "amount": {
+                "type": "string"
+              },
+              "subtotal_amount": {
+                "type": "string"
+              },
+              "tax_amount": {
+                "type": "string"
+              },
+              "total_amount": {
+                "type": "string"
+              }
+            }
+          },
           "first_period_recurring_subtotal_amount": {
             "type": "string",
             "format": "decimal"
@@ -4582,6 +4790,211 @@
           }
         }
       },
+      "V2FulfillmentAddress": {
+        "type": "object",
+        "nullable": true,
+        "description": "The delivery address as it stood when the order was created. This is the order's own snapshot, so editing the contract's address afterwards does not change it.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string"
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string"
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "state": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 country code."
+          }
+        }
+      },
+      "V2FulfillmentOrderLine": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "product_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "product_reference": {
+            "type": "string",
+            "nullable": true,
+            "description": "The seller's own product reference, i.e. the SKU a warehouse picks by. Null when the catalog product has been deleted."
+          },
+          "product_name": {
+            "type": "string",
+            "description": "Product name at the time the order was created."
+          },
+          "quantity": {
+            "type": "integer"
+          },
+          "quantity_fulfilled": {
+            "type": "integer",
+            "description": "How many units have been included in a shipment."
+          }
+        }
+      },
+      "V2Fulfillment": {
+        "type": "object",
+        "description": "A shipment booked for (part of) an order.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "order_id": {
+            "type": "integer"
+          },
+          "handler": {
+            "type": "string",
+            "enum": [
+              "dropp",
+              "posturinn",
+              "store_pickup"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "booked",
+              "failed",
+              "shipped",
+              "delivered",
+              "cancelled"
+            ]
+          },
+          "provider_order_id": {
+            "type": "string",
+            "description": "The provider's own identifier for the shipment, such as a Dropp order UUID or a Pósturinn shipment id."
+          },
+          "tracking_number": {
+            "type": "string"
+          },
+          "weight_grams": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Package weight used for the booking."
+          },
+          "error": {
+            "type": "string",
+            "description": "The last booking error, empty when the booking succeeded."
+          },
+          "booked_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "V2FulfillmentOrder": {
+        "type": "object",
+        "description": "A physical order generated by a paid billing run. This is also the body of the `fulfillment_order.*` webhooks.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "number": {
+            "type": "integer",
+            "description": "Per-account sequential order number."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "open",
+              "partially_fulfilled",
+              "fulfilled",
+              "cancelled"
+            ]
+          },
+          "contract_id": {
+            "type": "integer"
+          },
+          "billing_run_id": {
+            "type": "integer",
+            "description": "The successful billing run that generated this order. Each run generates at most one order."
+          },
+          "customer_id": {
+            "type": "integer"
+          },
+          "customer_reference": {
+            "type": "string"
+          },
+          "customer_name": {
+            "type": "string"
+          },
+          "customer_email": {
+            "type": "string",
+            "nullable": true
+          },
+          "delivery_address": {
+            "$ref": "#/components/schemas/V2FulfillmentAddress"
+          },
+          "shipping_selection": {
+            "$ref": "#/components/schemas/V2ShippingSelection"
+          },
+          "lines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/V2FulfillmentOrderLine"
+            }
+          },
+          "fulfillments": {
+            "type": "array",
+            "description": "Shipments booked for this order. Empty until one is booked, and always empty for an account with no shipping providers configured.",
+            "items": {
+              "$ref": "#/components/schemas/V2Fulfillment"
+            }
+          },
+          "estimated_weight_grams": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Sum of the products' chargeable unit weights, or null when any line lacks weight data, so a partial estimate is never mistaken for a total."
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/V2Metadata"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
       "V2SubscriptionContractCustomer": {
         "type": "object",
         "properties": {
@@ -5108,6 +5521,17 @@
           "type": "integer"
         }
       },
+      "V2FulfillmentOrderId": {
+        "name": "fulfillmentOrderId",
+        "in": "path",
+        "description": "Fulfillment order id. This is the order's `id`, not its per-account `number`.",
+        "required": true,
+        "style": "simple",
+        "explode": false,
+        "schema": {
+          "type": "integer"
+        }
+      },
       "V2CustomerReference": {
         "name": "customerReference",
         "in": "path",
@@ -5470,6 +5894,70 @@
           }
         }
       },
+      "V2PermissionDenied": {
+        "description": "The account may not use this endpoint, for example because it does not use subscription contracts or does not have shipping enabled",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "detail": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "V2FulfillmentOrder": {
+        "description": "V2 fulfillment order",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/V2FulfillmentOrder"
+            }
+          }
+        }
+      },
+      "V2FulfillmentOrderList": {
+        "description": "V2 fulfillment order list",
+        "content": {
+          "application/json": {
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/V2FulfillmentOrder"
+                  }
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "count": {
+                      "type": "integer"
+                    },
+                    "next": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "previous": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/V2FulfillmentOrder"
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
       "V2BillingRun": {
         "description": "V2 billing run",
         "content": {

package/src/resources/register.ts

@@ -9,13 +9,15 @@ Askell POSTs signed JSON to each URL you register. Verify \`Hook-HMAC\` before p
 Headers:
 - Hook-HMAC: base64 HMAC-SHA512 of the **raw body** (secret = \`hmac_secret\` from webhook create)
 - Hook-Event: event type (\`subscription.renewed\`, \`payment.changed\`, or a family wildcard \`subscription.*\`)
-- Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run
+- Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run / fulfillment_order
 
-## Body shape (not in OpenAPI)
+## Body shape
 
 JSON body **is the event object**. It is **not** \`{ event, data }\`.
 
-Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path. Inbound payloads are still undocumented in OpenAPI — this resource is the overlay.
+Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path.
+
+Most inbound families are still undocumented in OpenAPI — this resource is the overlay. Exception: \`fulfillment_order.*\` body **is** \`V2FulfillmentOrder\` (same as \`GET /v2/fulfillment-orders/{id}/\`). Live https://docs.askell.is/en/api/webhooks.html does not list this family yet.
 
 Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`event\` and \`data\` are objects, use \`data\`.
 
@@ -59,6 +61,13 @@ V2 migration: \`subscription.*\` is **not** aliased onto the new contract (paylo
 
 ### checkout.* (v1)
 \`created\`, \`changed\` — \`token\`, \`checkout_url\`, \`status\`.
+
+### fulfillment_order.* (v2)
+Family wildcard \`fulfillment_order.*\`. Concrete event names beyond the family are not listed in swagger or live webhook docs — do not invent \`created\`/\`changed\`.
+
+Body = \`V2FulfillmentOrder\` = \`GET /v2/fulfillment-orders/{fulfillmentOrderId}/\` (list items are the same object). Physical order from a paid billing run (\`billing_run_id\`; at most one order per run). \`delivery_address\` is a snapshot (later contract address edits do not change it). \`shipping_selection\` is the checkout snapshot. \`fulfillments[]\` are booked shipments (empty until booked / if no shipping providers). Status: \`open\` | \`partially_fulfilled\` | \`fulfilled\` | \`cancelled\`.
+
+Register \`fulfillment_order.*\` on \`POST /webhooks/\`. REST backfill: \`GET /v2/fulfillment-orders/?updated_since=\` (secret; newest first; \`403\` if the account has no subscription contracts or shipping is disabled). Read-only — no mark-shipped mutate.
 `;
 
 export function registerResources(server: McpServer): void {

package/src/server.ts

@@ -37,7 +37,7 @@ Workflow:
 
 API models:
 - v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Still supported for existing integrations.
-- v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs under /v2/. Prefer v2 for new integrations.
+- v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs, fulfillment orders under /v2/. Prefer v2 for new integrations.
 - Prose docs at https://docs.askell.is/api/ may describe flows (embedded checkout, 3D Secure, wallet passes) not fully listed in OpenAPI.
 
 API layout:
@@ -55,10 +55,13 @@ V2 checkout notes:
 - checkout_url on V2 checkouts points to the API object URL, not a hosted payment page.
 - GET contract.subscriber_page is the customer-facing subscription management URL (readOnly, nullable). Not checkout_url, not v1 /public/payments/{id}/ (hosted signup). Do not send it on create/patch.
 - finalize: a recurring offer needs a verified payment method even when due-now/total is 0 (trial or fully discounted first period). Only a free one-time purchase finalizes without one. Live docs still say "unless 0 ISK" — ignore that; bundled OpenAPI is right.
-- Hosted POST /v2/checkouts/: shipping {option, location_id?} is required when the offer has physical products and the account has active shipping options. No shipping-options list in OpenAPI (ids are account config). Pickup options need location_id. Snapshot is contract.shipping_selection, not on V2Checkout.
+- Hosted POST /v2/checkouts/: shipping {option, location_id?} is required when the offer has physical products and the account has active shipping options. No shipping-options list in OpenAPI (ids are account config). Pickup options need location_id. Snapshot is contract.shipping_selection (plus location / zone_name / weight_band), not on V2Checkout. Rate-table option with no zip/weight rate: 400, shipping_code shipping_not_available. Quote/checkout totals already include shipping_fee when present.
 - Hosted iframe (not askell.js): POST /v2/checkouts/ and POST .../payment-method-registrations/ take allowed_origin (one origin, no path; http only localhost/loopback). Replaces account-level frame-ancestors; GET empty string = account-level. Rejected on /v2/checkout-sessions/ (sales-channel allowed_origins[]).
 - Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (widget collects address/shipping; see docs, not all in OpenAPI).
 
+V2 fulfillment (warehouse, read-only):
+- GET /v2/fulfillment-orders/ and GET /v2/fulfillment-orders/{id}/. Same body as fulfillment_order.* webhooks (V2FulfillmentOrder). Secret key. 403 if the account has no subscription contracts or shipping is disabled. Poll updated_since after a missed webhook (newest first). No POST/PATCH — cannot mark shipped via the API.
+
 Auth:
 - Most endpoints need the secret API key.
 - Only temporary payment method and checkout status endpoints use the public key.
@@ -71,7 +74,7 @@ Safety:
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
-- askell://docs/webhook-events — inbound webhook payloads (not in OpenAPI; dummy /your-webhook-url/ is stripped on sync), HMAC-SHA512, /webhooks/ hmac_secret`;
+- askell://docs/webhook-events — inbound webhook payloads (most families not in OpenAPI; fulfillment_order.* is V2FulfillmentOrder), HMAC-SHA512, /webhooks/ hmac_secret`;
 }
 
 export function createServer(config: AppConfig): McpServer {