@lerianstudio/matcher-mcp 5.0.0-beta.90 → 5.0.0-beta.92

package/dist/spec/openapi.yaml

@@ -9261,7 +9261,7 @@ paths:
         - Onboarding
   /v1/admin/workspaces/{slug}/plan:
     put:
-      description: "Puts a workspace on the contractual enterprise plan: persists plan=enterprise and billing_status=active together, then evicts the billing edge-gate and volume-resolver caches so the contractual ceiling applies immediately. ONLY \"enterprise\" is accepted. This is not a generic set-plan operation: self-serve plans are bought through hosted checkout and converged from the live subscription's price, so assigning one by hand would be a payment-processor bypass that the next processor delivery silently reverts — any other plan code returns 409. It REFUSES a workspace whose subscription the payment processor could still bill (409): the operator cancels there first, where the proration and refund decision gets human eyes, and this route never moves processor money. That refusal covers every subscription that is not permanently over — one awaiting card authentication or one that is paused is not charging today and resumes tomorrow, and it would revert this plan the moment it does; only a cancelled or expired subscription is assignable over. If the processor cannot be asked, the request is refused as retryable (503) rather than allowed through. A suspended workspace is refused (409) because this operation moves no access posture — reactivate it first, and the write is compare-and-swapped on the status read, so a suspension landing mid-request is refused rather than reversed. There is no reverse: removing the enterprise plan is not offered. The target slug comes from the URL path (backoffice operation, workspace admin action). An unknown workspace returns 404. Errors use RFC 9457 problem+json."
+      description: "Puts a workspace on the contractual enterprise plan: persists plan=enterprise and billing_status=active together, then evicts the billing edge-gate and volume-resolver caches so the contractual ceiling applies immediately. ONLY \"enterprise\" is accepted. This is not a generic set-plan operation: self-serve plans are bought through hosted checkout and converged from the live subscription's price, so assigning one by hand would be a payment-processor bypass that the next processor delivery silently reverts — any other plan code returns 409. It REFUSES a workspace whose subscription the payment processor could still bill (409): the operator cancels there first, where the proration and refund decision gets human eyes, and this route never moves processor money. That refusal covers every subscription that is not permanently over — one awaiting card authentication or one that is paused is not charging today and resumes tomorrow, and it would revert this plan the moment it does; only a cancelled or expired subscription is assignable over. If the processor cannot be asked, the request is refused as retryable (503) rather than allowed through. A suspended workspace is refused (409) because this operation moves no access posture — reactivate it first, and the write is compare-and-swapped on the status read, so a suspension landing mid-request is refused rather than reversed. There is no reverse: removing the enterprise plan is not offered. The target slug comes from the URL path (backoffice operation, workspace admin action). An unknown workspace returns 404. Errors use RFC 9457 problem+json. Every refusal on this route carries its own product code, because the sentence of a 503 is scrubbed before it leaves the process and the code is then the whole answer: 409 MTCH-0803 (a subscription the processor can still bill — cancel it there first), 409 MTCH-0804 (a plan code other than enterprise), 409 MTCH-0805 (the workspace's billing status does not allow the change — reload it), 503 MTCH-0802 (the processor could not be asked — retry) and 503 MTCH-0801 (no payment processor is configured on this deployment — NO retry clears it; the lever is configuration). MTCH-0805 is the same code the suspend and reactivate routes answer for a refused billing-status transition."
       operationId: admin-assign-workspace-plan
       parameters:
         - description: Slug of the workspace to assign the plan to.
@@ -9360,7 +9360,7 @@ paths:
         - Onboarding
   /v1/billing/webhook:
     post:
-      description: "Receives a signed billing event from the payment processor and applies it to the workspace's commercial state. This route carries NO operator JWT and no tenant identifier of any kind: a processor event has no tenant until its customer id is resolved server-side. Authentication is the Stripe-Signature signature over the RAW request body, verified inside the processor's own tolerance window. It is fail-closed on configuration — with no signing secret configured every event is rejected, and there is no value that means accept anything. Delivery is idempotent by the processor's event id: a redelivery of an event already applied returns a quiet 200 and changes nothing, an event still being applied elsewhere returns 503 so the processor retries, and an event id reused with a DIFFERENT body is a 409 rather than an acknowledgement. A processing failure returns 5xx and never records the event as applied, so the processor's retry reclaims it. Errors use the RFC 9457 application/problem+json contract and never echo the signature, the secret or the body."
+      description: "Receives a signed billing event from the payment processor and applies it to the workspace's commercial state. This route carries NO operator JWT and no tenant identifier of any kind: a processor event has no tenant until its customer id is resolved server-side. Authentication is the Stripe-Signature signature over the RAW request body, verified inside the processor's own tolerance window. It is fail-closed on configuration — with no signing secret configured every event is rejected, and there is no value that means accept anything. Delivery is idempotent by the processor's event id: a redelivery of an event already applied returns a quiet 200 and changes nothing, an event still being applied elsewhere returns 503 so the processor retries, and an event id reused with a DIFFERENT body is a 409 rather than an acknowledgement. A processing failure returns 5xx and never records the event as applied, so the processor's retry reclaims it. Errors use the RFC 9457 application/problem+json contract and never echo the signature, the secret or the body. The divergent-replay conflict carries its own product code, 409 MTCH-0811."
       operationId: receiveBillingWebhook
       parameters:
         - description: The processor's signature over the raw body, verified inside the processor's own tolerance window.
@@ -17042,7 +17042,7 @@ paths:
         - Onboarding
   /v1/signup/verify:
     post:
-      description: "Completes email verification and starts self-service onboarding. This is a PUBLIC, anonymous, pre-tenant route: it exchanges the emailed verification token for a workspace whose setup is now under way, and returns the workspace handle. It does NOT wait for setup to finish — creating the environment includes a schema migration whose duration the server does not control, so a background worker drives it to completion and the response comes back immediately. It is idempotent: a repeat call records nothing new, and a token that no longer resolves (already used or expired) returns the same 200 response. The route is rate-limited per client IP."
+      description: "Completes email verification and starts self-service onboarding. This is a PUBLIC, anonymous, pre-tenant route: it exchanges the emailed verification token for a workspace whose setup is now under way, and returns the workspace handle. It does NOT wait for setup to finish — creating the environment includes a schema migration whose duration the server does not control, so a background worker drives it to completion and the response comes back immediately. It is idempotent: a repeat call records nothing new, and a token that no longer resolves (already used or expired) returns the same 200 response. The route is rate-limited per client IP. Its two conflicts carry their own product codes, and they are not the same answer: 409 MTCH-0812 (the workspace already exists and MAY be the caller's own — sign in, or sign up under another company name) and 409 MTCH-0813 (the name belongs to another account — only a different company name clears it)."
       operationId: signup-verify
       requestBody:
         content:
@@ -17091,7 +17091,7 @@ paths:
         - Onboarding
   /v1/workspace/billing-portal:
     post:
-      description: Opens the payment processor's hosted customer portal for the AUTHENTICATED tenant's own workspace and returns the URL to redirect the browser to. Card update, invoice history and cancellation live there, not here; cancellation takes effect at the end of the period already paid for. Errors use the RFC 9457 application/problem+json contract.
+      description: "Opens the payment processor's hosted customer portal for the AUTHENTICATED tenant's own workspace and returns the URL to redirect the browser to. Card update, invoice history and cancellation live there, not here; cancellation takes effect at the end of the period already paid for. Errors use the RFC 9457 application/problem+json contract. Its two refusals carry their own product codes: 409 MTCH-0806 (plan set by contract, so there is no self-serve subscription to manage) and 409 MTCH-0810 (no billing account yet — subscribe first)."
       operationId: workspace-billing-portal
       responses:
         "200":
@@ -17113,7 +17113,7 @@ paths:
         - Onboarding
   /v1/workspace/checkout:
     post:
-      description: "Opens a hosted checkout session that subscribes the AUTHENTICATED tenant's own workspace to a self-serve plan, and returns the URL to redirect the browser to. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers, and the session is bound to the caller's tenant. The billing interval selects the payment methods — monthly is card, annual is boleto and Pix — so a session is never created with an instrument the amount cannot clear. A plan that is not self-serve, an unknown plan or interval, and a workspace that already has a subscription are all refused before the processor is called. The return URLs carry no activation-bearing parameter: the plan is activated only by the verified webhook, and the return page reads the resulting state from GET /v1/workspace/billing. Errors use the RFC 9457 application/problem+json contract."
+      description: "Opens a hosted checkout session that subscribes the AUTHENTICATED tenant's own workspace to a self-serve plan, and returns the URL to redirect the browser to. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers, and the session is bound to the caller's tenant. The billing interval selects the payment methods — monthly is card, annual is boleto and Pix — so a session is never created with an instrument the amount cannot clear. A plan that is not self-serve, an unknown plan or interval, and a workspace that already has a subscription are all refused before the processor is called. The return URLs carry no activation-bearing parameter: the plan is activated only by the verified webhook, and the return page reads the resulting state from GET /v1/workspace/billing. Errors use the RFC 9457 application/problem+json contract. Each refusal carries its own product code so a client never has to read the sentence: 409 MTCH-0806 (plan set by contract), 409 MTCH-0807 (already subscribed), 409 MTCH-0808 (a checkout is open for a different plan or interval), 409 MTCH-0809 (a checkout is being opened right now — retry), 422 MTCH-0814 (the plan is not sold self-serve) and 400 MTCH-0001 (unknown plan or interval)."
       operationId: workspace-checkout
       requestBody:
         content:
@@ -17163,7 +17163,7 @@ paths:
         - Onboarding
   /v1/workspace/credit-purchase:
     post:
-      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace on a self-serve plan may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. A workspace on a CONTRACTUAL plan is refused with 409: its volume is not metered, so prepaid overage credit buys it nothing. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract."
+      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace on a self-serve plan may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. A workspace on a CONTRACTUAL plan is refused with 409: its volume is not metered, so prepaid overage credit buys it nothing. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract. Its two refusals carry their own product codes: 422 MTCH-0815 (the amount is outside the purchasable range) and 409 MTCH-0806 (plan set by contract, so volume is not metered and credit buys nothing)."
       operationId: workspace-credit-purchase
       requestBody:
         content:

package/dist/tools/workspace/usage.js

@@ -85,7 +85,21 @@ export function registerWorkspaceUsageTool(server) {
             'incurred that the credit did not cover — what the workspace OWES). ' +
             'The second is a receivable, not a negative balance: a new billing ' +
             'period does not clear it, so never tell a customer a rollover settled ' +
-            'it, and never report it as a credit.',
+            'it, and never report it as a credit. ' +
+            'When a commercial ACTION on this workspace is refused, the refusal ' +
+            'carries a code from onboarding\'s own MTCH-08xx family and the code is ' +
+            'the answer, not the sentence: 0801 no payment processor is configured ' +
+            '(retrying never clears it) vs 0802 the processor could not be asked ' +
+            '(retry) — both arrive as a 503 whose detail is scrubbed to "internal ' +
+            'error"; 0803 a subscription the processor can still bill; 0804 only ' +
+            'the enterprise plan is operator-assigned; 0805 the billing status ' +
+            'forbids the change; 0806 the plan is set by contract, so nothing ' +
+            'self-serve applies; 0807 already subscribed; 0808 a checkout is open ' +
+            'for a different plan or interval; 0809 a checkout is being opened ' +
+            'right now; 0810 no billing account yet; 0811 a billing event id was ' +
+            'replayed with different content; 0812 the workspace exists and may be ' +
+            'the caller\'s own; 0813 the name belongs to another account; 0814 the ' +
+            'plan is not sold self-serve; 0815 the credit amount is out of range.',
     }, async (extra) => dispatchToolRequest({ method: 'GET', path: WORKSPACE_BILLING_PATH }, extra, undefined, 
     // Spread, don't rebuild: the backend's fields are relayed unchanged and
     // the derived percent is purely additive.

package/dist/tools/workspace/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/tools/workspace/usage.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,iFAAiF;AACjF,6EAA6E;AAC7E,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAI7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAE3D,2FAA2F;AAC3F,MAAM,sBAAsB,GAAG,uBAAuB,CAAA;AAatD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsC;IAEtC,IAAI,IAAI,EAAE,aAAa,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;QAC7E,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,qEAAqE;IACrE,kDAAkD;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,GAAG,gBAAgB,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAiB;IAC1D,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,gEAAgE;YAChE,sEAAsE;YACtE,iEAAiE;YACjE,kEAAkE;YAClE,uEAAuE;YACvE,0DAA0D;YAC1D,wEAAwE;YACxE,uEAAuE;YACvE,yEAAyE;YACzE,uEAAuE;YACvE,oEAAoE;YACpE,yEAAyE;YACzE,iBAAiB;YACjB,wEAAwE;YACxE,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;YAClE,yEAAyE;YACzE,gEAAgE;YAChE,sEAAsE;YACtE,mEAAmE;YACnE,mEAAmE;YACnE,qEAAqE;YACrE,oEAAoE;YACpE,wEAAwE;YACxE,sCAAsC;KACzC,EACD,KAAK,EAAE,KAAK,EAAE,EAAE,CACd,mBAAmB,CACjB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAC/C,KAAK,EACL,SAAS;IACT,wEAAwE;IACxE,0CAA0C;IAC1C,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACZ,GAAI,OAA4C;QAChD,WAAW,EAAE,WAAW,CAAC,OAA2C,CAAC;KACtE,CAAC,CACH,CACJ,CAAA;AACH,CAAC"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/tools/workspace/usage.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,iFAAiF;AACjF,6EAA6E;AAC7E,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAI7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAE3D,2FAA2F;AAC3F,MAAM,sBAAsB,GAAG,uBAAuB,CAAA;AAatD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsC;IAEtC,IAAI,IAAI,EAAE,aAAa,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;QAC7E,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,qEAAqE;IACrE,kDAAkD;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,GAAG,gBAAgB,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAiB;IAC1D,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,gEAAgE;YAChE,sEAAsE;YACtE,iEAAiE;YACjE,kEAAkE;YAClE,uEAAuE;YACvE,0DAA0D;YAC1D,wEAAwE;YACxE,uEAAuE;YACvE,yEAAyE;YACzE,uEAAuE;YACvE,oEAAoE;YACpE,yEAAyE;YACzE,iBAAiB;YACjB,wEAAwE;YACxE,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;YAClE,yEAAyE;YACzE,gEAAgE;YAChE,sEAAsE;YACtE,mEAAmE;YACnE,mEAAmE;YACnE,qEAAqE;YACrE,oEAAoE;YACpE,wEAAwE;YACxE,uCAAuC;YACvC,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,oEAAoE;YACpE,mEAAmE;YACnE,uEAAuE;YACvE,oEAAoE;YACpE,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,sEAAsE;KACzE,EACD,KAAK,EAAE,KAAK,EAAE,EAAE,CACd,mBAAmB,CACjB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAC/C,KAAK,EACL,SAAS;IACT,wEAAwE;IACxE,0CAA0C;IAC1C,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACZ,GAAI,OAA4C;QAChD,WAAW,EAAE,WAAW,CAAC,OAA2C,CAAC;KACtE,CAAC,CACH,CACJ,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerianstudio/matcher-mcp",
-  "version": "5.0.0-beta.90",
+  "version": "5.0.0-beta.92",
   "type": "module",
   "description": "Model Context Protocol server for the Matcher reconciliation engine",
   "license": "Apache-2.0",