@lerianstudio/matcher-mcp 4.5.0-beta.16 → 4.5.0-beta.18

package/dist/spec/openapi.yaml

@@ -1155,6 +1155,38 @@ components:
       required:
         - status
       type: object
+    CheckoutBody:
+      additionalProperties: false
+      properties:
+        interval:
+          description: "Billing interval: \"monthly\" or \"annual\". It selects the payment methods the session offers — monthly is card, annual is boleto and Pix."
+          examples:
+            - monthly
+          maxLength: 16
+          type: string
+        plan:
+          description: Plan code to subscribe to. Must be a self-serve plan in the price list.
+          examples:
+            - tier_1
+          maxLength: 64
+          type: string
+      required:
+        - plan
+        - interval
+      type: object
+    CheckoutSessionResponse:
+      additionalProperties: false
+      properties:
+        sessionId:
+          description: "Processor-side session identifier, for support and correlation. It activates nothing: activation happens only through the verified webhook."
+          type: string
+        url:
+          description: Hosted checkout URL. Redirect the browser here.
+          type: string
+      required:
+        - url
+        - sessionId
+      type: object
     CloneContextRequest:
       additionalProperties: false
       properties:
@@ -2238,6 +2270,75 @@ components:
         - credentialId
         - createdAt
       type: object
+    CreditLedgerEntry:
+      additionalProperties: false
+      properties:
+        amountCents:
+          description: "How much the balance moved, in integer BRL cents. SIGNED: positive for a purchase, negative for a debit, so the entries sum to the balance."
+          format: int64
+          type: integer
+        balanceAfterCents:
+          description: The balance this movement left behind, in integer BRL cents.
+          format: int64
+          type: integer
+        createdAt:
+          description: When the movement was recorded (UTC).
+          format: date-time
+          type: string
+        period:
+          description: The enforcement period a debit was taken FOR. Omitted on a purchase, which belongs to no period, and on a trial's lifetime debit, which has none.
+          format: date-time
+          type: string
+        reason:
+          description: "Why the balance moved: \"purchase\", \"overage_debit\", or \"overage_debit_shortfall\" (the debit could not be covered in full and took the balance to zero)."
+          type: string
+        stripePaymentId:
+          description: The payment behind a purchase, for support and correlation. Omitted on a debit, which charges nothing.
+          type: string
+      required:
+        - amountCents
+        - balanceAfterCents
+        - reason
+        - createdAt
+      type: object
+    CreditLedgerPage:
+      additionalProperties: false
+      properties:
+        entries:
+          description: Recorded movements of the prepaid overage balance, newest first, capped server-side.
+          items:
+            $ref: "#/components/schemas/CreditLedgerEntry"
+          type:
+            - array
+            - "null"
+      required:
+        - entries
+      type: object
+    CreditPurchaseBody:
+      additionalProperties: false
+      properties:
+        amountCents:
+          description: How much credit to buy, in integer cents (BRL). The minimum and maximum come from the price list.
+          examples:
+            - 50000
+          format: int64
+          type: integer
+      required:
+        - amountCents
+      type: object
+    CreditPurchaseResponse:
+      additionalProperties: false
+      properties:
+        sessionId:
+          description: "Processor-side session identifier, for support and correlation. It credits nothing: the balance moves only through the verified webhook."
+          type: string
+        url:
+          description: Hosted payment URL. Redirect the browser here.
+          type: string
+      required:
+        - url
+        - sessionId
+      type: object
     CurrencyExposureResponse:
       additionalProperties: false
       properties:
@@ -5542,6 +5643,15 @@ components:
         - createdAt
         - updatedAt
       type: object
+    PortalSessionResponse:
+      additionalProperties: false
+      properties:
+        url:
+          description: Hosted customer-portal URL. Redirect the browser here. It is short-lived and single-customer.
+          type: string
+      required:
+        - url
+      type: object
     ProcessCallbackRequest:
       additionalProperties: false
       properties:
@@ -8165,6 +8275,26 @@ components:
           description: "Lines consumed against the free-trial allotment (volume axis): distinct transactions matched, so a transaction re-matched under a different classification consumes one line and not two — the same figure the quota gate enforces on. Meaningful for a trialing or lapsed workspace; 0 for a paid plan."
           format: int64
           type: integer
+        maxCreditPurchaseCents:
+          description: Largest credit purchase the payment route accepts, in integer BRL cents.
+          format: int64
+          type: integer
+        minCreditPurchaseCents:
+          description: Smallest credit purchase the payment route accepts, in integer BRL cents.
+          format: int64
+          type: integer
+        monthlyLineAllowance:
+          description: Billable lines the plan includes per month, from the price list. Monthly on every plan regardless of billing interval. 0 when the stored plan code is not in the catalogue.
+          format: int64
+          type: integer
+        overageCreditBalanceCents:
+          description: Prepaid overage credit left, in integer BRL cents. Overage is debited from it daily; an exhausted balance blocks new matching, and unspent credit never expires.
+          format: int64
+          type: integer
+        overageRateCentsPerThousandLines:
+          description: What lines beyond the allowance cost, in integer BRL cents per THOUSAND lines (per-thousand because the entry rate is 0,4 cents a line and would truncate to zero). 0 when the stored plan code is not in the catalogue.
+          format: int64
+          type: integer
         plan:
           description: Commercial plan the workspace is on ("free" or a paid tier).
           type: string
@@ -8184,6 +8314,11 @@ components:
         - linesRemaining
         - trialExpired
         - expiryReason
+        - monthlyLineAllowance
+        - overageRateCentsPerThousandLines
+        - overageCreditBalanceCents
+        - minCreditPurchaseCents
+        - maxCreditPurchaseCents
       type: object
   securitySchemes:
     BearerAuth:
@@ -15871,6 +16006,106 @@ paths:
       summary: Read the current workspace's commercial state
       tags:
         - 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.
+      operationId: workspace-billing-portal
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PortalSessionResponse"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Open the customer billing portal for the current workspace
+      tags:
+        - 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."
+      operationId: workspace-checkout
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CheckoutBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CheckoutSessionResponse"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Open a subscription checkout for the current workspace
+      tags:
+        - Onboarding
+  /v1/workspace/credit-ledger:
+    get:
+      description: "Returns the AUTHENTICATED tenant's own prepaid overage-credit movements, newest first: every purchase and every daily overage debit, each with its signed amount, the balance it left behind, and why it happened. The daily debit only does its job if the customer can see it — a balance that moves with no readable explanation is money nobody can reconcile. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the request and can only read the caller's own movements. The result is capped server-side and has no pagination. A tenant with no self-serve workspace record returns 404. Errors use the RFC 9457 application/problem+json contract."
+      operationId: workspace-credit-ledger
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreditLedgerPage"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Read the current workspace's prepaid-credit movements
+      tags:
+        - 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 may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. 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."
+      operationId: workspace-credit-purchase
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreditPurchaseBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreditPurchaseResponse"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Buy prepaid overage credit for the current workspace
+      tags:
+        - Onboarding
   /v1/workspaces/{slug}/auth-config:
     get:
       description: "Resolves the minimum a browser needs to start a PKCE login for a workspace: the console OAuth client id, the identity-provider organization, and the public issuer URL. This is a PUBLIC, anonymous, read-only, pre-tenant route: it carries no operator JWT and returns nothing about the account, its owner, or its lifecycle. It answers only for ACTIVE workspaces; a nonexistent, still-provisioning, or suspended workspace returns an IDENTICAL 404 (no enumeration of lifecycle state). The response is briefly cacheable and the route is rate-limited per client IP. Errors use the RFC 9457 application/problem+json contract."

package/package.json

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