askell-mcp 0.4.2 → 0.4.4

package/README.md

@@ -113,7 +113,7 @@ Typical agent workflow:
 | `askell_customer_overview`  | v1 customer + subscriptions              |
 | `askell_contract_overview`  | v2 subscription contract + billing runs  |
 | `askell_billing_run_triage` | v2 billing run (+ optional contract)     |
-| `askell_list_webhooks`      | List configured webhooks                 |
+| `askell_list_webhooks`      | List configured webhooks (`hmac_secret` redacted) |
 
 ### Resources
 
@@ -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.2",
+  "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.0",
+    "@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": [
               {
@@ -5334,4 +5495,4 @@
       }
     }
   }
-}
+}

package/src/client/askell-client.ts

@@ -1,5 +1,6 @@
 import { normalizeBaseUrl, type AppConfig } from '../config.ts';
 import { normalizeApiPath } from './paths.ts';
+import { redactSecretsInText } from './redact.ts';
 import {
   buildBoundedListPayload,
   formatApiResponse,
@@ -182,10 +183,11 @@ export class AskellClient {
       try {
         parsed = JSON.parse(bodyText);
       } catch {
+        const text = redactSecretsInText(bodyText);
         return {
-          text: bodyText,
+          text,
           truncated: false,
-          byteLength: Buffer.byteLength(bodyText, 'utf8'),
+          byteLength: Buffer.byteLength(text, 'utf8'),
           ok: false,
           status: lastStatus,
         };

package/src/client/redact.ts

@@ -0,0 +1,54 @@
+const SECRET_KEYS = new Set(['hmac_secret']);
+
+const JSON_SECRET_STRING =
+  /"(hmac_secret)"\s*:\s*("(?:\\.|[^"\\])*")/g;
+
+export function formatRedactedSecret(value: unknown): string {
+  if (typeof value === 'string' && value.startsWith('<redacted')) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return `<redacted len=${value.length}>`;
+  }
+  return '<redacted>';
+}
+
+export function redactSensitiveFields(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactSensitiveFields);
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(
+      value as Record<string, unknown>,
+    )) {
+      out[key] = SECRET_KEYS.has(key)
+        ? formatRedactedSecret(nested)
+        : redactSensitiveFields(nested);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+/** Fallback for non-JSON / truncated bodies. Leaves already-redacted values alone. */
+export function redactSecretsInText(text: string): string {
+  if (!text.includes('hmac_secret')) {
+    return text;
+  }
+
+  try {
+    return JSON.stringify(redactSensitiveFields(JSON.parse(text)));
+  } catch {
+    JSON_SECRET_STRING.lastIndex = 0;
+    return text.replace(JSON_SECRET_STRING, (_match, key: string, raw: string) => {
+      try {
+        return `"${key}": ${JSON.stringify(formatRedactedSecret(JSON.parse(raw)))}`;
+      } catch {
+        return `"${key}": ${JSON.stringify(formatRedactedSecret(undefined))}`;
+      }
+    });
+  }
+}

package/src/client/response-formatter.ts

@@ -1,3 +1,8 @@
+import {
+  redactSensitiveFields,
+  redactSecretsInText,
+} from './redact.ts';
+
 export interface FormattedResponse {
   text: string;
   truncated: boolean;
@@ -203,7 +208,8 @@ export function buildBoundedListPayload(input: {
   items: unknown[];
   maxBytes: number;
 }): FormattedResponse {
-  const { status, meta, items, maxBytes } = input;
+  const { status, meta, maxBytes } = input;
+  const items = input.items.map((item) => redactSensitiveFields(item));
 
   const attempts: Array<{
     items: unknown[];
@@ -334,13 +340,14 @@ export function formatApiResponse(
 ): FormattedResponse {
   const byteLength = Buffer.byteLength(bodyText, 'utf8');
   const truncated = byteLength > maxBytes;
-  const visibleBody = truncated ? truncateUtf8(bodyText, maxBytes) : bodyText;
+  const safeText = redactSecretsInText(bodyText);
+  const visibleBody = truncated ? truncateUtf8(safeText, maxBytes) : safeText;
 
   let parsedBody: unknown = visibleBody;
   try {
     parsedBody = JSON.parse(visibleBody);
   } catch {
-    // keep raw text
+    // keep redacted raw text
   }
 
   const payload = {

package/src/resources/register.ts

@@ -21,9 +21,10 @@ Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`even
 
 ## Registering endpoints (v1 management API)
 
-- GET/POST \`/webhooks/\` · GET/PUT/PATCH/DELETE \`/webhooks/{id}/\` (secret key)
+- GET/POST \`/webhooks/\` · GET/PUT/PATCH/DELETE \`/webhooks/{id}/\` (secret key). Live GET \`/webhooks/{id}/\` exists even if OpenAPI omits it.
 - Create body: \`{ url, event }\` (\`event\` may be a specific type or a family wildcard like \`payment.*\`)
-- Create/get response includes \`hmac_secret\` (store it; Askell will not show it again in a useful way if you lose it) and \`hmac_digest\` (typically \`SHA512\`)
+- Askell returns plaintext \`hmac_secret\` on list, get, and create (it is re-readable, not create-only), plus \`hmac_digest\` (typically \`SHA512\`)
+- MCP tool output redacts \`hmac_secret\` to \`<redacted len=N>\`. Do not treat that placeholder as the real secret. Copy the secret from the Askell dashboard or a direct API call outside MCP.
 
 Tools: \`askell_list_webhooks\`, \`askell_call\` (GET), \`askell_mutate\` (POST/PUT/PATCH/DELETE).
 

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.
@@ -64,6 +65,7 @@ Safety:
 - Writes go through askell_mutate (destructiveHint). Reads go through askell_call (readOnlyHint).
 - mutationGate=auto (default): confirmation form only if this request's envelope declared form elicitation; otherwise the client's own tool-allow UI is the gate. elicit always returns a form (SDK refuses if the client cannot fulfil it). off never asks.
 - Large list responses are compacted (index of id/dates/plan/customer) to fit responseMaxBytes before dropping rows; check meta.truncatedByMaxBytes, meta.compacted, and meta.compactedMode.
+- Tool output redacts webhook hmac_secret to \`<redacted len=N>\` (Askell list/get/create return the plaintext secret).
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI

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()])
@@ -278,7 +278,7 @@ export function registerAnalysisTools(
     {
       title: 'List configured webhooks (v1)',
       description:
-        'List Askell webhook endpoints configured for the account (management API only).',
+        'List Askell webhook endpoints configured for the account (management API only). hmac_secret is redacted in the tool output (`<redacted len=N>`); copy the real secret from the dashboard or a non-MCP API call.',
       inputSchema: z.object({
         page_size: z
           .int()

package/src/tools/call.ts

@@ -171,7 +171,7 @@ export function registerCallTools(
     {
       title: 'Call Askell API (read)',
       description:
-        'Read-only Askell API call (GET, HEAD) for any v1/v2 path. For POST/PUT/PATCH/DELETE use askell_mutate. Discover paths with askell_list_operations and askell_describe_operation first.',
+        'Read-only Askell API call (GET, HEAD) for any v1/v2 path. For POST/PUT/PATCH/DELETE use askell_mutate. Discover paths with askell_list_operations and askell_describe_operation first. Webhook hmac_secret is redacted in the response.',
       inputSchema: callInputSchema,
       annotations: {
         readOnlyHint: true,
@@ -190,7 +190,7 @@ export function registerCallTools(
     {
       title: 'Mutate Askell API',
       description:
-        'Mutating Askell API call (POST, PUT, PATCH, DELETE). Clients that declared form elicitation get a confirmation form; others rely on the client tool-approval UI. Use askell_call for GET. Discover paths with askell_list_operations and askell_describe_operation first.',
+        'Mutating Askell API call (POST, PUT, PATCH, DELETE). Clients that declared form elicitation get a confirmation form; others rely on the client tool-approval UI. Use askell_call for GET. Discover paths with askell_list_operations and askell_describe_operation first. Webhook hmac_secret is redacted in the response (including POST /webhooks/ create).',
       inputSchema: mutateInputSchema,
       annotations: {
         readOnlyHint: false,