askell-mcp 0.4.18 → 0.4.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "mcpName": "io.github.Neschadin/askell-mcp",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",

package/spec/openapi-v2.json

@@ -4091,6 +4091,12 @@
                 ],
                 "description": "Stored on the checkout and copied to the created contract's `metadata` when the checkout is finalized. In a checkout session the session's own metadata wins on a shared key, and the sales channel's `metadata_policy.frontend_allowed_keys` limits the keys the browser may send (with no such list any key is accepted, and an empty list accepts none). Keys Askell uses itself (`askell_source`, `billing_anchor_mode`, `activation_failure`, `email_markers`, `copied_legacy_pauses`, `copied_legacy_extra_data`, `migration_source`, `migration_cadence_mode`, `legacy_subscription_ids`, `seed`) are not copied."
               },
+              "contract_reference": {
+                "type": "string",
+                "nullable": true,
+                "maxLength": 128,
+                "description": "Your reference for the subscription contract this checkout creates, such as your order number. Copied to the contract's `reference` when the contract is created on finalize, so it is in every `subscription_contract.*` webhook, `subscription_contract.created` included, and `GET /api/v2/subscription-contracts/?reference=` finds the contract. Must not contain commas; not unique. Surrounding whitespace is trimmed and a blank value means no reference. Not accepted on checkout-session endpoints: there the seller's backend sets `contract_reference` when it creates the session."
+              },
               "delivery_address": {
                 "$ref": "#/components/schemas/V2Address",
                 "description": "Optional delivery-address snapshot for physical products or alternate delivery."
@@ -4421,6 +4427,12 @@
             "type": "string",
             "description": "Seller customer reference. If an existing customer has this reference, the session is bound to that customer."
           },
+          "contract_reference": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 128,
+            "description": "Your reference for the subscription contract this session creates, such as your order number. Copied to the contract's `reference` when the contract is created on finalize, so it is in every `subscription_contract.*` webhook, `subscription_contract.created` included, and `GET /api/v2/subscription-contracts/?reference=` finds the contract. Must not contain commas; not unique. Surrounding whitespace is trimmed and a blank value means no reference. Only settable here, with a secret key: the browser cannot set it and the public session payload does not include it."
+          },
           "metadata": {
             "allOf": [
               {
@@ -4497,6 +4509,11 @@
           },
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
+          },
+          "contract_reference": {
+            "type": "string",
+            "nullable": true,
+            "description": "The reference the contract gets when this session's checkout is finalized; `null` when none was given."
           }
         }
       },
@@ -4871,6 +4888,11 @@
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
           },
+          "contract_reference": {
+            "type": "string",
+            "nullable": true,
+            "description": "The `contract_reference` given when this checkout was created, or `null`. Always `null` for a checkout created in a checkout session, whose contract takes the session's `contract_reference` instead."
+          },
           "allowed_origin": {
             "type": "string",
             "description": "Origin allowed to embed hosted pages for this checkout, or an empty string when the account-level checkout origins apply."
@@ -6242,7 +6264,7 @@
             "type": "string",
             "nullable": true,
             "maxLength": 128,
-            "description": "The contract's reference in an external system, such as the seller's order number. V2 payment pages set it from their `subscription_reference` URL parameter."
+            "description": "The contract's reference in an external system, such as the seller's order number. V2 payment pages set it from their `subscription_reference` URL parameter, and checkouts from the `contract_reference` given when the checkout session, or a checkout without a session, was created."
           },
           "shipping_selection": {
             "$ref": "#/components/schemas/V2ShippingSelection"

package/src/server.ts

@@ -59,10 +59,11 @@ V2 checkout notes:
 - 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).
+- contract_reference (max 128, no commas, blank or null means none, not unique): the seller backend sets it on POST /v2/checkouts/ (no session) or POST /v2/checkout-sessions/ (secret). Copied to contract.reference when the contract is created, so it is already on subscription_contract.created and GET /v2/subscription-contracts/?reference= returns a list. Do not PATCH reference afterwards — too late for subscription_contract.created. The browser cannot set it: sending contract_reference while creating a checkout in the session is 400, and it is absent from the public session payload and browser responses. A checkout created inside a session has contract_reference null; the contract takes the session's value. GET /v2/checkout-sessions/{token}/ returns the session reference; GET /v2/checkouts/{token}/ returns the checkout's.
 - Checkout/session metadata is copied onto the contract at finalize except Askell-owned keys (askell_source, billing_anchor_mode, activation_failure, email_markers, copied_legacy_pauses, copied_legacy_extra_data, migration_source, migration_cadence_mode, legacy_subscription_ids, seed). On a shared key the session value wins.
 
 V2 contract changes:
-- reference: external id, max 128, no commas. Create: blank means none. PATCH null/blank clears. GET /v2/subscription-contracts/?reference= is an exact filter.
+- reference: external id, max 128, no commas, not unique. Create: blank means none. PATCH null/blank clears. GET /v2/subscription-contracts/?reference= is an exact filter. For a checkout-created contract, set contract_reference on the checkout or session (checkout notes); a later PATCH misses subscription_contract.created.
 - PATCH body is only metadata, reference, payment_processor_override. The operation description also lists delivery_address, accounting_department, accounting_cost_center; V2SubscriptionContractPatch does not include them — do not send them.
 - PATCH metadata replaces the integration's keys. The Askell-owned keys above keep their current values; sending them does nothing.
 - items/update apply_at=now (default): effective_at must not be in the future (400 future_effective_at_not_supported). apply_at=period_end charges nothing now and stores scheduled_change (change_id null); do not send effective_at, settlement_behavior, or include_pending_adjustments with it. A pending scheduled change rejects further item updates with 409 scheduled_change_exists until POST .../scheduled-changes/{scheduledChangeId}/cancel/ (already canceled → replayed: true; applied/failed → 409 scheduled_change_not_cancelable). items/add and items/remove can also 409 (V2ProrationConflict); their operation text does not say so. Webhook families subscription_contract_scheduled_change.* and subscription_contract_item.* are not part of subscription_contract.*. Non-migrated contract events match GET: customer is an object, numeric id is customer_id. A scheduled cancellation sends subscription_contract.ended, not canceled, even though state becomes canceled.