askell-mcp 0.4.3 → 0.4.4

package/README.md

@@ -127,7 +127,7 @@ Typical agent workflow:
 
 - **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
 - **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
-- **v2 coupons** — `GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount` (one active coupon). Quotes take `promotion_code`. Not the v1 `discount` 0–100 field.
+- **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. Totals already include both. 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
 - Docs: [docs.askell.is](https://docs.askell.is/) · OpenAPI: [v1](https://askell.is/api/swagger/swagger.json) · [v2](https://askell.is/api/swagger/v2/swagger.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -62,11 +62,11 @@
     "build:all": "bun run build && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-arm64 && bun run build:darwin-x64"
   },
   "devDependencies": {
-    "@types/bun": "1.4.1",
+    "@types/bun": "1.4.2",
     "typescript": "7.0.2"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.5.4"
+    "zod": "4.6.1"
   }
 }

package/spec/openapi-v2.json

@@ -1455,7 +1455,7 @@
           "V2 Checkouts"
         ],
         "summary": "Finalize a V2 checkout",
-        "description": "Creates the subscription contract and initial billing run, then executes payment. The contract is activated only after successful payment. Requires a secret key.",
+        "description": "Creates the subscription contract and initial billing run, then executes payment. The contract is activated only after successful payment. An offer with recurring items requires a verified payment method for the customer even when the initial total is zero (trial period or fully discounted first period); the card is charged when the first paid period arrives. Only a free one-time purchase finalizes without one. Requires a secret key.",
         "parameters": [
           {
             "$ref": "#/components/parameters/V2CheckoutToken"
@@ -2369,6 +2369,11 @@
             "type": "string",
             "nullable": true,
             "description": "Optional promotion code. When valid, the resulting discount is folded into the offer totals; on contract creation the code is redeemed and a discount is attached to the contract."
+          },
+          "customer": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Optional customer id. When given, the quote also reflects combo discounts earned through the customer's other active contracts, and promotion-code restrictions are checked against this customer."
           }
         }
       },
@@ -3079,11 +3084,93 @@
               "delivery_address": {
                 "$ref": "#/components/schemas/V2Address",
                 "description": "Optional delivery-address snapshot for physical products or alternate delivery."
+              },
+              "shipping": {
+                "$ref": "#/components/schemas/V2ShippingSelectionInput",
+                "description": "The shipping option the customer chose. Required when the offer contains physical products and the account has active shipping options."
               }
             }
           }
         ]
       },
+      "V2ShippingSelectionInput": {
+        "type": "object",
+        "required": [
+          "option"
+        ],
+        "properties": {
+          "option": {
+            "type": "integer",
+            "description": "Id of one of the account's active shipping options."
+          },
+          "location_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Provider id of the chosen pickup location. Required for options with `requires_location`."
+          },
+          "location_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "location_address": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "V2ShippingSelection": {
+        "type": "object",
+        "nullable": true,
+        "description": "Snapshot of the shipping option chosen at checkout.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "option_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "handler": {
+            "type": "string",
+            "enum": [
+              "dropp",
+              "posturinn",
+              "store_pickup"
+            ]
+          },
+          "delivery_mode": {
+            "type": "string",
+            "enum": [
+              "home_delivery",
+              "pickup_point",
+              "post_office",
+              "store_pickup",
+              "freight"
+            ]
+          },
+          "option_name": {
+            "type": "string"
+          },
+          "service_code": {
+            "type": "string"
+          },
+          "price_amount": {
+            "type": "string"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "location_id": {
+            "type": "string"
+          },
+          "location_name": {
+            "type": "string"
+          },
+          "location_address": {
+            "type": "string"
+          }
+        }
+      },
       "V2Address": {
         "type": "object",
         "properties": {
@@ -3914,6 +4001,77 @@
               }
             }
           },
+          "combo_discounts": {
+            "type": "array",
+            "description": "Automatic combo discounts applied to this quote: one entry per discounted recurring line. The quoted totals already include the first-period amounts, and the recurring_* totals already include the renewal amounts. Rules are evaluated against the products in the offer plus, when a customer is given, the products of the customer's other active contracts.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "integer",
+                  "description": "The combo discount rule id."
+                },
+                "name": {
+                  "type": "string"
+                },
+                "line_key": {
+                  "type": "string",
+                  "description": "Key of the discounted line in recurring_items."
+                },
+                "product_id": {
+                  "type": "integer"
+                },
+                "product_name": {
+                  "type": "string"
+                },
+                "required_product_ids": {
+                  "type": "array",
+                  "items": {
+                    "type": "integer"
+                  }
+                },
+                "percent_off": {
+                  "type": "string",
+                  "format": "decimal",
+                  "nullable": true
+                },
+                "amount_off": {
+                  "type": "string",
+                  "format": "decimal",
+                  "nullable": true
+                },
+                "currency": {
+                  "type": "string"
+                },
+                "discount_subtotal_amount": {
+                  "type": "string",
+                  "format": "decimal",
+                  "description": "First-period (prorated) discount, already reflected in subtotal_amount."
+                },
+                "discount_tax_amount": {
+                  "type": "string",
+                  "format": "decimal"
+                },
+                "discount_total_amount": {
+                  "type": "string",
+                  "format": "decimal"
+                },
+                "renewal_discount_subtotal_amount": {
+                  "type": "string",
+                  "format": "decimal",
+                  "description": "Full-period discount applied on each renewal while the customer holds the required products."
+                },
+                "renewal_discount_tax_amount": {
+                  "type": "string",
+                  "format": "decimal"
+                },
+                "renewal_discount_total_amount": {
+                  "type": "string",
+                  "format": "decimal"
+                }
+              }
+            }
+          },
           "recurring_items": {
             "type": "array",
             "items": {
@@ -4630,6 +4788,9 @@
           "customer_reference": {
             "type": "string"
           },
+          "shipping_selection": {
+            "$ref": "#/components/schemas/V2ShippingSelection"
+          },
           "discount": {
             "allOf": [
               {

package/src/server.ts

@@ -47,14 +47,15 @@ API layout:
 - V2 list endpoints paginate only when page_size is provided (default 10, max 1000).
 - GET /v2/customer-entitlements/ requires customer_reference query param.
 
-V2 discounts (coupons / promotion codes) — not the same as v1:
-- v2 contracts: one active coupon at a time. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
-- Quotes: pass promotion_code on POST /v2/subscription-offer-quotes/; totals already include the discount when set.
-- v1 Subscription.discount is a 0-100 percent override on a PlanVariant subscription. Do not send it to v2 contract endpoints.
+V2 discounts — two systems, not v1 Subscription.discount (0-100 on a PlanVariant; never send that to v2):
+- Coupons: one active per contract. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
+- Quotes (POST /v2/subscription-offer-quotes/): pass promotion_code for coupons. When quoting an existing customer, pass customer (numeric id) or combo discounts from their other active contracts and promo-code customer restrictions are skipped. Quoted totals already include coupon + combo; do not subtract again. combo_discounts[] is on the quote response (askell_describe_operation omits response schemas). Combo is automatic, not apply-code.
 
 V2 checkout notes:
-- checkout_url on V2 checkouts points to the API object URL, not a browser payment page.
-- Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (see docs, not all in OpenAPI).
+- checkout_url on V2 checkouts points to the API object URL, not a hosted payment page.
+- 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.
+- Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (widget collects address/shipping; see docs, not all in OpenAPI).
 
 Auth:
 - Most endpoints need the secret API key.

package/src/tools/analysis.ts

@@ -141,7 +141,7 @@ export function registerAnalysisTools(
     {
       title: 'Subscription contract overview (v2)',
       description:
-        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied.',
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, and `shipping_selection` when shipping was chosen at checkout.',
       inputSchema: z.object({
         contractId: z
           .union([z.string().min(1), z.int()])