askell-mcp 0.4.20 → 0.4.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "mcpName": "io.github.Neschadin/askell-mcp",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
@@ -67,7 +67,7 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "zod": "4.6.5"
   }
 }

package/spec/openapi-v1.json

@@ -41,6 +41,10 @@
       "name": "Subscription",
       "description": "Subscription operations, requires secret api key."
     },
+    {
+      "name": "Subscription Discounts",
+      "description": "Promotion codes on subscriptions. Authenticated by the subscription's token instead of an API key, so they can be called from customer-facing applications."
+    },
     {
       "name": "Plan",
       "description": "Plan operations, requires a secret api key."
@@ -410,6 +414,7 @@
           "Customer"
         ],
         "summary": "Add subscription to a customer",
+        "description": "Adds a subscription for an existing customer, charging the first period with the customer's payment method unless the plan has a trial.\n\nPass `promotion_code` to redeem a promotion code on the new subscription before its first charge. An invalid code returns 400 before the delivery address or the subscription is created and before anything is charged.",
         "parameters": [
           {
             "name": "customerReference",
@@ -719,6 +724,7 @@
           "Subscription"
         ],
         "summary": "Create multiple subscriptions",
+        "description": "Creates or reuses a customer and creates one subscription per item in `subscriptions`, charging the first period of each item that has no trial.\n\nEach item can carry a `promotion_code`, and a code used on several items must have a redemption left for each. Every item's code is validated up front: an invalid code (or a checkout price mismatch, below) returns 400 before the payment method is stored and before any subscription is created or charged. The customer may already have been created or updated by then. When `payment_method.token` comes from a checkout created with a `promotion_code` (`POST /checkouts/`), that code is redeemed on the first item for the checkout's plan that has no `promotion_code` of its own. Unless the checkout was `capture_only`, that item's discounted first charge must still equal the amount the checkout quoted (and the card was authorised for); if the coupon's terms or the item's `amount`/`discount` make it differ, the request returns 400 before the payment method is stored or any subscription is created or charged. Pass `promotion_code` on the item explicitly to redeem the code at the current price without this check.",
         "requestBody": {
           "$ref": "#/components/requestBodies/Subscription"
         },
@@ -1023,13 +1029,367 @@
         ]
       }
     },
+    "/subscriptions/{subscriptionId}/apply-code/": {
+      "post": {
+        "tags": [
+          "Subscription Discounts"
+        ],
+        "summary": "Apply a promotion code to a subscription",
+        "description": "Redeems a promotion code on an active subscription, creating a discount that is applied to its subsequent charges. A subscription can only carry one discount at a time. That includes a pending one: a code redeemed when the subscription was created with a future `start_date` has a discount whose window opens on that date. Until then it still blocks a new code with 400, although `GET /subscriptions/{subscriptionId}/discount/` reports it as `has_discount: false`.\n\nThis endpoint does not use an API key. It is authenticated by the subscription's `token` (the `token` field of the Subscription object), sent as `subscription_token` in the request body, so it can be called from a customer-facing application. Treat the subscription token as a secret.\n\nThe code is matched case-insensitively. It is validated against the subscription's customer, currency and billing amount (minimum amount and customer restrictions apply).\n\nTo discount the first charge of a new subscription, pass `promotion_code` when creating it instead (`POST /customers/{customerReference}/subscriptions/add/` or `POST /subscriptions/multi/`).",
+        "parameters": [
+          {
+            "name": "subscriptionId",
+            "in": "path",
+            "description": "Subscription id",
+            "required": true,
+            "style": "simple",
+            "explode": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "code",
+                  "subscription_token"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "description": "The promotion code to redeem.",
+                    "example": "SUMMER20"
+                  },
+                  "subscription_token": {
+                    "type": "string",
+                    "description": "The subscription's `token`.",
+                    "example": "3f5a8c1e-2b7d-4a9e-8c6f-1d2e3f4a5b6c"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Promotion code applied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "example": true
+                    },
+                    "message": {
+                      "type": "string",
+                      "example": "Promotion code applied successfully"
+                    },
+                    "discount": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "integer",
+                          "example": 123
+                        },
+                        "coupon_name": {
+                          "type": "string",
+                          "nullable": true,
+                          "example": "Summer Sale"
+                        },
+                        "discount_display": {
+                          "type": "string",
+                          "nullable": true,
+                          "description": "The coupon's discount, for example `20%` or `500 ISK`.",
+                          "example": "20%"
+                        },
+                        "start": {
+                          "type": "string",
+                          "format": "date-time",
+                          "nullable": true
+                        },
+                        "end": {
+                          "type": "string",
+                          "format": "date-time",
+                          "nullable": true
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The code or token is missing, the subscription is not active, it already has an active or pending discount, or the code is invalid, expired, used up or not valid for this subscription",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No subscription with this id and token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unexpected error while applying the code",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/subscriptions/{subscriptionId}/discount/": {
+      "get": {
+        "tags": [
+          "Subscription Discounts"
+        ],
+        "summary": "Get the active discount for a subscription",
+        "description": "Returns the subscription's active coupon discount, or `has_discount: false` when none is active.\n\nThis endpoint does not use an API key. It is authenticated by the subscription's `token` (the `token` field of the Subscription object), sent as the `subscription_token` query parameter.",
+        "parameters": [
+          {
+            "name": "subscriptionId",
+            "in": "path",
+            "description": "Subscription id",
+            "required": true,
+            "style": "simple",
+            "explode": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "subscription_token",
+            "in": "query",
+            "description": "The subscription's `token`.",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Active discount",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "has_discount": {
+                      "type": "boolean",
+                      "example": true
+                    },
+                    "discount": {
+                      "type": "object",
+                      "nullable": true,
+                      "properties": {
+                        "id": {
+                          "type": "integer",
+                          "example": 123
+                        },
+                        "coupon_name": {
+                          "type": "string",
+                          "example": "Summer Sale"
+                        },
+                        "discount_display": {
+                          "type": "string",
+                          "example": "20%"
+                        },
+                        "promotion_code": {
+                          "type": "string",
+                          "nullable": true,
+                          "description": "The code the discount was redeemed with, or null for a coupon applied without a code.",
+                          "example": "SUMMER20"
+                        },
+                        "start": {
+                          "type": "string",
+                          "format": "date-time",
+                          "nullable": true
+                        },
+                        "end": {
+                          "type": "string",
+                          "format": "date-time",
+                          "nullable": true
+                        },
+                        "duration": {
+                          "type": "string",
+                          "enum": [
+                            "once",
+                            "repeating",
+                            "forever"
+                          ],
+                          "example": "forever"
+                        },
+                        "duration_in_months": {
+                          "type": "integer",
+                          "nullable": true,
+                          "description": "Number of months a `repeating` discount lasts."
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The subscription token is missing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No subscription with this id and token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unexpected error while reading the discount",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/subscriptions/{subscriptionId}/remove-discount/": {
+      "post": {
+        "tags": [
+          "Subscription Discounts"
+        ],
+        "summary": "Remove the active or pending discount from a subscription",
+        "description": "Removes the subscription's active coupon discount, or a pending one that has not started yet (a code redeemed at creation with a future `start_date`; `GET /subscriptions/{subscriptionId}/discount/` reports a pending discount as `has_discount: false`). Subsequent charges are made at the full subscription amount.\n\nThis endpoint does not use an API key. It is authenticated by the subscription's `token` (the `token` field of the Subscription object), sent as `subscription_token` in the request body.",
+        "parameters": [
+          {
+            "name": "subscriptionId",
+            "in": "path",
+            "description": "Subscription id",
+            "required": true,
+            "style": "simple",
+            "explode": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "subscription_token"
+                ],
+                "properties": {
+                  "subscription_token": {
+                    "type": "string",
+                    "description": "The subscription's `token`.",
+                    "example": "3f5a8c1e-2b7d-4a9e-8c6f-1d2e3f4a5b6c"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Discount removed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "example": true
+                    },
+                    "message": {
+                      "type": "string",
+                      "example": "Discount removed successfully"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The subscription token is missing, or the subscription has no active or pending discount",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No subscription with this id and token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unexpected error while removing the discount",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionDiscountError"
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
     "/checkouts/": {
       "post": {
         "tags": [
           "Checkout"
         ],
         "summary": "Create a hosted checkout card form",
-        "description": "Creates a hosted checkout and returns a `checkout_url` that should be rendered in an iframe. The hosted page collects card details, handles 3D Secure when required, and posts completion messages to the embedding page. The resulting `token` is a reference to a payment method that can be added to a customer after checkout status becomes `tokencreated`.\n\nCreate a checkout either for a `plan` or directly for an account `payment_processor`. When using `payment_processor`, `currency` is required. A `plan` checkout completes into a legacy subscription, so on an account that uses subscription contracts only it is refused with 400 and `code: legacy_subscriptions_disabled`; a checkout for a `payment_processor` still works there. To capture only the card details, set `capture_only` to `true`; this value is optional and defaults to `false`.\n\nIf supplied, `allowed_origin` must be an origin only, for example `https://merchant.example`, with no path, query string, or credentials. It controls the single parent page origin allowed to frame this checkout and receive checkout postMessage notifications. If omitted, all checkout origins configured for the account are allowed to frame the checkout.",
+        "description": "Creates a hosted checkout and returns a `checkout_url` that should be rendered in an iframe. The hosted page collects card details, handles 3D Secure when required, and posts completion messages to the embedding page. The resulting `token` is a reference to a payment method that can be added to a customer after checkout status becomes `tokencreated`.\n\nCreate a checkout either for a `plan` or directly for an account `payment_processor`. When using `payment_processor`, `currency` is required. A `plan` checkout completes into a legacy subscription, so on an account that uses subscription contracts only it is refused with 400 and `code: legacy_subscriptions_disabled`; a checkout for a `payment_processor` still works there. To capture only the card details, set `capture_only` to `true`; this value is optional and defaults to `false`.\n\nIf supplied, `allowed_origin` must be an origin only, for example `https://merchant.example`, with no path, query string, or credentials. It controls the single parent page origin allowed to frame this checkout and receive checkout postMessage notifications. If omitted, all checkout origins configured for the account are allowed to frame the checkout.\n\nWith a `plan`, a `promotion_code` can be supplied. The card form then shows the discounted first-period amount, and the code is redeemed when the checkout's `token` is used in `POST /subscriptions/multi/`. See `promotion_code` in the request body.",
         "requestBody": {
           "$ref": "#/components/requestBodies/CheckoutCreate"
         },
@@ -1876,6 +2236,11 @@
             "format": "uri",
             "description": "Optional iframe parent origin for this checkout, for example `https://merchant.example`. Must be an origin only, with no path, query string, or credentials. Overrides the account configured checkout origins for this checkout.",
             "example": "https://merchant.example"
+          },
+          "promotion_code": {
+            "type": "string",
+            "example": "SUMMER20",
+            "description": "Optional promotion code for the subscription this checkout's card will pay for (requires a `plan`). It is validated against the plan amount and currency; a code restricted to a specific customer cannot be used here, as the checkout has no customer yet. The card form and 3D Secure use the discounted first-period amount (unless `capture_only` is set). The checkout itself creates no subscription and redeems nothing: when the checkout's `token` is used as `payment_method.token` in `POST /subscriptions/multi/`, the code is redeemed on the first item for this checkout's plan that has no `promotion_code` of its own (an item's own code always wins). Other endpoints do not carry it over: pass `promotion_code` explicitly there."
           }
         },
         "oneOf": [
@@ -2588,6 +2953,11 @@
             "example": "My custom note",
             "required": "false",
             "description": "An optional description for internal purposes."
+          },
+          "promotion_code": {
+            "type": "string",
+            "example": "SUMMER20",
+            "description": "Optional promotion code to redeem on the new subscription. It is validated against the customer and the amount it applies to: the plan amount, or `amount` when given, less the `discount` percentage. It is redeemed before the first charge, so that charge is already discounted, and later renewals follow the coupon's duration. When a future `start_date` defers the first charge of a plan without a trial, the discount starts on that date, so a `repeating` coupon's months count from the first charge. A coupon that skips the trial period charges the discounted first period immediately instead of starting the plan's trial, unless `start_date` is in the future (the first billing then lands on it, as with a trial). A `once` coupon that brings the immediate first charge to zero is used up by it. An invalid, expired, used-up or customer-restricted code returns 400 before any payment method is stored and before any subscription is created or charged (with `POST /subscriptions/multi/`, the customer may already have been created or updated). When the same code is used on several items of `POST /subscriptions/multi/`, it must have a redemption left for each of them. Blank or absent means no code."
           }
         }
       },
@@ -2748,6 +3118,46 @@
           "checkout_url": {
             "type": "string",
             "example": "https://askell.is/checkout/637302f0412e2e11adc0ba21adafcf11/"
+          },
+          "promotion_code": {
+            "type": "object",
+            "description": "Present only when the checkout was created with a `promotion_code`.",
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "The normalised (upper-case) code stored on the checkout.",
+                "example": "SUMMER20"
+              },
+              "discount_display": {
+                "type": "string",
+                "description": "The coupon's discount, for example `20%` or `500 ISK`.",
+                "example": "20%"
+              },
+              "original_amount": {
+                "type": "string",
+                "description": "The plan's first-period amount before the discount.",
+                "example": "1000.00"
+              },
+              "discounted_amount": {
+                "type": "string",
+                "description": "The first-period amount after the discount, shown in the card form.",
+                "example": "800.00"
+              }
+            }
+          }
+        }
+      },
+      "SubscriptionDiscountError": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Present on the `apply-code` and `remove-discount` responses.",
+            "example": false
+          },
+          "error": {
+            "type": "string",
+            "example": "Invalid subscription or token"
           }
         }
       },

package/spec/openapi-v2.json

@@ -4568,6 +4568,45 @@
           }
         }
       },
+      "V2CustomerPaymentMethodCard": {
+        "type": "object",
+        "description": "The card behind a card payment method. Each field is `null` when the payment processor does not tell Áskell.",
+        "properties": {
+          "brand": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "visa",
+              "mastercard",
+              "amex",
+              "maestro",
+              "diners",
+              "discover",
+              "jcb",
+              "dankort",
+              null
+            ],
+            "description": "Card brand. Visa Electron is reported as `visa`."
+          },
+          "last4": {
+            "type": "string",
+            "nullable": true,
+            "pattern": "^[0-9]{4}$",
+            "description": "Last four digits of the card number."
+          },
+          "funding": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "credit",
+              "debit",
+              "prepaid",
+              null
+            ],
+            "description": "Whether the card is a credit, debit or prepaid card. Only known for processors that report it (Straumur, and Valitor Pay after the card's first successful charge); always `null` for Teya."
+          }
+        }
+      },
       "V2CustomerPaymentMethod": {
         "type": "object",
         "properties": {
@@ -4596,6 +4635,15 @@
           "display_info": {
             "type": "string"
           },
+          "card": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2CustomerPaymentMethodCard"
+              }
+            ],
+            "nullable": true,
+            "description": "Brand, last four digits and funding of the card. `null` for claim and invoice payment methods."
+          },
           "verified": {
             "type": "boolean"
           },

package/src/client/askell-client.ts

@@ -27,8 +27,14 @@ export class AskellClient {
     this.baseUrl = normalizeBaseUrl(config.apiBaseUrl);
   }
 
-  private apiKeyFor(kind: ApiKeyKind | undefined): string {
+  private authorizationHeader(
+    kind: ApiKeyKind | undefined,
+  ): Record<string, string> {
     const apiKeyKind = kind ?? 'secret';
+    if (apiKeyKind === 'none') {
+      return {};
+    }
+
     const apiKey =
       apiKeyKind === 'public'
         ? this.config.publicApiKey
@@ -42,7 +48,7 @@ export class AskellClient {
       );
     }
 
-    return apiKey;
+    return { Authorization: `Api-Key ${apiKey}` };
   }
 
   async request(
@@ -69,14 +75,14 @@ export class AskellClient {
       }
     }
 
-    const apiKey = this.apiKeyFor(input.apiKeyKind);
+    const authorization = this.authorizationHeader(input.apiKeyKind);
 
     const started = performance.now();
     const response = await fetch(url, {
       method,
       headers: {
-        Authorization: `Api-Key ${apiKey}`,
         Accept: 'application/json',
+        ...authorization,
         ...(input.body !== undefined
           ? { 'Content-Type': 'application/json' }
           : {}),
@@ -115,7 +121,7 @@ export class AskellClient {
     signal?: AbortSignal;
   }): Promise<FormattedResponse & { ok: boolean; status: number }> {
     const maxPages = input.maxPages ?? 20;
-    const apiKey = this.apiKeyFor(input.apiKeyKind);
+    const authorization = this.authorizationHeader(input.apiKeyKind);
 
     const collected: unknown[] = [];
     let nextUrl: URL | null = null;
@@ -146,8 +152,8 @@ export class AskellClient {
       const response = await fetch(url, {
         method: 'GET',
         headers: {
-          Authorization: `Api-Key ${apiKey}`,
           Accept: 'application/json',
+          ...authorization,
         },
         signal: input.signal,
       });

package/src/client/paths.ts

@@ -1,3 +1,23 @@
+/** OpenAPI `{param}` template vs a concrete request path. Both should be normalized. */
+export function openApiPathMatches(template: string, concrete: string): boolean {
+  if (template === concrete) {
+    return true;
+  }
+
+  const templateParts = template.split('/');
+  const concreteParts = concrete.split('/');
+  if (templateParts.length !== concreteParts.length) {
+    return false;
+  }
+
+  return templateParts.every((part, index) => {
+    if (part.startsWith('{') && part.endsWith('}') && part.length > 2) {
+      return concreteParts[index] !== '';
+    }
+    return part === concreteParts[index];
+  });
+}
+
 /** Normalize Askell API paths: leading slash + trailing slash (OpenAPI convention). */
 export function normalizeApiPath(path: string): string {
   let normalized = path.startsWith('/') ? path : `/${path}`;

package/src/openapi/registry.ts

@@ -60,6 +60,83 @@ function resolveSchema(doc: OpenApiDocument, schema: unknown): unknown {
   return schema;
 }
 
+/**
+ * Follow nested `$ref`s in a schema. `seen` is the ancestor chain only, so the
+ * same component used twice as a sibling is inlined twice; a cycle stops.
+ */
+function resolveSchemaDeep(
+  doc: OpenApiDocument,
+  schema: unknown,
+  seen = new Set<string>(),
+): unknown {
+  if (schema == null || typeof schema !== 'object') {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map((item) => resolveSchemaDeep(doc, item, seen));
+  }
+
+  const record = schema as Record<string, unknown>;
+  if (typeof record.$ref === 'string') {
+    if (record.circular === true || seen.has(record.$ref)) {
+      return { $ref: record.$ref, circular: true };
+    }
+
+    const next = new Set(seen);
+    next.add(record.$ref);
+    return resolveSchemaDeep(doc, resolveRef(doc, record.$ref), next);
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] =
+      value !== null && typeof value === 'object'
+        ? resolveSchemaDeep(doc, value, seen)
+        : value;
+  }
+  return out;
+}
+
+function resolveRequestBody(
+  doc: OpenApiDocument,
+  requestBody: {
+    $ref?: string;
+    required?: boolean;
+    description?: string;
+    content?: Record<string, { schema?: unknown }>;
+  },
+): ApiOperation['requestBody'] {
+  let source = requestBody;
+
+  if (typeof requestBody.$ref === 'string') {
+    const resolved = resolveRef(doc, requestBody.$ref);
+    if (
+      resolved == null ||
+      typeof resolved !== 'object' ||
+      Array.isArray(resolved)
+    ) {
+      return { contentTypes: [] };
+    }
+    source = resolved as typeof requestBody;
+  }
+
+  const content = source.content ?? {};
+  const contentTypes = Object.keys(content);
+  const firstContent = contentTypes[0] ? content[contentTypes[0]] : undefined;
+
+  return {
+    ...(source.required !== undefined ? { required: source.required } : {}),
+    ...(source.description !== undefined
+      ? { description: source.description }
+      : {}),
+    contentTypes,
+    ...(firstContent?.schema !== undefined
+      ? { schema: resolveSchemaDeep(doc, firstContent.schema) }
+      : {}),
+  };
+}
+
 function resolveParameters(
   doc: OpenApiDocument,
   parameters: OpenApiParameter[] | undefined,
@@ -100,10 +177,16 @@ function resolveParameters(
 function inferApiKeyKind(
   security: Array<Record<string, unknown[]>> | undefined,
 ): ApiKeyKind {
-  if (!security?.length) {
+  // Omitted `security` inherits the document default (secret key).
+  // `security: []` opts out of every scheme — no API key.
+  if (security === undefined) {
     return 'secret';
   }
 
+  if (security.length === 0) {
+    return 'none';
+  }
+
   for (const requirement of security) {
     if ('Public-Api-Key' in requirement) {
       return 'public';
@@ -139,11 +222,6 @@ function parseDocument(
       }
 
       const method = methodKey.toUpperCase() as HttpMethod;
-      const content = operation.requestBody?.content ?? {};
-      const contentTypes = Object.keys(content);
-      const firstContent = contentTypes[0]
-        ? content[contentTypes[0]]
-        : undefined;
 
       operations.push({
         id: buildOperationId(apiVersion, method, path),
@@ -155,14 +233,7 @@ function parseDocument(
         description: operation.description,
         parameters: resolveParameters(doc, operation.parameters),
         requestBody: operation.requestBody
-          ? {
-              required: operation.requestBody.required,
-              description: operation.requestBody.description,
-              contentTypes,
-              schema: firstContent
-                ? resolveSchema(doc, firstContent.schema)
-                : undefined,
-            }
+          ? resolveRequestBody(doc, operation.requestBody)
           : undefined,
         apiKeyKind: inferApiKeyKind(operation.security),
         deprecated: operation.deprecated,

package/src/openapi/types.ts

@@ -2,7 +2,7 @@ export type ApiVersion = 'v1' | 'v2';
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
 
-export type ApiKeyKind = 'secret' | 'public';
+export type ApiKeyKind = 'secret' | 'public' | 'none';
 
 export interface OpenApiParameter {
   name?: string;
@@ -51,6 +51,7 @@ export interface OpenApiDocument {
           deprecated?: boolean;
           parameters?: OpenApiParameter[];
           requestBody?: {
+            $ref?: string;
             required?: boolean;
             description?: string;
             content?: Record<string, { schema?: unknown }>;

package/src/server.ts

@@ -13,6 +13,14 @@ import { registerCallTools } from './tools/call.ts';
 import { registerDiscoveryTools } from './tools/discovery.ts';
 import { PACKAGE_VERSION } from './version.ts';
 
+/**
+ * Combined array elements and object members allowed in one `tools/call`
+ * `arguments` payload. Off in the SDK by default; set here so a wide or deep
+ * JSON body cannot be walked before schema validation. Legitimate Askell
+ * writes (checkout, contract, webhook) sit far under this.
+ */
+export const MAX_TOOL_INPUT_ELEMENTS = 10_000;
+
 export function buildServerInstructions(config: AppConfig): string {
   const apiBase = normalizeBaseUrl(config.apiBaseUrl);
   const envLine =
@@ -47,11 +55,18 @@ 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 — not v1 Subscription.discount (0-100 on a PlanVariant; never send that to v2). Coupon = discount definition; promotion code = customer-facing code:
+V2 discounts — not the v1 percent field Subscription.discount (0-100 on a PlanVariant; never send that to v2). v1 promotion codes are a separate system, below. Coupon = discount definition; promotion code = customer-facing code:
 - Catalog (secret): CRUD /v2/coupons/ and /v2/promotion-codes/. Create coupon: exactly one of amount_off+currency or percent_off; duration_in_months required iff duration=repeating (omit otherwise); redeem_by must be future. PATCH type switch: send the old field as null. Redeemed coupon/code cannot DELETE — retire coupon with redeem_by/max_redemptions, promo with active=false (frees code for reuse). List/get hide soft-deletes. Promo code is uppercased and generated if omitted; unique among active; restrict with customer xor customer_reference.
 - Contract: one active discount. 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. First-period subtotal/tax/total already include coupon + combo. quote.recurring_* include combo, not the coupon — renewal-with-coupon is discount.recurring_final_amount, and only while duration still applies (once → after first payment use recurring_*). combo_discounts[] and discount.recurring_* are on the quote response (askell_describe_operation omits response schemas). Combo is automatic, not apply-code.
 
+V1 promotion codes — not Subscription.discount (0-100). Live subscription docs do not describe these yet; bundled OpenAPI is right:
+- First charge: promotion_code on POST /customers/{customerReference}/subscriptions/add/, or on each item of POST /subscriptions/multi/. apply-code does not discount the first charge.
+- POST /checkouts/ promotion_code requires a plan. The checkout redeems nothing. The code is applied only when that checkout's token is payment_method.token on POST /subscriptions/multi/, on the first item for that plan that has no promotion_code of its own (an item's own code wins). POST .../subscriptions/add/ does not carry the checkout code over. Unless capture_only, that item's discounted first charge must equal the amount the checkout quoted, or the request is 400 before the payment method is stored. A customer-restricted code cannot be used at checkout (no customer yet).
+- One discount per subscription, including a pending one from a future start_date. GET /subscriptions/{subscriptionId}/discount/ reports a pending discount as has_discount: false, but apply-code still returns 400 until remove-discount.
+- POST /subscriptions/{subscriptionId}/apply-code/ body {code, subscription_token}. POST .../remove-discount/ body {subscription_token}. GET .../discount/?subscription_token=. subscription_token is Subscription.token. Treat it as a secret. These three paths are apiKeyKind none: do not send Authorization.
+- An invalid code on add, multi, or checkout is 400 before the subscription is created or charged. On multi the customer may already have been created or updated. The same code on several multi items needs a redemption left for each. A coupon that skips the trial charges the discounted first period immediately, unless start_date is in the future. legacy_subscriptions_disabled still refuses add, multi, and a plan checkout.
+
 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.
@@ -71,6 +86,9 @@ V2 contract changes:
 - apply_on_payment (default false; items/update and proration-preview; apply_at=now only): false switches the item now and collects afterwards. true keeps the current values until the proration run is collected, without moving the billing schedule. Same-interval (an upgrade): pending_interval_change is null; the wait is only pending_change (interval_change false, status awaiting_payment). Renewal is held. Other item edits and change-anchor return 409 pending_change — change-anchor's operation text only names pending_interval_change. Needs invoice_now (400 apply_on_payment_requires_invoice_now). Nothing to collect (no proration, a downgrade, or a charge fully covered) applies at once. A terminal failure leaves the item unchanged; a later manual retry that succeeds still applies the change unless the item was changed or its renewal billed in the meantime, in which case the payment is credited to the contract balance. Send the same apply_on_payment on proration-preview: a preview token only validates an update with the same value.
 - POST .../change-anchor/ moves the next renewal of the contract and every active item. new_billing_anchor_at must be after effective_at and, with proration, at most one billing period later. Does not extend entitlements. Preview with proration-preview operation=change_anchor (new_billing_anchor_at required). Do not PATCH billing_anchor_at.
 
+V2 payment methods:
+- V2CustomerPaymentMethod.card is brand, last4, funding. null for claim and invoice. funding is null for Teya, and for Valitor Pay until the card's first successful charge. Visa Electron is visa.
+
 V2 refunds:
 - A billing-run charge is not a Payment. payment.* for that charge is a flat object (Hook-API-Version v2, subscription_contract_id, billing_run_id, billing_run_attempt_id), not transactions[]; a payment.retry may have a null uuid and state retry_scheduled. Refund with POST /v2/billing-runs/{id}/refund/ (no body, full amount only, secret). 200 → state refunded, metadata.transaction_refund, webhook billing_run.changed (no separate refund event). 202 → run still succeeded (metadata.refund_requests); wait or re-GET; do not resend immediately. 400 if not succeeded, zero amount, already refunded, or the processor cannot refund. No response (timeout): GET the run and check state plus metadata.refund_requests before retrying. POST /payments/{uuid}/refund/ is one-off Payments only.
 
@@ -81,11 +99,13 @@ V2 fulfillment (warehouse):
 Auth:
 - Most endpoints need the secret API key.
 - Only temporary payment method and checkout status endpoints use the public key.
+- v1 subscription discount paths (apply-code, discount, remove-discount) are apiKeyKind none: no Authorization header. Pass subscription_token (Subscription.token) and treat that token as a secret. Omit apiKeyKind on askell_call/askell_mutate to follow the operation.
 
 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 arguments are rejected when they contain more than ${MAX_TOOL_INPUT_ELEMENTS} combined array elements and object members. The call returns isError and names the limit; shrink the JSON body or query.
 - Tool output redacts webhook hmac_secret to \`<redacted len=N>\` (Askell list/get/create return the plaintext secret).
 
 Resources:
@@ -101,6 +121,7 @@ export function createServer(config: AppConfig): McpServer {
     },
     {
       instructions: buildServerInstructions(config),
+      maxToolInputElements: MAX_TOOL_INPUT_ELEMENTS,
     },
   );
 

package/src/tools/analysis.ts

@@ -116,9 +116,11 @@ export function registerAnalysisTools(
           .optional()
           .describe('Query string parameters forwarded to the list endpoint'),
         apiKeyKind: z
-          .enum(['secret', 'public'])
+          .enum(['secret', 'public', 'none'])
           .default('secret')
-          .describe('Which configured API key to use'),
+          .describe(
+            'Which configured API key to use. none sends no Authorization header',
+          ),
         maxPages: z
           .int()
           .positive()

package/src/tools/call.ts

@@ -9,9 +9,10 @@ import {
 import * as z from 'zod';
 
 import { AskellClient, type AskellRequest } from '../client/askell-client.ts';
-import { normalizeApiPath } from '../client/paths.ts';
+import { normalizeApiPath, openApiPathMatches } from '../client/paths.ts';
 import type { AppConfig } from '../config.ts';
 import { operationRegistry } from '../openapi/registry.ts';
+import type { ApiKeyKind, HttpMethod } from '../openapi/types.ts';
 import {
   clientSupportsFormElicitation,
   decideMutationGate,
@@ -32,11 +33,33 @@ const sharedCallFields = {
     .describe('Query string parameters'),
   body: z.json().optional().describe('JSON request body'),
   apiKeyKind: z
-    .enum(['secret', 'public'])
-    .default('secret')
-    .describe('Which configured API key to use'),
+    .enum(['secret', 'public', 'none'])
+    .optional()
+    .describe(
+      'Which configured API key to send. Omit to use the operation from askell_describe_operation: secret, public, or none (no Authorization header). v1 subscription discount paths are none and authenticate with subscription_token',
+    ),
 };
 
+export function resolveCallApiKeyKind(
+  method: HttpMethod,
+  path: string,
+  explicit: ApiKeyKind | undefined,
+): ApiKeyKind {
+  if (explicit) {
+    return explicit;
+  }
+
+  const normalized = normalizeApiPath(path);
+  const matches = operationRegistry.operations.filter(
+    (operation) =>
+      operation.method === method &&
+      openApiPathMatches(operation.path, normalized),
+  );
+  const exact = matches.find((operation) => operation.path === normalized);
+
+  return (exact ?? matches[0])?.apiKeyKind ?? 'secret';
+}
+
 const callInputSchema = z.object({
   method: z.enum(['GET', 'HEAD']).describe('HTTP method (read-only)'),
   ...sharedCallFields,
@@ -61,11 +84,16 @@ type ToolCtx = {
 };
 
 function buildApprovalMessage(input: MutateInput): string {
+  const apiKeyKind = resolveCallApiKeyKind(
+    input.method,
+    input.path,
+    input.apiKeyKind,
+  );
   const lines = [
     'Approve this Askell API request?',
     '',
     `${input.method} ${input.path}`,
-    `apiKeyKind: ${input.apiKeyKind}`,
+    `apiKeyKind: ${apiKeyKind}`,
   ];
 
   if (input.query && Object.keys(input.query).length > 0) {
@@ -85,19 +113,12 @@ async function executeAskellRequest(
   signal: AbortSignal,
 ): Promise<CallToolResult> {
   const path = normalizeApiPath(input.path);
-  const known = operationRegistry
-    .find({
-      method: input.method,
-      pathPrefix: path,
-    })
-    .find((operation) => operation.path === path);
-
   const request: AskellRequest = {
     method: input.method,
     path,
     query: input.query,
     body: input.body,
-    apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
+    apiKeyKind: resolveCallApiKeyKind(input.method, path, input.apiKeyKind),
     signal,
   };
 
@@ -171,7 +192,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. Webhook hmac_secret is redacted in the response.',
+        '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. Omit apiKeyKind to follow the operation (none sends no Authorization header). Webhook hmac_secret is redacted in the response.',
       inputSchema: callInputSchema,
       annotations: {
         readOnlyHint: true,
@@ -190,7 +211,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. Webhook hmac_secret is redacted in the response (including POST /webhooks/ create).',
+        '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. Omit apiKeyKind to follow the operation (none sends no Authorization header). Webhook hmac_secret is redacted in the response (including POST /webhooks/ create).',
       inputSchema: mutateInputSchema,
       annotations: {
         readOnlyHint: false,

package/src/tools/discovery.ts

@@ -24,9 +24,11 @@ const listInputSchema = z.object({
       'Case-insensitive search in id, path, summary, description, tags',
     ),
   apiKeyKind: z
-    .enum(['secret', 'public'])
+    .enum(['secret', 'public', 'none'])
     .optional()
-    .describe('Filter by required API key type'),
+    .describe(
+      'Filter by required API key type. none means the operation does not use an API key',
+    ),
   limit: z
     .int()
     .positive()
@@ -44,7 +46,7 @@ const describeInputSchema = z.object({
 });
 
 const apiVersionSchema = z.enum(['v1', 'v2']);
-const apiKeyKindSchema = z.enum(['secret', 'public']);
+const apiKeyKindSchema = z.enum(['secret', 'public', 'none']);
 const httpMethodSchema = z.enum([
   'GET',
   'POST',