solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/_generated/models.py

@@ -0,0 +1,3643 @@
+"""GENERATED by python/scripts/generate_client.py from openapi/sdk-v1.json. Do not edit."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+
+class ActivatePlanDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20)]
+    plan_ref: Annotated[str, Field(alias="planRef", max_length=20)]
+    product_ref: Annotated[str, Field(alias="productRef", max_length=20)]
+
+
+class ActivatePlanResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    checkout_session_id: Annotated[str | None, Field(alias="checkoutSessionId")] = None
+    checkout_url: Annotated[str | None, Field(alias="checkoutUrl")] = None
+    credit_balance: Annotated[int | float | None, Field(alias="creditBalance")] = None
+    credits_per_unit: Annotated[int | float | None, Field(alias="creditsPerUnit")] = None
+    currency: str | None = None
+    message: str | None = None
+    purchase_ref: Annotated[str | None, Field(alias="purchaseRef")] = None
+    status: Literal[
+        "activated",
+        "already_active",
+        "already_purchased",
+        "topup_required",
+        "payment_required",
+        "invalid",
+    ]
+
+
+class ApiError(BaseModel):
+    """
+    Error response. Besides the fields listed, an error can carry fields specific to its `code`.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    code: Annotated[str | None, Field(examples=["KEY_ENV_MISMATCH"])] = None
+    """
+    A stable identifier to branch on, when the error has one.
+    """
+    error: Annotated[str | None, Field(examples=["Not Found"])] = None
+    """
+    The HTTP status text.
+    """
+    errors: list[dict[str, Any]] | None = None
+    """
+    On a validation failure, one entry per invalid field.
+    """
+    message: str | list[str] | None = None
+    """
+    What went wrong, for a person to read.
+    """
+    path: str
+    """
+    The request path.
+    """
+    status_code: Annotated[int, Field(alias="statusCode", examples=[404])]
+    """
+    The HTTP status code.
+    """
+    timestamp: str
+
+
+class Estimate(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str | None, Field(pattern="^\\d+(\\.\\d{1,8})?$")] = None
+    currency: Annotated[str | None, Field(pattern="^[A-Z]{3}$")] = None
+
+
+class AuthorizeCallDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    agent_token: Annotated[str, Field(alias="agentToken", max_length=4096, min_length=1)]
+    estimate: Estimate
+    item: Annotated[str | None, Field(max_length=200, min_length=1)] = None
+    prompt_excerpt: Annotated[str | None, Field(alias="promptExcerpt", max_length=1500)] = None
+    prompt_hash: Annotated[
+        str | None, Field(alias="promptHash", pattern="^sha256:[0-9a-f]{64}$")
+    ] = None
+    request_id: Annotated[str, Field(alias="requestId", max_length=128, min_length=1)]
+    tool_error: Annotated[bool | None, Field(alias="toolError")] = None
+    wait: Annotated[int, Field(ge=0, le=55)] = 0
+
+
+class Held(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str, Field(pattern="^\\d+(\\.\\d{1,8})?$")]
+    currency: Annotated[str, Field(pattern="^[A-Z]{3}$")]
+
+
+class Reservation(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    expires_at: Annotated[str, Field(alias="expiresAt")]
+    held: Held
+
+
+class AuthorizeCallResponseDto1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    call_ref: Annotated[str, Field(alias="callRef")]
+    reservation: Reservation
+    status: Literal["allowed"]
+
+
+class AuthorizeCallResponseDto2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    call_ref: Annotated[str, Field(alias="callRef")]
+    message: str
+    reason: Literal[
+        "customer_not_linked",
+        "ask",
+        "deny",
+        "topup_required",
+        "approval_declined",
+        "approval_expired",
+    ]
+    status: Literal["refused"]
+
+
+class Approval(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    expires_at: Annotated[str, Field(alias="expiresAt")]
+    reference: str
+
+
+class AuthorizeCallResponseDto3(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    approval: Approval
+    call_ref: Annotated[str, Field(alias="callRef")]
+    message: str
+    retry_after_seconds: Annotated[int, Field(alias="retryAfterSeconds")]
+    status: Literal["waiting"]
+
+
+class AuthorizeCallResponseDto(
+    RootModel[AuthorizeCallResponseDto1 | AuthorizeCallResponseDto2 | AuthorizeCallResponseDto3]
+):
+    root: AuthorizeCallResponseDto1 | AuthorizeCallResponseDto2 | AuthorizeCallResponseDto3
+
+
+class AutoRechargeDisplayFormattedDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    threshold: Annotated[str, Field(examples=["$5.00"])]
+    """
+    Formatted threshold amount
+    """
+    topup: Annotated[str, Field(examples=["$20.00"])]
+    """
+    Formatted top-up amount
+    """
+
+
+class AutoRechargeTopupDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int | float, Field(alias="amountMinor", examples=[2000])]
+    """
+    Top-up amount in currency minor units
+    """
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    ISO 4217 currency code
+    """
+    mode: Annotated[Literal["fixed"], Field(examples=["fixed"])]
+    """
+    Top-up mode
+    """
+
+
+class AutoRechargeTriggerDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    threshold_amount_minor: Annotated[int | float, Field(alias="thresholdAmountMinor", examples=[500])]
+    """
+    Display-currency minor units for the balance threshold
+    """
+    type: Annotated[Literal["balance"], Field(examples=["balance"])]
+    """
+    Trigger kind
+    """
+
+
+class AutoRechargeTriggeredResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    triggered: Annotated[bool, Field(examples=[True])]
+    """
+    Whether the server initiated an auto-recharge charge after this debit (TOPUP credit lands via webhook)
+    """
+
+
+class AutoRechargeValidationMetaResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    max_amount_major: Annotated[int | float, Field(alias="maxAmountMajor", examples=[10000])]
+    """
+    Maximum display-currency major units accepted for threshold/top-up
+    """
+    stripe_minimum_minor_by_currency: Annotated[
+        dict[str, int | float],
+        Field(alias="stripeMinimumMinorByCurrency", examples=[{"GBP": 30, "USD": 50}]),
+    ]
+    """
+    Stripe minimum charge in minor units, keyed by ISO 4217 currency
+    """
+
+
+class Cost(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str, Field(pattern="^\\d+(\\.\\d{1,8})?$")]
+    currency: Literal["USD"]
+    source: Literal["reported", "provisional"]
+
+
+class Event(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    action_type: Annotated[
+        Literal["transaction", "api_call", "hour", "email", "storage", "custom"],
+        Field(alias="actionType"),
+    ] = "api_call"
+    cost: Cost | None = None
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    description: str | None = None
+    duration: Annotated[int | float | None, Field(ge=0.0)] = None
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    idempotency_key: Annotated[str | None, Field(alias="idempotencyKey", max_length=256)] = None
+    metadata: dict[str, Any] | None = None
+    outcome: Literal["success", "paywall", "fail"] = "success"
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20)] = None
+    purchase_ref: Annotated[str | None, Field(alias="purchaseRef", max_length=20)] = None
+    timestamp: str
+    units: Annotated[int, Field(ge=0, le=100000)] = 1
+
+
+class BulkCreateUsageRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    events: Annotated[list[Event], Field(max_length=1000, min_length=1)]
+
+
+class BusinessDetailsDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    business_name: Annotated[str | None, Field(alias="businessName")] = None
+    """
+    Legal business name
+    """
+    country: str | None = None
+    """
+    ISO 3166-1 alpha-2 country code
+    """
+    customer_city: Annotated[str | None, Field(alias="customerCity")] = None
+    """
+    Billing city
+    """
+    customer_country: Annotated[str | None, Field(alias="customerCountry")] = None
+    """
+    ISO 3166-1 alpha-2 billing country (non-business consumers)
+    """
+    customer_line1: Annotated[str | None, Field(alias="customerLine1")] = None
+    """
+    Billing address line 1
+    """
+    customer_line2: Annotated[str | None, Field(alias="customerLine2")] = None
+    """
+    Billing address line 2
+    """
+    customer_name: Annotated[str | None, Field(alias="customerName", max_length=100)] = None
+    """
+    Customer full name
+    """
+    customer_postal_code: Annotated[str | None, Field(alias="customerPostalCode")] = None
+    """
+    Billing postal code (required by Stripe Tax for US)
+    """
+    customer_ref: Annotated[str | None, Field(alias="customerRef")] = None
+    """
+    Customer reference to persist business tax details on the customer record. Only honored by the payment-intent business-details endpoint; ignored on the checkout-session endpoint.
+    """
+    customer_state: Annotated[str | None, Field(alias="customerState")] = None
+    """
+    Billing state/region
+    """
+    is_business: Annotated[bool, Field(alias="isBusiness")]
+    """
+    Whether the purchase is on behalf of a business
+    """
+    tax_id: Annotated[str | None, Field(alias="taxId")] = None
+    """
+    Tax / VAT identification number
+    """
+    tax_id_type: Annotated[
+        Literal[
+            "ae_trn",
+            "al_tin",
+            "am_tin",
+            "ao_tin",
+            "au_abn",
+            "aw_tin",
+            "az_tin",
+            "ba_tin",
+            "bb_tin",
+            "bd_bin",
+            "bf_ifu",
+            "bh_vat",
+            "bj_ifu",
+            "bs_tin",
+            "by_tin",
+            "ca_gst_hst",
+            "cd_nif",
+            "ch_vat",
+            "cl_tin",
+            "cm_niu",
+            "co_nit",
+            "cr_tin",
+            "cv_nif",
+            "ec_ruc",
+            "eg_tin",
+            "et_tin",
+            "eu_vat",
+            "gb_vat",
+            "ge_vat",
+            "gn_nif",
+            "hk_br",
+            "id_npwp",
+            "in_gst",
+            "is_vat",
+            "jp_trn",
+            "ke_pin",
+            "kg_tin",
+            "kh_tin",
+            "kr_brn",
+            "kz_bin",
+            "la_tin",
+            "li_vat",
+            "lk_vat",
+            "ma_vat",
+            "md_vat",
+            "me_pib",
+            "mk_vat",
+            "mr_nif",
+            "mx_rfc",
+            "my_sst",
+            "ng_tin",
+            "no_vat",
+            "np_pan",
+            "nz_gst",
+            "om_vat",
+            "pe_ruc",
+            "ph_tin",
+            "rs_pib",
+            "ru_inn",
+            "sa_vat",
+            "sg_gst",
+            "sn_ninea",
+            "sr_fin",
+            "th_vat",
+            "tj_tin",
+            "tr_tin",
+            "tw_vat",
+            "tz_vat",
+            "ua_vat",
+            "ug_tin",
+            "us_ein",
+            "uy_ruc",
+            "uz_vat",
+            "vn_tin",
+            "za_vat",
+            "zm_tin",
+            "zw_tin",
+        ]
+        | None,
+        Field(alias="taxIdType"),
+    ] = None
+    """
+    Tax ID type
+    """
+
+
+class CancelPurchaseRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    reason: str | None = None
+
+
+class FreeAllowance(BaseModel):
+    """
+    SDK-only free-tool allowance. Authenticated by the provider secret key, so `cap` is the provider's own declaration, not customer input.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cap: Annotated[int | None, Field(gt=0)] = None
+    meter: Annotated[str | None, Field(min_length=1, pattern="^free-[a-z0-9-]+$")] = None
+    """
+    Free meter name. Must match `/^free-[a-z0-9-]+$/`.
+    """
+    scope: Literal["rolling_window", "lifetime"] | None = None
+    window_days: Annotated[int | None, Field(alias="windowDays", ge=1)] = None
+
+
+class CheckLimitRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    free_allowance: Annotated[FreeAllowance | None, Field(alias="freeAllowance")] = None
+    """
+    SDK-only free-tool allowance. Authenticated by the provider secret key, so `cap` is the provider's own declaration, not customer input.
+    """
+    include_checkout_session: Annotated[bool | None, Field(alias="includeCheckoutSession")] = None
+    meter_name: Annotated[str | None, Field(alias="meterName")] = None
+    product_ref: Annotated[str, Field(alias="productRef", max_length=20, min_length=1)]
+    usage_type: Annotated[str | None, Field(alias="usageType")] = None
+
+
+class CloneProductDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str | None, Field(min_length=1, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$")
+    ] = None
+
+
+class Cost1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str | None, Field(pattern="^\\d+(\\.\\d{1,8})?$")] = None
+    currency: Annotated[str | None, Field(pattern="^[A-Z]{3}$")] = None
+
+
+class CompleteCallDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cost: Annotated[Cost1 | None, Field(...)]
+    interrupted: Annotated[str | None, Field(max_length=200, min_length=1)] = None
+    status: Annotated[int, Field(ge=100, le=599)]
+
+
+class Amount(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str | None, Field(pattern="^\\d+(\\.\\d{1,8})?$")] = None
+    currency: Annotated[str | None, Field(pattern="^[A-Z]{3}$")] = None
+
+
+class CompleteCallResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Amount
+    call_ref: Annotated[str, Field(alias="callRef")]
+    duplicate: bool
+    settled: bool
+    source: Literal["reported", "provisional", "none"]
+
+
+class Options(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int, Field(alias="amountMinor", ge=0)]
+    currency: str
+    kind: Literal["charge"]
+    label: str | None = None
+    meter: Annotated[str | None, Field(min_length=1)] = None
+    one_time: Annotated[bool | None, Field(alias="oneTime")] = None
+    per: Literal["unit", "seat", "flat"]
+
+
+class Options1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    anchor: str | None = None
+    count: Annotated[int | None, Field(ge=1)] = None
+    interval: Literal["week", "month", "year"]
+    kind: Literal["billingCycle"]
+
+
+class Charge(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int, Field(alias="amountMinor", ge=0)]
+    currency: str
+    label: str | None = None
+    meter: Annotated[str | None, Field(min_length=1)] = None
+    per: Literal["unit", "seat", "flat"]
+
+
+class Options2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    charge: Charge
+    from_: Annotated[int, Field(alias="from", ge=0)]
+    kind: Literal["tier"]
+    label: str | None = None
+    mode: Literal["graduated", "volume"]
+    to: Annotated[int | None, Field(ge=0)]
+
+
+class Options3(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cap: Annotated[int, Field(ge=0)]
+    kind: Literal["limit"]
+    label: str | None = None
+    meter: Annotated[str, Field(min_length=1)]
+    on_exceed: Annotated[Literal["block", "draw_credits"], Field(alias="onExceed")]
+    scope: Literal["billing_period", "lifetime", "rolling_window"]
+    window_days: Annotated[int | None, Field(alias="windowDays", ge=1)] = None
+
+
+class Options4(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    feature: Annotated[str, Field(min_length=1)]
+    kind: Literal["entitlement"]
+    label: str | None = None
+    scope: str | None = None
+    value: bool | int | float | str
+
+
+class Options5(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    days: Annotated[int, Field(ge=1)]
+    kind: Literal["trial"]
+    label: str | None = None
+    on_end: Annotated[Literal["convert", "cancel"], Field(alias="onEnd")]
+
+
+class Options6(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    applies_to: Annotated[
+        Literal["recurring", "setup", "usage", "all"] | None, Field(alias="appliesTo")
+    ] = None
+    currency: str | None = None
+    cycles: Annotated[int | None, Field(ge=1)] = None
+    duration: Literal["once", "repeating", "forever"]
+    kind: Literal["discount"]
+    label: str | None = None
+    mode: Literal["percentage", "fixed"]
+    value: Annotated[int, Field(gt=0)]
+
+
+class Options7(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["autoAssigned"]
+    label: str | None = None
+
+
+class Options8(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["hidden"]
+    label: str | None = None
+
+
+class Plan(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: Annotated[str | None, Field(max_length=3, min_length=3)] = None
+    features: dict[str, Any] | None = None
+    key: Annotated[str, Field(min_length=1)]
+    name: Annotated[str, Field(min_length=1)]
+    options: list[
+        Options
+        | Options1
+        | Options2
+        | Options3
+        | Options4
+        | Options5
+        | Options6
+        | Options7
+        | Options8
+    ]
+
+
+class ToolMappingItem(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[str, Field(min_length=1)]
+    plan_keys: Annotated[list[str], Field(alias="planKeys")]
+
+
+class ConfigureMcpPlansDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    plans: list[Plan] | None = None
+    tool_mapping: Annotated[list[ToolMappingItem] | None, Field(alias="toolMapping")] = None
+
+
+class Debited(RootModel[Literal[False]]):
+    root: Literal[False]
+
+
+class CostDebitSkippedResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    debited: Debited
+    reason: Annotated[
+        Literal["duplicate", "customer_not_found", "record_failed"], Field(examples=["duplicate"])
+    ]
+
+
+class Debited1(RootModel[Literal[True]]):
+    root: Literal[True]
+
+
+class CostDebitSuccessResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[0])]
+    """
+    Whole credits the balance dropped by (0 for a cost below one credit; the exact amount is in amountUsd)
+    """
+    amount_usd: Annotated[str, Field(alias="amountUsd", examples=["0.000043"])]
+    """
+    Exact amount debited, USD decimal string
+    """
+    auto_recharge: Annotated[AutoRechargeTriggeredResponse | None, Field(alias="autoRecharge")] = (
+        None
+    )
+    balance_credits: Annotated[int | float, Field(alias="balanceCredits", examples=[30000])]
+    """
+    Balance in whole credits after the debit
+    """
+    balance_usd: Annotated[str, Field(alias="balanceUsd", examples=["2.999957"])]
+    """
+    Exact balance after the debit, USD decimal string
+    """
+    cost_source: Annotated[Literal["reported", "provisional"], Field(alias="costSource")]
+    """
+    Set on a debit by reported cost: whether the cost was reported or an estimate
+    """
+    debited: Debited1
+
+
+class CreateCheckoutSessionRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    plan_ref: Annotated[str | None, Field(alias="planRef", max_length=20)] = None
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20, min_length=1)] = (
+        None
+    )
+    purpose: Literal["credit_topup"] | None = None
+    return_url: Annotated[str | None, Field(alias="returnUrl")] = None
+
+
+class CreateCheckoutSessionResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    checkout_url: Annotated[
+        str,
+        Field(
+            alias="checkoutUrl",
+            examples=["https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788"],
+        ),
+    ]
+    """
+    Full checkout URL based on backend configuration (ready to redirect customer)
+    """
+    session_id: Annotated[
+        str, Field(alias="sessionId", examples=["e3f1c2d4b6a89f001122334455667788"])
+    ]
+    """
+    Checkout session ID/token
+    """
+
+
+class Telephone(RootModel[str]):
+    root: Annotated[str, Field(pattern="^\\+[1-9]\\d{6,14}$")]
+
+
+class CreateCustomerRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    description: Annotated[str | None, Field(max_length=1000)] = None
+    email: str
+    external_ref: Annotated[str | None, Field(alias="externalRef", max_length=50)] = None
+    metadata: dict[str, Any] | None = None
+    name: Annotated[
+        str | None, Field(max_length=100, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$")
+    ] = None
+    telephone: Telephone | Literal[""] | None = None
+
+
+class CreateCustomerSessionRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20)] = None
+
+
+class CreateCustomerSessionResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_url: Annotated[
+        str,
+        Field(
+            alias="customerUrl",
+            examples=["https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788"],
+        ),
+    ]
+    """
+    Full customer URL based on backend configuration (ready to redirect customer)
+    """
+    session_id: Annotated[
+        str, Field(alias="sessionId", examples=["e3f1c2d4b6a89f001122334455667788"])
+    ]
+    """
+    Customer session ID/token
+    """
+
+
+class AutoRecharge(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: str | None = None
+    enabled: bool | None = None
+    max_monthly_spend_major: Annotated[
+        int | float | None, Field(alias="maxMonthlySpendMajor", gt=0.0, le=10000.0)
+    ] = None
+    threshold_amount_major: Annotated[
+        int | float | None, Field(alias="thresholdAmountMajor", gt=0.0, le=10000.0)
+    ] = None
+    topup_amount_major: Annotated[
+        int | float | None, Field(alias="topupAmountMajor", gt=0.0, le=10000.0)
+    ] = None
+    trigger_type: Annotated[Literal["balance"] | None, Field(alias="triggerType")] = None
+
+
+class CreatePaymentIntentDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | None, Field(ge=100, le=10000000)] = None
+    auto_recharge: Annotated[AutoRecharge | None, Field(alias="autoRecharge")] = None
+    currency: str | None = None
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    description: Annotated[str | None, Field(max_length=500)] = None
+    plan_ref: Annotated[str | None, Field(alias="planRef", max_length=20, min_length=1)] = None
+    pricing_tier: Annotated[str | None, Field(alias="pricingTier")] = None
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20, min_length=1)] = (
+        None
+    )
+    purpose: Literal["product", "credit_topup", "usage_billing"] = "product"
+
+
+class Options9(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int, Field(alias="amountMinor", ge=0)]
+    currency: str
+    kind: Literal["charge"]
+    label: str | None = None
+    meter: Annotated[str | None, Field(min_length=1)] = None
+    one_time: Annotated[bool | None, Field(alias="oneTime")] = None
+    per: Literal["unit", "seat", "flat"]
+
+
+class Options10(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    anchor: str | None = None
+    count: Annotated[int | None, Field(ge=1)] = None
+    interval: Literal["week", "month", "year"]
+    kind: Literal["billingCycle"]
+
+
+class Options11(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    charge: Charge
+    from_: Annotated[int, Field(alias="from", ge=0)]
+    kind: Literal["tier"]
+    label: str | None = None
+    mode: Literal["graduated", "volume"]
+    to: Annotated[int | None, Field(ge=0)]
+
+
+class Options12(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cap: Annotated[int, Field(ge=0)]
+    kind: Literal["limit"]
+    label: str | None = None
+    meter: Annotated[str, Field(min_length=1)]
+    on_exceed: Annotated[Literal["block", "draw_credits"], Field(alias="onExceed")]
+    scope: Literal["billing_period", "lifetime", "rolling_window"]
+    window_days: Annotated[int | None, Field(alias="windowDays", ge=1)] = None
+
+
+class Options13(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    feature: Annotated[str, Field(min_length=1)]
+    kind: Literal["entitlement"]
+    label: str | None = None
+    scope: str | None = None
+    value: bool | int | float | str
+
+
+class Options14(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    days: Annotated[int, Field(ge=1)]
+    kind: Literal["trial"]
+    label: str | None = None
+    on_end: Annotated[Literal["convert", "cancel"], Field(alias="onEnd")]
+
+
+class Options15(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    applies_to: Annotated[
+        Literal["recurring", "setup", "usage", "all"] | None, Field(alias="appliesTo")
+    ] = None
+    currency: str | None = None
+    cycles: Annotated[int | None, Field(ge=1)] = None
+    duration: Literal["once", "repeating", "forever"]
+    kind: Literal["discount"]
+    label: str | None = None
+    mode: Literal["percentage", "fixed"]
+    value: Annotated[int, Field(gt=0)]
+
+
+class Options16(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["autoAssigned"]
+    label: str | None = None
+
+
+class Options17(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["hidden"]
+    label: str | None = None
+
+
+class CreatePlanRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    access_expiry_days: Annotated[int | None, Field(alias="accessExpiryDays", ge=0)] = None
+    currency: Annotated[str | None, Field(max_length=3, min_length=3)] = None
+    description: Annotated[str | None, Field(max_length=500)] = None
+    features: dict[str, Any] | None = None
+    max_active_users: Annotated[int | None, Field(alias="maxActiveUsers", ge=0)] = None
+    metadata: dict[str, Any] | None = None
+    name: Annotated[
+        str, Field(max_length=200, min_length=2, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$")
+    ]
+    options: list[
+        Options9
+        | Options10
+        | Options11
+        | Options12
+        | Options13
+        | Options14
+        | Options15
+        | Options16
+        | Options17
+    ]
+    status: Literal["active", "inactive", "archived"] | None = None
+    tax_behavior: Annotated[
+        Literal["auto", "inclusive", "exclusive"] | None, Field(alias="taxBehavior")
+    ] = None
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    delivery_method: Annotated[str | None, Field(alias="deliveryMethod")] = None
+    fulfillment_type: Annotated[str | None, Field(alias="fulfillmentType")] = None
+    validity_period: Annotated[int | None, Field(alias="validityPeriod", gt=0)] = None
+
+
+class CreateProductRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    config: Config | None = None
+    description: Annotated[str | None, Field(max_length=1000)] = None
+    image_url: Annotated[str | None, Field(alias="imageUrl")] = None
+    is_managed_mcp: Annotated[bool | None, Field(alias="isManagedMcp")] = None
+    is_mcp_pay: Annotated[bool | None, Field(alias="isMcpPay")] = None
+    metadata: dict[str, Any] | None = None
+    name: Annotated[
+        str, Field(max_length=100, min_length=2, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$")
+    ]
+    product_type: Annotated[str | None, Field(alias="productType", max_length=100)] = None
+    tax_behavior: Annotated[
+        Literal["auto", "inclusive", "exclusive"] | None, Field(alias="taxBehavior")
+    ] = None
+
+
+class Cost2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[str | None, Field(pattern="^\\d+(\\.\\d{1,8})?$")] = None
+    currency: Literal["USD"] | None = None
+    source: Literal["reported", "provisional"] | None = None
+
+
+class CreateUsageRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    action_type: Annotated[
+        Literal["transaction", "api_call", "hour", "email", "storage", "custom"],
+        Field(alias="actionType"),
+    ] = "api_call"
+    cost: Cost2 | None = None
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    description: str | None = None
+    duration: Annotated[int | float | None, Field(ge=0.0)] = None
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    idempotency_key: Annotated[str | None, Field(alias="idempotencyKey", max_length=256)] = None
+    metadata: dict[str, Any] | None = None
+    outcome: Literal["success", "paywall", "fail"] = "success"
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20)] = None
+    purchase_ref: Annotated[str | None, Field(alias="purchaseRef", max_length=20)] = None
+    timestamp: str
+    units: Annotated[int, Field(ge=0, le=100000)] = 1
+
+
+class CreditActivityEntryDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[-200])]
+    """
+    Signed credit units on the USD peg (100 credits = 1 USD cent)
+    """
+    balance: Annotated[int | float, Field(examples=[599800])]
+    """
+    Running credit balance after this event
+    """
+    product_name: Annotated[str | None, Field(alias="productName")] = None
+    """
+    Product display name when the event is product-scoped
+    """
+    product_ref: Annotated[str | None, Field(alias="productRef")] = None
+    """
+    Product reference when the event is product-scoped
+    """
+    reason: str | None = None
+    """
+    Machine-readable reason when the ledger stored one
+    """
+    timestamp: Annotated[str, Field(examples=["2026-09-05T14:22:00.000Z"])]
+    """
+    ISO-8601 timestamp
+    """
+    type: Literal["USAGE", "TOPUP", "GRANT", "REFUND", "ADJUSTMENT"]
+    """
+    Ledger event type
+    """
+
+
+class CreditActivityResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    entries: list[CreditActivityEntryDto]
+    has_more: Annotated[bool, Field(alias="hasMore", examples=[False])]
+    """
+    True when more events exist beyond this page
+    """
+
+
+class Debited2(RootModel[Literal[False]]):
+    root: Literal[False]
+
+
+class CreditDebitSkippedResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    debited: Debited2
+    reason: Annotated[
+        Literal[
+            "duplicate",
+            "no_product_ref",
+            "customer_not_found",
+            "no_active_purchase",
+            "plan_not_credit_based",
+            "not_credit_drawn",
+            "within_included",
+            "free_meter",
+        ],
+        Field(examples=["duplicate"]),
+    ]
+    """
+    Reason no credit debit was recorded
+    """
+
+
+class Debited3(RootModel[Literal[True]]):
+    root: Literal[True]
+
+
+class CreditDebitSuccessResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[100])]
+    """
+    Credits debited for this usage event (credits are USD-pegged at 100 credits per minor unit, so a 1¢/unit charge debits 100 credits/unit)
+    """
+    auto_recharge: Annotated[AutoRechargeTriggeredResponse | None, Field(alias="autoRecharge")] = (
+        None
+    )
+    debited: Debited3
+    remaining_units: Annotated[int | float, Field(alias="remainingUnits", examples=[99])]
+    """
+    How many metered items the remaining credit balance still covers
+    """
+    units_remaining: Annotated[int | float, Field(alias="unitsRemaining", deprecated=True, examples=[99])]
+    """
+    Deprecated alias of remainingUnits. Prefer remainingUnits.
+    """
+
+
+class CustomerBalanceDisplayDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_major: Annotated[int | float, Field(alias="amountMajor", examples=[42])]
+    """
+    Balance amount in the display currency major units (e.g. dollars)
+    """
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    ISO 4217 display currency code
+    """
+    exchange_rate: Annotated[int | float, Field(alias="exchangeRate", examples=[1])]
+    """
+    Exchange rate applied from USD to the display currency
+    """
+    formatted: Annotated[str, Field(examples=["$42.00"])]
+    """
+    Human-readable formatted balance
+    """
+    rate_source: Annotated[
+        Literal["parity", "db", "fallback", "funding"],
+        Field(alias="rateSource", examples=["parity"]),
+    ]
+    """
+    Source of the exchange rate used
+    """
+
+
+class CustomerBalanceResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    credits: Annotated[int | float, Field(examples=[4200])]
+    """
+    Raw credit balance in credits (100 credits = 1 minor currency unit)
+    """
+    credits_per_minor_unit: Annotated[int | float, Field(alias="creditsPerMinorUnit", examples=[100])]
+    """
+    Number of credits per minor currency unit
+    """
+    customer_ref: Annotated[str, Field(alias="customerRef", examples=["cus_3c4d5e6f7g8h"])]
+    """
+    Customer reference identifier
+    """
+    display: CustomerBalanceDisplayDto
+    """
+    Formatted balance display block for the display currency
+    """
+    display_currency: Annotated[str, Field(alias="displayCurrency", examples=["USD"])]
+    """
+    ISO 4217 display currency code
+    """
+    display_exchange_rate: Annotated[int | float, Field(alias="displayExchangeRate", examples=[1])]
+    """
+    Exchange rate from USD to the display currency
+    """
+
+
+class DisableAutoRechargeResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    success: Annotated[bool, Field(examples=[True])]
+    """
+    Whether auto-recharge was disabled
+    """
+
+
+class GrantCustomerCreditsRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    credits: Annotated[int, Field(gt=0)]
+    reason: Annotated[str | None, Field(max_length=256)] = None
+
+
+class GrantCustomerCreditsResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    balance: int | float
+    """
+    Customer credit balance after the grant
+    """
+    credits: int | float
+    """
+    Granted credit amount
+    """
+    customer_ref: Annotated[str, Field(alias="customerRef")]
+    """
+    Customer reference identifier
+    """
+    reason: str | None = None
+    """
+    Machine-readable grant reason
+    """
+    success: bool
+    """
+    Whether the grant was recorded
+    """
+
+
+class LimitAutoRechargeDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    enabled: bool
+    """
+    Whether auto-recharge is enabled for this provider
+    """
+    status: str | None = None
+    """
+    Stored auto-recharge status when a config exists
+    """
+
+
+class LimitBalanceDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    credit_balance: Annotated[int | float, Field(alias="creditBalance")]
+    """
+    Credit balance in credits (100 credits = 1 minor currency unit)
+    """
+    credits_per_minor_unit: Annotated[int | float | None, Field(alias="creditsPerMinorUnit")] = None
+    """
+    Credits per minor unit of `currency` (typically 100)
+    """
+    credits_per_unit: Annotated[int | float, Field(alias="creditsPerUnit")]
+    """
+    Credits deducted per metered item (wallet coverage: remainingUnits = balance / creditsPerUnit)
+    """
+    currency: str
+    display_exchange_rate: Annotated[int | float | None, Field(alias="displayExchangeRate")] = None
+    """
+    USD → display-currency rate used with creditsPerMinorUnit
+    """
+    remaining_units: Annotated[int | float | None, Field(alias="remainingUnits")] = None
+    """
+    How many metered items the credit balance still covers (`balance / creditsPerUnit`)
+    """
+
+
+class LimitPlanItemDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    billing_cycle: Annotated[str | None, Field(alias="billingCycle")] = None
+    """
+    Derived billing cycle
+    """
+    checkout_url: Annotated[str | None, Field(alias="checkoutUrl")] = None
+    """
+    Deep link that opens hosted checkout with this plan preselected. Present only when a checkout session was minted for this response.
+    """
+    credits_per_unit: Annotated[int | float | None, Field(alias="creditsPerUnit", deprecated=True)] = None
+    """
+    Deprecated alias of perUnitChargeMinor. Same minor-units value — not credits. Prefer perUnitChargeMinor.
+    """
+    currency: str
+    free_units: Annotated[int | float | None, Field(alias="freeUnits")] = None
+    """
+    Derived included allowance for the metered meter. `0` is the unlimited sentinel (`LimitOption.cap === 0`).
+    """
+    name: str | None = None
+    options: list[dict[str, Any]] | None = None
+    """
+    Composable pricing options for this plan
+    """
+    per_unit_charge_minor: Annotated[int | float | None, Field(alias="perUnitChargeMinor")] = None
+    """
+    Per-request charge in minor currency units (usage-based plans)
+    """
+    price: int | float
+    """
+    Headline price in smallest currency unit (e.g. cents)
+    """
+    reference: str
+    requires_payment: Annotated[bool, Field(alias="requiresPayment")]
+    type: str
+    """
+    Derived plan type
+    """
+
+
+class LimitProductBriefDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: str | None = None
+    reference: str
+
+
+class LimitResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    activation_required: Annotated[bool | None, Field(alias="activationRequired")] = None
+    """
+    True when the customer must activate a priced default plan before usage is allowed
+    """
+    auto_recharge: Annotated[LimitAutoRechargeDto | None, Field(alias="autoRecharge")] = None
+    """
+    Per-provider auto-recharge snapshot read off the customer document. Omitted when no config exists.
+    """
+    balance: LimitBalanceDto | None = None
+    """
+    Prepaid usage balance context when the default plan is usage-based
+    """
+    checkout_session_id: Annotated[
+        str | None, Field(alias="checkoutSessionId", examples=["e3f1c2d4b6a89f001122334455667788"])
+    ] = None
+    """
+    Checkout session ID if payment is required
+    """
+    checkout_url: Annotated[
+        str | None,
+        Field(
+            alias="checkoutUrl",
+            examples=["https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788"],
+        ),
+    ] = None
+    """
+    Checkout URL if payment is required
+    """
+    confirmation_url: Annotated[str | None, Field(alias="confirmationUrl")] = None
+    """
+    Customer portal confirmation URL when activation is required (fallback when not starting checkout)
+    """
+    credit_balance: Annotated[int | float | None, Field(alias="creditBalance")] = None
+    """
+    Credit balance in credits (100 credits = 1 minor currency unit), for pre-paid usage-based plans
+    """
+    credits_per_unit: Annotated[int | float | None, Field(alias="creditsPerUnit")] = None
+    """
+    Credits deducted per metered item (for prepaid usage-based plans)
+    """
+    currency: str | None = None
+    """
+    ISO 4217 currency code for credit fields
+    """
+    limit: int | float | None = None
+    """
+    The effective finite cap for this meter. Present only when the backend measured a finite cap.
+    """
+    meter_name: Annotated[str | None, Field(alias="meterName", examples=["requests"])] = None
+    """
+    The meter name to use when tracking usage events
+    """
+    needs_top_up: Annotated[bool | None, Field(alias="needsTopUp")] = None
+    """
+    Access is blocked until prepaid credits cover the next unit — past an included cap with `onExceed: draw_credits`, or from the first unit on a recurring meter with no limit.
+    """
+    overage: bool | None = None
+    """
+    Access is granted past the included cap and the usage is paid from prepaid credits — `onExceed: draw_credits`.
+    """
+    paywall_reason: Annotated[
+        Literal["activation_required", "topup_required", "payment_required", "limit_reached"]
+        | None,
+        Field(alias="paywallReason"),
+    ] = None
+    """
+    Authoritative paywall classification shared with Managed MCP. Present on denial responses only.
+    """
+    plan_name: Annotated[str | None, Field(alias="planName")] = None
+    """
+    Display name of the active or default plan
+    """
+    plan_ref: Annotated[str | None, Field(alias="planRef")] = None
+    """
+    Active plan reference when the customer already holds a purchase
+    """
+    plans: list[LimitPlanItemDto] | None = None
+    """
+    Active plans on the product available for activation or checkout
+    """
+    product: LimitProductBriefDto | None = None
+    """
+    Product the limit check applies to
+    """
+    purchase_ref: Annotated[str | None, Field(alias="purchaseRef")] = None
+    """
+    Active purchase reference when the customer already holds a purchase
+    """
+    remaining: Annotated[int | float, Field(examples=[997])]
+    """
+    Remaining usage units before hitting the limit. `-1` means unlimited (no finite cap).
+    """
+    used: int | float | None = None
+    """
+    Consumed usage units this period. Present only when the backend measured a finite cap.
+    """
+    within_limits: Annotated[bool, Field(alias="withinLimits", examples=[True])]
+    """
+    Whether the customer is within their usage limits
+    """
+
+
+class Options18(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int, Field(alias="amountMinor", ge=0)]
+    currency: str
+    kind: Literal["charge"]
+    label: str | None = None
+    meter: Annotated[str | None, Field(min_length=1)] = None
+    one_time: Annotated[bool | None, Field(alias="oneTime")] = None
+    per: Literal["unit", "seat", "flat"]
+
+
+class Options19(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    anchor: str | None = None
+    count: Annotated[int | None, Field(ge=1)] = None
+    interval: Literal["week", "month", "year"]
+    kind: Literal["billingCycle"]
+
+
+class Options20(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    charge: Charge
+    from_: Annotated[int, Field(alias="from", ge=0)]
+    kind: Literal["tier"]
+    label: str | None = None
+    mode: Literal["graduated", "volume"]
+    to: Annotated[int | None, Field(ge=0)]
+
+
+class Options21(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cap: Annotated[int, Field(ge=0)]
+    kind: Literal["limit"]
+    label: str | None = None
+    meter: Annotated[str, Field(min_length=1)]
+    on_exceed: Annotated[Literal["block", "draw_credits"], Field(alias="onExceed")]
+    scope: Literal["billing_period", "lifetime", "rolling_window"]
+    window_days: Annotated[int | None, Field(alias="windowDays", ge=1)] = None
+
+
+class Options22(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    feature: Annotated[str, Field(min_length=1)]
+    kind: Literal["entitlement"]
+    label: str | None = None
+    scope: str | None = None
+    value: bool | int | float | str
+
+
+class Options23(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    days: Annotated[int, Field(ge=1)]
+    kind: Literal["trial"]
+    label: str | None = None
+    on_end: Annotated[Literal["convert", "cancel"], Field(alias="onEnd")]
+
+
+class Options24(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    applies_to: Annotated[
+        Literal["recurring", "setup", "usage", "all"] | None, Field(alias="appliesTo")
+    ] = None
+    currency: str | None = None
+    cycles: Annotated[int | None, Field(ge=1)] = None
+    duration: Literal["once", "repeating", "forever"]
+    kind: Literal["discount"]
+    label: str | None = None
+    mode: Literal["percentage", "fixed"]
+    value: Annotated[int, Field(gt=0)]
+
+
+class Options25(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["autoAssigned"]
+    label: str | None = None
+
+
+class Options26(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["hidden"]
+    label: str | None = None
+
+
+class Plan1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: Annotated[str | None, Field(max_length=3, min_length=3)] = None
+    features: dict[str, Any] | None = None
+    key: Annotated[str, Field(min_length=1)]
+    name: Annotated[str, Field(min_length=1)]
+    options: list[
+        Options18
+        | Options19
+        | Options20
+        | Options21
+        | Options22
+        | Options23
+        | Options24
+        | Options25
+        | Options26
+    ]
+
+
+class Tool(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    description: str | None = None
+    name: Annotated[str, Field(min_length=1)]
+    no_plan: Annotated[bool | None, Field(alias="noPlan")] = None
+    plan_keys: Annotated[list[str] | None, Field(alias="planKeys")] = None
+
+
+class McpBootstrapDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    auth_api_key: Annotated[str | None, Field(alias="authApiKey")] = None
+    auth_header_name: Annotated[
+        str | None,
+        Field(
+            alias="authHeaderName",
+            max_length=64,
+            min_length=1,
+            pattern="^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$",
+        ),
+    ] = None
+    description: str | None = None
+    image_url: Annotated[str | None, Field(alias="imageUrl")] = None
+    mcp_domain: Annotated[str | None, Field(alias="mcpDomain")] = None
+    metadata: dict[str, Any] | None = None
+    name: str | None = None
+    origin_url: Annotated[str, Field(alias="originUrl")]
+    plans: list[Plan1] | None = None
+    product_type: Annotated[str | None, Field(alias="productType")] = None
+    tools: list[Tool] | None = None
+
+
+class AutoMappedTool(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    description: str | None = None
+    name: str | None = None
+
+
+class OneTimePurchaseInfo(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[9900])]
+    """
+    Amount in USD cents (normalised for aggregation)
+    """
+    completed_at: Annotated[str, Field(alias="completedAt", examples=["2025-10-27T10:00:00Z"])]
+    """
+    When the one-time purchase was completed
+    """
+    created_at: Annotated[str, Field(alias="createdAt")]
+    """
+    Created at
+    """
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    ISO 4217 currency code of the customer-facing charge
+    """
+    customer_ref: Annotated[str, Field(alias="customerRef", examples=["cus_3C4D5E6F"])]
+    """
+    Customer reference
+    """
+    product_ref: Annotated[str | None, Field(alias="productRef", examples=["prd_abc123"])] = None
+    """
+    Product reference
+    """
+    reference: Annotated[str, Field(examples=["pur_1A2B3C4D"])]
+    """
+    Purchase reference
+    """
+
+
+class Plan2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    access_expiry_days: Annotated[int | float | None, Field(alias="accessExpiryDays")] = None
+    """
+    Access expiry in days
+    """
+    created_at: Annotated[str, Field(alias="createdAt")]
+    """
+    Creation timestamp
+    """
+    currency: Annotated[str | None, Field(examples=["USD"])] = None
+    """
+    Currency code (ISO 4217)
+    """
+    currency_symbol: Annotated[str | None, Field(alias="currencySymbol", examples=["$"])] = None
+    """
+    Currency symbol (derived from currency)
+    """
+    description: Annotated[str | None, Field(examples=["Best for teams getting started"])] = None
+    """
+    Plan description
+    """
+    features: dict[str, Any] | None = None
+    """
+    Plan features
+    """
+    is_active: Annotated[bool, Field(alias="isActive", examples=[True])]
+    """
+    Whether the plan is active (derived from status)
+    """
+    max_active_users: Annotated[int | float | None, Field(alias="maxActiveUsers")] = None
+    """
+    Maximum number of active users
+    """
+    name: Annotated[str | None, Field(examples=["Starter"])] = None
+    """
+    Plan name
+    """
+    options: list[dict[str, Any]]
+    """
+    Composable pricing options (money as integer minor units)
+    """
+    price: Annotated[int | float | None, Field(examples=[2999])] = None
+    """
+    Derived headline price in minor units (the base or one-time charge)
+    """
+    reference: Annotated[str, Field(examples=["pln_1A2B3C4D"])]
+    """
+    Plan reference
+    """
+    requires_payment: Annotated[bool | None, Field(alias="requiresPayment", examples=[True])] = None
+    """
+    Whether payment is required
+    """
+    status: Annotated[str, Field(examples=["active"])]
+    """
+    Plan status
+    """
+    type: Annotated[
+        Literal["recurring", "one-time", "usage-based", "hybrid"], Field(examples=["recurring"])
+    ]
+    """
+    Derived plan type (read from options)
+    """
+    updated_at: Annotated[str, Field(alias="updatedAt")]
+    """
+    Last update timestamp
+    """
+
+
+class ProcessPaymentCancelled(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    status: Annotated[Literal["cancelled"], Field(examples=["cancelled"])]
+
+
+class ProcessPaymentFailed(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    status: Annotated[Literal["failed"], Field(examples=["failed"])]
+
+
+class ProcessPaymentIntentDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    plan_ref: Annotated[str | None, Field(alias="planRef", max_length=20)] = None
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20, min_length=1)] = (
+        None
+    )
+
+
+class ProcessPaymentProcessing(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    status: Annotated[Literal["processing"], Field(examples=["processing"])]
+
+
+class ProcessPaymentSucceededBare(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    status: Annotated[Literal["succeeded"], Field(examples=["succeeded"])]
+
+
+class ProcessPaymentSucceededOneTime(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    one_time_purchase: Annotated[OneTimePurchaseInfo, Field(alias="oneTimePurchase")]
+    status: Annotated[Literal["succeeded"], Field(examples=["succeeded"])]
+    type: Annotated[Literal["one-time"], Field(examples=["one-time"])]
+
+
+class ProcessPaymentTimeout(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    message: str | None = None
+    """
+    Detail message describing the timeout
+    """
+    status: Annotated[Literal["timeout"], Field(examples=["timeout"])]
+
+
+class ProductConfigDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    delivery_method: Annotated[str | None, Field(alias="deliveryMethod", examples=["api"])] = None
+    """
+    Delivery method
+    """
+    fulfillment_type: Annotated[
+        str | None, Field(alias="fulfillmentType", examples=["digital"])
+    ] = None
+    """
+    Fulfillment type
+    """
+    validity_period: Annotated[int | float | None, Field(alias="validityPeriod", examples=[30])] = None
+    """
+    Validity period in days
+    """
+
+
+class PutAutoRechargeSdkDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: str
+    customer_email: Annotated[str | None, Field(alias="customerEmail")] = None
+    customer_name: Annotated[str | None, Field(alias="customerName")] = None
+    customer_ref: Annotated[str, Field(alias="customerRef", min_length=1)]
+    defer_setup_intent: Annotated[bool | None, Field(alias="deferSetupIntent")] = None
+    enabled: bool
+    max_monthly_spend_major: Annotated[
+        int | float | None, Field(alias="maxMonthlySpendMajor", gt=0.0, le=10000.0)
+    ] = None
+    threshold_amount_major: Annotated[
+        int | float | None, Field(alias="thresholdAmountMajor", gt=0.0, le=10000.0)
+    ] = None
+    topup_amount_major: Annotated[
+        int | float | None, Field(alias="topupAmountMajor", gt=0.0, le=10000.0)
+    ] = None
+    trigger_type: Annotated[Literal["balance"], Field(alias="triggerType")]
+
+
+class Event1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    meter_name: Annotated[str, Field(alias="meterName", min_length=1)]
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20)] = None
+    properties: dict[str, Any] | None = None
+    timestamp: str | None = None
+    value: int | float | None = None
+
+
+class RecordBulkMeterEventsZodDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    events: Annotated[list[Event1], Field(min_length=1)]
+
+
+class RecordMeterEventZodDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    meter_name: Annotated[str, Field(alias="meterName", min_length=1)]
+    product_ref: Annotated[str | None, Field(alias="productRef", max_length=20)] = None
+    properties: dict[str, Any] | None = None
+    timestamp: str | None = None
+    value: int | float | None = None
+
+
+class SdkMerchantResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    city: Annotated[str | None, Field(examples=["London"])] = None
+    """
+    City from the legal entity address
+    """
+    company_number: Annotated[str | None, Field(alias="companyNumber", examples=["HRB12345"])] = (
+        None
+    )
+    """
+    Company registration number (EIN, Companies House No, Org No)
+    """
+    country: Annotated[str | None, Field(examples=["US"])] = None
+    """
+    ISO-3166 alpha-2 country code of the merchant
+    """
+    default_currency: Annotated[str | None, Field(alias="defaultCurrency", examples=["usd"])] = None
+    """
+    ISO-4217 default settlement currency
+    """
+    display_name: Annotated[str, Field(alias="displayName", examples=["Acme"])]
+    """
+    Brand name shown in UI
+    """
+    icon_url: Annotated[
+        str | None, Field(alias="iconUrl", examples=["https://cdn.acme.com/icon.png"])
+    ] = None
+    """
+    Absolute URL to the square app icon / logomark. Consumed by MCP host chromes, mobile avatar slots, and any surface where the landscape `logoUrl` would need letterboxing.
+    """
+    legal_name: Annotated[str, Field(alias="legalName", examples=["Acme Inc."])]
+    """
+    Legal entity name used in SCA mandate copy
+    """
+    logo_url: Annotated[
+        str | None, Field(alias="logoUrl", examples=["https://cdn.acme.com/logo.png"])
+    ] = None
+    """
+    Absolute URL to the merchant logo
+    """
+    privacy_url: Annotated[
+        str | None, Field(alias="privacyUrl", examples=["https://acme.com/privacy"])
+    ] = None
+    state_or_county: Annotated[
+        str | None, Field(alias="stateOrCounty", examples=["Greater London"])
+    ] = None
+    """
+    State, county, or region from the legal entity address. Free text — values like "Greater London" are valid.
+    """
+    statement_descriptor: Annotated[
+        str | None, Field(alias="statementDescriptor", examples=["ACME INC"])
+    ] = None
+    """
+    Descriptor appearing on the customer card statement
+    """
+    support_email: Annotated[
+        str | None, Field(alias="supportEmail", examples=["support@acme.com"])
+    ] = None
+    support_url: Annotated[
+        str | None, Field(alias="supportUrl", examples=["https://acme.com/support"])
+    ] = None
+    supported_topup_currencies: Annotated[
+        list[str] | None, Field(alias="supportedTopupCurrencies", examples=[["USD", "EUR", "GBP"]])
+    ] = None
+    """
+    Full set of currencies a customer may pay credit topups in, including the default currency. Omitted/single-entry means single-currency behavior.
+    """
+    tax_id: Annotated[str | None, Field(alias="taxId", examples=["12-3456789"])] = None
+    """
+    Tax identification number (US: EIN)
+    """
+    terms_url: Annotated[
+        str | None, Field(alias="termsUrl", examples=["https://acme.com/terms"])
+    ] = None
+    vat_number: Annotated[str | None, Field(alias="vatNumber", examples=["DE123456789"])] = None
+    """
+    VAT identification number (UK/EU)
+    """
+    website_url: Annotated[str | None, Field(alias="websiteUrl", examples=["https://acme.com"])] = (
+        None
+    )
+    """
+    Merchant public website. Distinct from supportUrl so the same URL is not emitted twice.
+    """
+
+
+class SdkPaymentIntentListItem(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[4999])]
+    """
+    Amount in USD minor units (ledger/normalised); `currency` is the presentment currency
+    """
+    client_secret: Annotated[
+        str | None, Field(alias="clientSecret", examples=["pi_1a2b3c4d5e6f7g8h_secret_xxx"])
+    ] = None
+    """
+    Client secret used to confirm the payment on the client
+    """
+    created_at: Annotated[
+        str | None, Field(alias="createdAt", examples=["2025-10-11T10:30:00.000Z"])
+    ] = None
+    """
+    Creation timestamp
+    """
+    currency: Annotated[str, Field(examples=["usd"])]
+    """
+    ISO 4217 presentment (charge) currency code
+    """
+    plan_ref: Annotated[str | None, Field(alias="planRef", examples=["pln_2b3c4d5e6f7g"])] = None
+    """
+    Plan reference
+    """
+    processor_payment_id: Annotated[
+        str, Field(alias="processorPaymentId", examples=["pi_1a2b3c4d5e6f7g8h"])
+    ]
+    """
+    Payment processor payment intent ID
+    """
+    status: Annotated[
+        Literal[
+            "pending",
+            "requires_payment_method",
+            "requires_confirmation",
+            "requires_action",
+            "processing",
+            "succeeded",
+            "failed",
+            "cancelled",
+        ],
+        Field(examples=["succeeded"]),
+    ]
+    """
+    Payment intent status
+    """
+
+
+class SdkPaymentIntentListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    payment_intents: Annotated[list[SdkPaymentIntentListItem], Field(alias="paymentIntents")]
+    total: Annotated[int | float, Field(examples=[1])]
+    """
+    Number of payment intents returned
+    """
+
+
+class SdkPaymentIntentResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    account_id: Annotated[str | None, Field(alias="accountId", examples=["acct_1A2B3C4D"])] = None
+    """
+    Connected Stripe account ID (only present on create)
+    """
+    amount: Annotated[int | float, Field(examples=[4999])]
+    """
+    Amount in USD minor units (ledger/normalised). The charge-currency amount is `originalAmount` paired with `currency`.
+    """
+    client_secret: Annotated[
+        str, Field(alias="clientSecret", examples=["pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456"])
+    ]
+    """
+    Client secret used to confirm the payment on the client
+    """
+    created_at: Annotated[
+        str | None, Field(alias="createdAt", examples=["2025-10-18T10:30:00.000Z"])
+    ] = None
+    """
+    Creation timestamp
+    """
+    currency: Annotated[str, Field(examples=["usd"])]
+    """
+    ISO 4217 presentment (charge) currency code — pairs with `originalAmount`
+    """
+    customer_ref: Annotated[
+        str | None, Field(alias="customerRef", examples=["cus_3c4d5e6f7g8h"])
+    ] = None
+    """
+    Customer reference
+    """
+    exchange_rate: Annotated[int | float | None, Field(alias="exchangeRate", examples=[1])] = None
+    """
+    Exchange rate applied to convert to USD
+    """
+    expires_at: Annotated[
+        str | None, Field(alias="expiresAt", examples=["2025-10-19T10:30:00.000Z"])
+    ] = None
+    """
+    Expiry timestamp of the payment intent
+    """
+    original_amount: Annotated[int | float | None, Field(alias="originalAmount", examples=[4999])] = None
+    """
+    Charge-currency amount in minor units (the currency the customer is billed in)
+    """
+    plan_ref: Annotated[str | None, Field(alias="planRef", examples=["pln_2b3c4d5e6f7g"])] = None
+    """
+    Plan reference
+    """
+    processor_payment_id: Annotated[
+        str, Field(alias="processorPaymentId", examples=["pi_1a2b3c4d5e6f7g8h"])
+    ]
+    """
+    Payment processor payment intent ID
+    """
+    publishable_key: Annotated[str, Field(alias="publishableKey", examples=["pk_test_..."])]
+    """
+    Stripe publishable key for the environment
+    """
+    status: Annotated[
+        Literal[
+            "pending",
+            "requires_payment_method",
+            "requires_confirmation",
+            "requires_action",
+            "processing",
+            "succeeded",
+            "failed",
+            "cancelled",
+        ],
+        Field(examples=["requires_payment_method"]),
+    ]
+    """
+    Payment intent status
+    """
+    transaction_id: Annotated[
+        str | None, Field(alias="transactionId", examples=["507f1f77bcf86cd799439011"])
+    ] = None
+    """
+    Ledger transaction ID
+    """
+
+
+class SdkPlanResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    created_at: Annotated[str, Field(alias="createdAt")]
+    """
+    Creation timestamp
+    """
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    Currency code (ISO 4217)
+    """
+    currency_symbol: Annotated[str | None, Field(alias="currencySymbol", examples=["$"])] = None
+    """
+    Currency symbol
+    """
+    description: Annotated[str | None, Field(examples=["Best for teams getting started"])] = None
+    """
+    Plan description
+    """
+    features: dict[str, Any] | None = None
+    """
+    Plan features
+    """
+    is_active: Annotated[bool, Field(alias="isActive", examples=[True])]
+    """
+    Whether the plan is active
+    """
+    name: Annotated[str | None, Field(examples=["Starter"])] = None
+    """
+    Plan name
+    """
+    options: list[dict[str, Any]]
+    """
+    Composable pricing options (money as integer minor units)
+    """
+    price: Annotated[int | float | None, Field(examples=[2999])] = None
+    """
+    Derived headline price in minor units (base or one-time charge)
+    """
+    reference: Annotated[str, Field(examples=["pln_1A2B3C4D"])]
+    """
+    Plan reference
+    """
+    requires_payment: Annotated[bool, Field(alias="requiresPayment", examples=[True])]
+    """
+    Whether payment is required
+    """
+    status: Annotated[str, Field(examples=["active"])]
+    """
+    Plan status
+    """
+    type: Annotated[
+        Literal["recurring", "one-time", "usage-based", "hybrid"], Field(examples=["recurring"])
+    ]
+    """
+    Derived plan type (read from options)
+    """
+    updated_at: Annotated[str, Field(alias="updatedAt")]
+    """
+    Last update timestamp
+    """
+
+
+class SdkPlanSnapshotDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    Currency code
+    """
+    features: dict[str, Any] | None = None
+    """
+    Plan features
+    """
+    is_metered: Annotated[bool | None, Field(alias="isMetered", examples=[True])] = None
+    """
+    Whether the frozen plan counts usage (prices per unit, or has a limit). Shipped clients read this to show an allowance.
+    """
+    name: Annotated[str | None, Field(examples=["Pro Monthly"])] = None
+    """
+    Plan name captured at purchase time
+    """
+    options: list[dict[str, Any]] | None = None
+    """
+    Frozen composable pricing options captured at purchase time
+    """
+    price: Annotated[int | float, Field(examples=[2999])]
+    """
+    Headline plan price in minor units (e.g. cents)
+    """
+    reference: Annotated[str | None, Field(examples=["pln_1A2B3C4D"])] = None
+    """
+    Plan reference
+    """
+
+
+class SdkPlatformConfigResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    stripe_publishable_key: Annotated[
+        str | None, Field(alias="stripePublishableKey", examples=["pk_test_..."])
+    ] = None
+    """
+    SolvaPay's platform Stripe publishable key for the authenticated provider's environment. Safe to expose browser-side; paired with the connected `accountId` returned from `create-payment-intent` for Stripe Connect direct charges. Omitted when not configured so callers can fall back cleanly to a hosted flow.
+    """
+
+
+class SdkProductResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    balance: Annotated[int | float, Field(examples=[0])]
+    """
+    Product balance in cents
+    """
+    config: ProductConfigDto | None = None
+    """
+    Product-specific configuration
+    """
+    created_at: Annotated[str, Field(alias="createdAt")]
+    """
+    Creation timestamp
+    """
+    description: str | None = None
+    """
+    Product description
+    """
+    image_url: Annotated[str | None, Field(alias="imageUrl")] = None
+    """
+    URL to the product image
+    """
+    is_managed_mcp: Annotated[bool, Field(alias="isManagedMcp", examples=[False])]
+    """
+    Whether this product uses the Managed MCP integration (SolvaPay reverse proxy)
+    """
+    is_mcp_pay: Annotated[bool, Field(alias="isMcpPay", deprecated=True, examples=[False])]
+    """
+    Deprecated alias of isManagedMcp. Prefer isManagedMcp; still emitted for wire compatibility.
+    """
+    mcp: Annotated[
+        dict[str, Any] | None,
+        Field(
+            examples=[
+                {
+                    "defaultPlanRef": "pln_FREE123",
+                    "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp",
+                    "mcpServerRef": "mcp_ABC123",
+                    "mcpSubdomain": "acme-docs",
+                    "originUrl": "https://origin.example.com/mcp",
+                }
+            ]
+        ),
+    ] = None
+    """
+    MCP linkage details for MCP-enabled products
+    """
+    metadata: dict[str, Any] | None = None
+    """
+    Arbitrary key-value metadata
+    """
+    name: Annotated[str, Field(examples=["AI Writing Assistant"])]
+    """
+    Product name
+    """
+    plans: list[SdkPlanResponse] | None = None
+    """
+    Plans associated with this product
+    """
+    product_type: Annotated[str | None, Field(alias="productType")] = None
+    """
+    Free-form product type
+    """
+    reference: Annotated[str, Field(examples=["prd_1A2B3C4D"])]
+    """
+    Product reference
+    """
+    status: Annotated[str, Field(examples=["active"])]
+    """
+    Product status
+    """
+    total_transactions: Annotated[int | float, Field(alias="totalTransactions", examples=[0])]
+    """
+    Total number of transactions
+    """
+    updated_at: Annotated[str, Field(alias="updatedAt")]
+    """
+    Last update timestamp
+    """
+
+
+class SdkUsagePeriodDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    period_end: Annotated[
+        str | None, Field(alias="periodEnd", examples=["2025-11-01T00:00:00Z"])
+    ] = None
+    """
+    Billing period of the active usage window; counts come from `/v1/sdk/limits`
+    """
+    period_start: Annotated[
+        str | None, Field(alias="periodStart", examples=["2025-10-01T00:00:00Z"])
+    ] = None
+    """
+    Billing period of the active usage window; counts come from `/v1/sdk/limits`
+    """
+
+
+class TaxBreakdownDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: str
+    """
+    ISO 4217 currency code
+    """
+    inclusive: bool
+    """
+    Whether tax is included in the listed price
+    """
+    not_registered: Annotated[bool | None, Field(alias="notRegistered")] = None
+    """
+    True when Stripe reports taxability_reason not_collecting (no registration)
+    """
+    subtotal: int | float
+    """
+    Pre-tax amount in minor units
+    """
+    tax_amount: Annotated[int | float, Field(alias="taxAmount")]
+    """
+    Tax amount in minor units
+    """
+    tax_rate: Annotated[int | float, Field(alias="taxRate")]
+    """
+    Tax rate as a decimal (e.g. 0.25 for 25%)
+    """
+    tax_type: Annotated[
+        Literal[
+            "amusement_tax",
+            "communications_tax",
+            "gst",
+            "hst",
+            "igst",
+            "jct",
+            "lease_tax",
+            "pst",
+            "qst",
+            "retail_delivery_fee",
+            "rst",
+            "sales_tax",
+            "service_tax",
+            "vat",
+        ]
+        | None,
+        Field(alias="taxType"),
+    ] = None
+    """
+    Stripe tax type (e.g. vat, sales_tax, gst)
+    """
+    total: int | float
+    """
+    Total amount in minor units
+    """
+    treatment: Literal["reverse_charge", "standard", "none", "not_collecting", "not_supported"]
+
+
+class UpdateCustomerRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    description: Annotated[str | None, Field(max_length=1000)] = None
+    email: str | None = None
+    external_ref: Annotated[str | None, Field(alias="externalRef", max_length=50)] = None
+    metadata: Any | None = None
+    name: Annotated[
+        str | None, Field(max_length=100, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$")
+    ] = None
+    telephone: Telephone | Literal[""] | None = None
+
+
+class Options27(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount_minor: Annotated[int, Field(alias="amountMinor", ge=0)]
+    currency: str
+    kind: Literal["charge"]
+    label: str | None = None
+    meter: Annotated[str | None, Field(min_length=1)] = None
+    one_time: Annotated[bool | None, Field(alias="oneTime")] = None
+    per: Literal["unit", "seat", "flat"]
+
+
+class Options28(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    anchor: str | None = None
+    count: Annotated[int | None, Field(ge=1)] = None
+    interval: Literal["week", "month", "year"]
+    kind: Literal["billingCycle"]
+
+
+class Options29(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    charge: Charge
+    from_: Annotated[int, Field(alias="from", ge=0)]
+    kind: Literal["tier"]
+    label: str | None = None
+    mode: Literal["graduated", "volume"]
+    to: Annotated[int | None, Field(ge=0)]
+
+
+class Options30(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    cap: Annotated[int, Field(ge=0)]
+    kind: Literal["limit"]
+    label: str | None = None
+    meter: Annotated[str, Field(min_length=1)]
+    on_exceed: Annotated[Literal["block", "draw_credits"], Field(alias="onExceed")]
+    scope: Literal["billing_period", "lifetime", "rolling_window"]
+    window_days: Annotated[int | None, Field(alias="windowDays", ge=1)] = None
+
+
+class Options31(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    feature: Annotated[str, Field(min_length=1)]
+    kind: Literal["entitlement"]
+    label: str | None = None
+    scope: str | None = None
+    value: bool | int | float | str
+
+
+class Options32(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    days: Annotated[int, Field(ge=1)]
+    kind: Literal["trial"]
+    label: str | None = None
+    on_end: Annotated[Literal["convert", "cancel"], Field(alias="onEnd")]
+
+
+class Options33(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    applies_to: Annotated[
+        Literal["recurring", "setup", "usage", "all"] | None, Field(alias="appliesTo")
+    ] = None
+    currency: str | None = None
+    cycles: Annotated[int | None, Field(ge=1)] = None
+    duration: Literal["once", "repeating", "forever"]
+    kind: Literal["discount"]
+    label: str | None = None
+    mode: Literal["percentage", "fixed"]
+    value: Annotated[int, Field(gt=0)]
+
+
+class Options34(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["autoAssigned"]
+    label: str | None = None
+
+
+class Options35(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["hidden"]
+    label: str | None = None
+
+
+class UpdatePlanRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    access_expiry_days: Annotated[int | None, Field(alias="accessExpiryDays", ge=0)] = None
+    currency: Annotated[str | None, Field(max_length=3, min_length=3)] = None
+    description: Annotated[str | None, Field(max_length=500)] = None
+    features: dict[str, Any] | None = None
+    max_active_users: Annotated[int | None, Field(alias="maxActiveUsers", ge=0)] = None
+    metadata: dict[str, Any] | None = None
+    name: Annotated[
+        str | None,
+        Field(max_length=200, min_length=2, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$"),
+    ] = None
+    options: (
+        list[
+            Options27
+            | Options28
+            | Options29
+            | Options30
+            | Options31
+            | Options32
+            | Options33
+            | Options34
+            | Options35
+        ]
+        | None
+    ) = None
+    status: Literal["active", "inactive", "archived"] | None = None
+    tax_behavior: Annotated[
+        Literal["auto", "inclusive", "exclusive"] | None, Field(alias="taxBehavior")
+    ] = None
+
+
+class UpdateProductRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    config: Config | None = None
+    description: Annotated[str | None, Field(max_length=1000)] = None
+    image_url: Annotated[str | None, Field(alias="imageUrl")] = None
+    metadata: dict[str, Any] | None = None
+    name: Annotated[
+        str | None,
+        Field(max_length=100, min_length=2, pattern="^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$"),
+    ] = None
+    product_type: Annotated[str | None, Field(alias="productType", max_length=100)] = None
+    tax_behavior: Annotated[
+        Literal["auto", "inclusive", "exclusive"] | None, Field(alias="taxBehavior")
+    ] = None
+
+
+class UsageRecordResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    credit_debit: Annotated[
+        CreditDebitSuccessResponse
+        | CreditDebitSkippedResponse
+        | CostDebitSuccessResponse
+        | CostDebitSkippedResponse
+        | None,
+        Field(alias="creditDebit"),
+    ] = None
+    reference: Annotated[str, Field(examples=["usage_A1B2C3D4"])]
+    success: Annotated[bool, Field(examples=[True])]
+
+
+class Call(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    call_ref: Annotated[str, Field(alias="callRef", max_length=20, pattern="^call_[A-Z0-9]+$")]
+    cost: Annotated[str, Field(pattern="^\\d+(\\.\\d{1,8})?$")]
+
+
+class UntaggedItem(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    at: str
+    cost: Annotated[str, Field(pattern="^\\d+(\\.\\d{1,8})?$")]
+
+
+class Window(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    from_: Annotated[str | None, Field(alias="from")] = None
+    to: str | None = None
+
+
+class UsageReportDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    calls: Annotated[list[Call], Field(max_length=10000)]
+    currency: Annotated[str, Field(pattern="^[A-Z]{3}$")]
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20)]
+    report_id: Annotated[
+        str, Field(alias="reportId", max_length=128, min_length=1, pattern="^[A-Za-z0-9_:.-]+$")
+    ]
+    source: Annotated[str, Field(max_length=200, min_length=1)]
+    untagged: Annotated[list[UntaggedItem], Field(max_length=2000)]
+    window: Window
+
+
+class Result(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    booked_credit: Annotated[str | None, Field(alias="bookedCredit")] = None
+    booked_policy: Annotated[str | None, Field(alias="bookedPolicy")] = None
+    call_ref: Annotated[str, Field(alias="callRef")]
+    credit_delta: Annotated[str | None, Field(alias="creditDelta")] = None
+    policy_delta: Annotated[str | None, Field(alias="policyDelta")] = None
+    reason: Literal["provisional", "expired", "no_debit", "cost_differs"] | None = None
+    reported: str | None = None
+    result: Literal["matched", "adjusted", "pending", "already_reconciled", "ignored"]
+
+
+class Untagged(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    before_policy: Annotated[str | None, Field(alias="beforePolicy")] = None
+    flagged: bool | None = None
+    total: str | None = None
+
+
+class UsageReportResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: Literal["USD"]
+    duplicate: bool
+    reference: str
+    results: list[Result]
+    untagged: Untagged
+
+
+class UserInfoPlanDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    billing_cycle: Annotated[str | None, Field(alias="billingCycle", examples=["monthly"])] = None
+    currency: Annotated[str, Field(examples=["USD"])]
+    features: dict[str, Any] | None = None
+    limits: Annotated[dict[str, Any] | None, Field(deprecated=True)] = None
+    """
+    Deprecated: always null. Limit data now lives in the plan snapshot options (`kind: "limit"`).
+    """
+    price: Annotated[int | float | None, Field(examples=[2999])] = None
+    """
+    Price in minor currency units (e.g. cents)
+    """
+    reference: Annotated[str | None, Field(examples=["pln_2B3C4D5E"])] = None
+    type: Annotated[str, Field(examples=["recurring"])]
+
+
+class UserInfoRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    customer_ref: Annotated[str, Field(alias="customerRef", max_length=20, min_length=1)]
+    product_ref: Annotated[str, Field(alias="productRef", max_length=20, min_length=1)]
+
+
+class UserInfoUsageDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    meter_ref: Annotated[str | None, Field(alias="meterRef", examples=["requests"])] = None
+    """
+    Meter key referenced by the plan options
+    """
+    percent_used: Annotated[int | float | None, Field(alias="percentUsed", examples=[25])] = None
+    remaining: Annotated[int | float, Field(examples=[750])]
+    total: Annotated[int | float, Field(examples=[1000])]
+    """
+    Included allowance for the period. `0` means unlimited / no finite cap.
+    """
+    used: Annotated[int | float, Field(examples=[250])]
+
+
+class UserInfoUserDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    email: Annotated[str, Field(examples=["john@example.com"])]
+    external_ref: Annotated[
+        str | None, Field(alias="externalRef", examples=["auth_user_12345"])
+    ] = None
+    name: Annotated[str | None, Field(examples=["John Doe"])] = None
+    reference: Annotated[str, Field(examples=["cus_3C4D5E6F"])]
+
+
+class VerifiedAgentKeyResponseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    agent_ref: Annotated[str, Field(alias="agentRef")]
+    environment: Literal["sandbox", "live"]
+    principal_ref: Annotated[str, Field(alias="principalRef")]
+    prompt_excerpt: Annotated[bool, Field(alias="promptExcerpt")]
+
+
+class VerifyAgentKeyDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    agent_key: Annotated[str, Field(alias="agentKey", max_length=200)]
+
+
+class WebhookEventDataDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    object: dict[str, Any]
+    """
+    The resource that the event relates to.
+    """
+    previous_attributes: dict[str, Any] | None = None
+    """
+    For *.updated events, the previous values of changed attributes.
+    """
+
+
+class WebhookEventRequestDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[dict[str, Any] | None, Field(...)]
+    """
+    ID of the API request that triggered the event.
+    """
+    idempotency_key: Annotated[dict[str, Any] | None, Field(...)]
+    """
+    Idempotency key of the triggering request.
+    """
+
+
+class WebhookEventType(
+    RootModel[
+        Literal[
+            "customer.created",
+            "customer.updated",
+            "customer.deleted",
+            "purchase.created",
+            "purchase.activated",
+            "purchase.updated",
+            "purchase.trial_ending",
+            "purchase.trial_converted",
+            "purchase.suspended",
+            "purchase.past_due",
+            "purchase.cancellation_scheduled",
+            "purchase.cancelled",
+            "purchase.reactivated",
+            "purchase.expired",
+            "purchase.renewed",
+            "purchase.renewal_reminder",
+            "purchase.refunded",
+            "purchase.plan_changed",
+            "payment.succeeded",
+            "payment.failed",
+            "payment.refunded",
+            "payment.refund_failed",
+            "payment.refund_pending",
+            "payment.canceled",
+            "payment.disputed",
+            "payment.dispute_closed",
+            "payout.paid",
+            "payout.failed",
+            "checkout_session.created",
+            "checkout_session.completed",
+            "checkout_session.expired",
+            "customer.credit.topped_up",
+            "customer.credit.low_balance",
+            "customer.credit.exhausted",
+            "customer.credit.debited",
+            "customer.credit.granted",
+            "customer.credit.adjusted",
+            "customer.credit.auto_topup_failed",
+            "usage.charged",
+            "usage.recorded",
+            "usage.reset",
+            "product.created",
+            "product.updated",
+            "product.archived",
+            "plan.created",
+            "plan.updated",
+            "plan.archived",
+        ]
+    ]
+):
+    root: Literal[
+        "customer.created",
+        "customer.updated",
+        "customer.deleted",
+        "purchase.created",
+        "purchase.activated",
+        "purchase.updated",
+        "purchase.trial_ending",
+        "purchase.trial_converted",
+        "purchase.suspended",
+        "purchase.past_due",
+        "purchase.cancellation_scheduled",
+        "purchase.cancelled",
+        "purchase.reactivated",
+        "purchase.expired",
+        "purchase.renewed",
+        "purchase.renewal_reminder",
+        "purchase.refunded",
+        "purchase.plan_changed",
+        "payment.succeeded",
+        "payment.failed",
+        "payment.refunded",
+        "payment.refund_failed",
+        "payment.refund_pending",
+        "payment.canceled",
+        "payment.disputed",
+        "payment.dispute_closed",
+        "payout.paid",
+        "payout.failed",
+        "checkout_session.created",
+        "checkout_session.completed",
+        "checkout_session.expired",
+        "customer.credit.topped_up",
+        "customer.credit.low_balance",
+        "customer.credit.exhausted",
+        "customer.credit.debited",
+        "customer.credit.granted",
+        "customer.credit.adjusted",
+        "customer.credit.auto_topup_failed",
+        "usage.charged",
+        "usage.recorded",
+        "usage.reset",
+        "product.created",
+        "product.updated",
+        "product.archived",
+        "plan.created",
+        "plan.updated",
+        "plan.archived",
+    ]
+    """
+    Event type.
+    """
+
+
+class RecordMeterEventResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    success: Annotated[bool | None, Field(examples=[True])] = None
+
+
+class RecordMeterEventsBulkResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    inserted: Annotated[int | float | None, Field(examples=[50])] = None
+    success: Annotated[bool | None, Field(examples=[True])] = None
+
+
+class GetPaymentMethodResponse1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    brand: Annotated[str, Field(examples=["visa"])]
+    exp_month: Annotated[int, Field(alias="expMonth", examples=[12], ge=1, le=12)]
+    exp_year: Annotated[int, Field(alias="expYear", examples=[2030])]
+    kind: Literal["card"]
+    last4: Annotated[str, Field(examples=["4242"])]
+    reusable: Annotated[bool, Field(examples=[True])]
+
+
+class GetPaymentMethodResponse2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    kind: Literal["none"]
+
+
+class GetPaymentMethodResponse(RootModel[GetPaymentMethodResponse1 | GetPaymentMethodResponse2]):
+    root: Annotated[
+        GetPaymentMethodResponse1 | GetPaymentMethodResponse2, Field(discriminator="kind")
+    ]
+
+
+class ListProductsResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: int | float | None = None
+    """
+    Applied page size (clamped to 1-100)
+    """
+    offset: int | float | None = None
+    """
+    Applied pagination offset
+    """
+    products: list[SdkProductResponse] | None = None
+    total: int | float | None = None
+    """
+    Total number of products matching the filters
+    """
+
+
+class DeleteProductResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    action: Literal["deactivated", "soft_deleted"] | None = None
+    """
+    Outcome of the delete: deactivation when purchases exist, otherwise soft-delete. Same in sandbox and live.
+    """
+    success: bool | None = None
+
+
+class ListPlansResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: int | float | None = None
+    offset: int | float | None = None
+    plans: list[Plan2] | None = None
+    total: int | float | None = None
+    """
+    Total number of plans for the product
+    """
+
+
+class DeletePlanResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    success: bool | None = None
+
+
+class AttachBusinessDetailsResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    tax_breakdown: Annotated[TaxBreakdownDto, Field(alias="taxBreakdown")]
+    """
+    Calculated tax breakdown
+    """
+
+
+class AutoRechargeConfigDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    enabled: Annotated[bool, Field(examples=[True])]
+    """
+    Whether auto-recharge is enabled
+    """
+    failure_count: Annotated[int | float, Field(alias="failureCount", examples=[0])]
+    """
+    Consecutive failure count
+    """
+    funding_source_type: Annotated[
+        Literal["saved_card", "tokenized_card"], Field(alias="fundingSourceType")
+    ]
+    """
+    Funding source type
+    """
+    in_flight_payment_intent_id: Annotated[str | None, Field(alias="inFlightPaymentIntentId")] = (
+        None
+    )
+    """
+    PaymentIntent ID of an in-flight recharge
+    """
+    last_charge_at: Annotated[str | None, Field(alias="lastChargeAt")] = None
+    """
+    Timestamp of the last successful charge
+    """
+    lock_acquired_at: Annotated[str | None, Field(alias="lockAcquiredAt")] = None
+    """
+    Timestamp the processing lock was acquired
+    """
+    max_monthly_spend_minor: Annotated[
+        int | float | None, Field(alias="maxMonthlySpendMinor", examples=[10000])
+    ] = None
+    """
+    Optional monthly spend cap in topup.currency minor units
+    """
+    monthly_spend_minor: Annotated[int | float, Field(alias="monthlySpendMinor", examples=[4500])]
+    """
+    Successful auto-recharge spend in the current UTC month
+    """
+    monthly_spend_period: Annotated[
+        str | None, Field(alias="monthlySpendPeriod", examples=["2026-07"])
+    ] = None
+    """
+    UTC YYYY-MM period key for monthlySpendMinor
+    """
+    payment_method_id: Annotated[str | None, Field(alias="paymentMethodId")] = None
+    """
+    Saved payment method ID backing the recharge
+    """
+    status: Literal["active", "disabled", "failed", "pending_setup"]
+    """
+    Current config status
+    """
+    topup: AutoRechargeTopupDto
+    trigger: AutoRechargeTriggerDto
+    updated_at: Annotated[str, Field(alias="updatedAt")]
+    """
+    Last update timestamp
+    """
+
+
+class AutoRechargeDisplayDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    currency: Annotated[str, Field(examples=["USD"])]
+    """
+    Display currency code
+    """
+    exchange_rate: Annotated[int | float, Field(alias="exchangeRate", examples=[1])]
+    """
+    Exchange rate used for display conversion
+    """
+    formatted: AutoRechargeDisplayFormattedDto
+    rate_source: Annotated[
+        Literal["parity", "db", "fallback"], Field(alias="rateSource", examples=["db"])
+    ]
+    """
+    Source of the exchange rate
+    """
+    threshold_amount_major: Annotated[int | float, Field(alias="thresholdAmountMajor", examples=[5])]
+    """
+    Threshold amount in display-currency major units
+    """
+    topup_amount_major: Annotated[int | float, Field(alias="topupAmountMajor", examples=[20])]
+    """
+    Top-up amount in display-currency major units
+    """
+
+
+class AutoRechargeGetResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    config: AutoRechargeConfigDto | None = None
+    """
+    Current auto-recharge config, or null when not configured
+    """
+    display: AutoRechargeDisplayDto | None = None
+    validation: AutoRechargeValidationMetaResponse
+    """
+    Validation metadata for the auto-recharge form (always present)
+    """
+
+
+class BulkUsageResultResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    credit_debit: Annotated[
+        CreditDebitSuccessResponse
+        | CreditDebitSkippedResponse
+        | CostDebitSuccessResponse
+        | CostDebitSkippedResponse
+        | None,
+        Field(alias="creditDebit"),
+    ] = None
+    reference: Annotated[str, Field(examples=["usage_A1B2C3D4"])]
+
+
+class ConfigureMcpPlansResult(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    mcp_server: Annotated[dict[str, Any], Field(alias="mcpServer")]
+    """
+    Updated MCP server identity
+    """
+    plan_map: Annotated[dict[str, Any], Field(alias="planMap")]
+    """
+    Resolved plan mapping by key (includes existing free plan)
+    """
+    product: SdkProductResponse
+    """
+    Updated product
+    """
+
+
+class McpBootstrapResult(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    auto_mapped_tools: Annotated[list[AutoMappedTool] | None, Field(alias="autoMappedTools")] = None
+    """
+    Auto-discovered tools used during bootstrap
+    """
+    mcp_server: Annotated[
+        dict[str, Any],
+        Field(
+            alias="mcpServer",
+            examples=[
+                {
+                    "defaultPlanRef": "pln_FREE123",
+                    "id": "507f1f77bcf86cd799439011",
+                    "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp",
+                    "reference": "mcp_ABC123",
+                    "subdomain": "acme-docs",
+                    "url": "https://origin.example.com/mcp",
+                }
+            ],
+        ),
+    ]
+    """
+    Created or updated MCP server identity
+    """
+    plan_map: Annotated[
+        dict[str, Any],
+        Field(alias="planMap", examples=[{"free": {"name": "Free", "reference": "pln_FREE123"}}]),
+    ]
+    """
+    Resolved plan mapping by bootstrap key
+    """
+    product: SdkProductResponse
+    """
+    Created product
+    """
+    tools_auto_mapped: Annotated[bool | None, Field(alias="toolsAutoMapped", examples=[True])] = (
+        None
+    )
+    """
+    True when tools were auto-discovered from origin because the request omitted tools
+    """
+
+
+class SaveAutoRechargeResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    config: AutoRechargeConfigDto
+    display: AutoRechargeDisplayDto | None = None
+    publishable_key: Annotated[str | None, Field(alias="publishableKey")] = None
+    """
+    Stripe publishable key for the resolved environment
+    """
+    setup_client_secret: Annotated[str | None, Field(alias="setupClientSecret")] = None
+    """
+    Stripe SetupIntent client secret for card collection
+    """
+    stripe_account_id: Annotated[str | None, Field(alias="stripeAccountId")] = None
+    """
+    Connected Stripe account ID
+    """
+
+
+class SdkPurchaseResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    amount: Annotated[int | float, Field(examples=[9900])]
+    """
+    Amount in USD cents (normalised for aggregation)
+    """
+    auto_renew: Annotated[bool | None, Field(alias="autoRenew")] = None
+    """
+    Auto-renew enabled
+    """
+    billing_cycle: Annotated[
+        Literal["weekly", "monthly", "quarterly", "yearly"] | None, Field(alias="billingCycle")
+    ] = None
+    """
+    Billing cycle
+    """
+    cancellation_reason: Annotated[
+        str | None, Field(alias="cancellationReason", examples=["Customer request"])
+    ] = None
+    """
+    Reason for cancellation
+    """
+    cancelled_at: Annotated[
+        str | None, Field(alias="cancelledAt", examples=["2025-10-28T10:00:00Z"])
+    ] = None
+    """
+    When purchase was cancelled
+    """
+    created_at: Annotated[str, Field(alias="createdAt")]
+    """
+    Created at
+    """
+    currency: Annotated[str, Field(examples=["GBP"])]
+    """
+    ISO 4217 currency code of the customer-facing charge
+    """
+    customer_email: Annotated[
+        str | None, Field(alias="customerEmail", examples=["customer@example.com"])
+    ] = None
+    """
+    Customer email
+    """
+    customer_ref: Annotated[str, Field(alias="customerRef", examples=["cus_3C4D5E6F"])]
+    """
+    Customer reference
+    """
+    end_date: Annotated[str | None, Field(alias="endDate", examples=["2025-11-27T10:00:00Z"])] = (
+        None
+    )
+    """
+    End date of purchase
+    """
+    exchange_rate: Annotated[int | float | None, Field(alias="exchangeRate", examples=[1.32])] = None
+    """
+    Exchange rate from original currency to USD
+    """
+    is_recurring: Annotated[bool, Field(alias="isRecurring", examples=[True])]
+    """
+    Whether the purchase is recurring
+    """
+    metadata: dict[str, Any] | None = None
+    """
+    Arbitrary metadata attached to the purchase
+    """
+    next_billing_date: Annotated[str | None, Field(alias="nextBillingDate")] = None
+    """
+    Next billing date
+    """
+    origin: Annotated[
+        Literal["paid", "free_default", "manual", "one_time", "credit_topup", "admin_assignment"]
+        | None,
+        Field(examples=["paid"]),
+    ] = None
+    """
+    How the purchase originated
+    """
+    original_amount: Annotated[int | float | None, Field(alias="originalAmount", examples=[7500])] = None
+    """
+    Original amount in the payment currency (minor units)
+    """
+    paid_at: Annotated[str | None, Field(alias="paidAt")] = None
+    """
+    Paid at timestamp
+    """
+    plan_ref: Annotated[str | None, Field(alias="planRef", examples=["pln_abc123"])] = None
+    """
+    Plan reference from the plan snapshot, for reliable plan matching
+    """
+    plan_snapshot: Annotated[SdkPlanSnapshotDto | None, Field(alias="planSnapshot")] = None
+    """
+    Snapshot of the plan at time of purchase
+    """
+    product_name: Annotated[
+        str | None, Field(alias="productName", examples=["API Gateway Manager"])
+    ] = None
+    """
+    Product name
+    """
+    product_ref: Annotated[str | None, Field(alias="productRef", examples=["prd_abc123"])] = None
+    """
+    Product reference
+    """
+    reference: Annotated[str, Field(examples=["pur_1A2B3C4D"])]
+    """
+    Purchase reference
+    """
+    requires_payment: Annotated[bool | None, Field(alias="requiresPayment", examples=[False])] = (
+        None
+    )
+    """
+    Whether the purchase requires payment
+    """
+    start_date: Annotated[str, Field(alias="startDate", examples=["2025-10-27T10:00:00Z"])]
+    """
+    Start date
+    """
+    status: Annotated[str, Field(examples=["active"])]
+    """
+    Purchase status
+    """
+    usage: SdkUsagePeriodDto | None = None
+    """
+    Billing period of the active usage window; counts come from `/v1/sdk/limits`
+    """
+
+
+class UserInfoPurchaseDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    end_date: Annotated[str | None, Field(alias="endDate", examples=["2025-11-27T10:00:00Z"])] = (
+        None
+    )
+    plan: UserInfoPlanDto | None = None
+    plan_type: Annotated[str | None, Field(alias="planType", examples=["recurring"])] = None
+    product_name: Annotated[str, Field(alias="productName", examples=["My API Product"])]
+    reference: Annotated[str, Field(examples=["pur_1A2B3C4D"])]
+    start_date: Annotated[
+        str | None, Field(alias="startDate", examples=["2025-10-27T10:00:00Z"])
+    ] = None
+    status: Annotated[str, Field(examples=["active"])]
+    usage: UserInfoUsageDto | None = None
+
+
+class UserInfoResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchase: UserInfoPurchaseDto | None = None
+    status: Annotated[
+        str, Field(examples=["Active subscription: My API Product (25% usage consumed)"])
+    ]
+    """
+    Human-readable status summary
+    """
+    user: UserInfoUserDto | None = None
+    verify_url: Annotated[
+        str | None,
+        Field(alias="verifyUrl", examples=["https://solvapay.com/customer/manage?id=abc123"]),
+    ] = None
+    """
+    Customer portal session URL
+    """
+
+
+class WebhookEventDefinitionDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    description: str
+    """
+    Human-readable description of the event.
+    """
+    status: Annotated[Literal["live", "planned"], Field(examples=["live"])]
+    """
+    Emission status.
+    """
+    type: Annotated[WebhookEventType, Field(examples=["purchase.created"])]
+
+
+class WebhookEventDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    api_version: Annotated[str, Field(examples=["2025-10-01"])]
+    """
+    API version that produced the event payload.
+    """
+    created: Annotated[int | float, Field(examples=[1717000000])]
+    """
+    Unix timestamp (seconds) when the event was created.
+    """
+    data: WebhookEventDataDto
+    """
+    Event payload envelope.
+    """
+    id: Annotated[str, Field(examples=["evt_1A2B3C4D"])]
+    """
+    Unique event ID.
+    """
+    livemode: Annotated[bool, Field(examples=[True])]
+    """
+    True for live-mode events, false for sandbox.
+    """
+    request: WebhookEventRequestDto
+    """
+    Context about the triggering API request.
+    """
+    type: Annotated[WebhookEventType, Field(examples=["purchase.created"])]
+
+
+class ListPurchasesResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchases: list[SdkPurchaseResponse] | None = None
+
+
+class GetPurchasesForCustomerResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchases: list[SdkPurchaseResponse] | None = None
+
+
+class GetPurchasesForProductResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchases: list[SdkPurchaseResponse] | None = None
+
+
+class CancelPurchaseResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchase: SdkPurchaseResponse | None = None
+    success: bool | None = None
+
+
+class ReactivatePurchaseResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchase: SdkPurchaseResponse | None = None
+    success: bool | None = None
+
+
+class BulkUsageResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    inserted: Annotated[int | float, Field(examples=[2])]
+    """
+    Number of usage events inserted
+    """
+    results: list[BulkUsageResultResponse]
+    success: Annotated[bool, Field(examples=[True])]
+
+
+class CustomerResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    email: Annotated[str, Field(examples=["customer@example.com"])]
+    """
+    Customer email address
+    """
+    external_ref: Annotated[
+        str | None, Field(alias="externalRef", examples=["auth_user_12345"])
+    ] = None
+    """
+    External reference ID from your auth system (if set during creation or update)
+    """
+    name: Annotated[str, Field(examples=["John Doe"])]
+    """
+    Customer full name
+    """
+    purchases: list[SdkPurchaseResponse] | None = None
+    """
+    Active purchases
+    """
+    reference: Annotated[str, Field(examples=["cus_3c4d5e6f7g8h"])]
+    """
+    Customer reference identifier
+    """
+
+
+class GetCustomerSessionResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    created_at: Annotated[str, Field(alias="createdAt", examples=["2025-01-01T11:45:00.000Z"])]
+    """
+    Session creation date
+    """
+    customer: CustomerResponse
+    """
+    Customer object from session data
+    """
+    customer_url: Annotated[
+        str,
+        Field(
+            alias="customerUrl",
+            examples=["https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788"],
+        ),
+    ]
+    """
+    Full customer URL based on backend configuration (ready to redirect customer)
+    """
+    expires_at: Annotated[str, Field(alias="expiresAt", examples=["2025-01-01T12:00:00.000Z"])]
+    """
+    Session expiration date
+    """
+    session_id: Annotated[
+        str, Field(alias="sessionId", examples=["e3f1c2d4b6a89f001122334455667788"])
+    ]
+    """
+    Customer session ID/token
+    """
+    status: Annotated[Literal["active", "expired", "used"], Field(examples=["active"])]
+    """
+    Session status
+    """
+    updated_at: Annotated[str, Field(alias="updatedAt", examples=["2025-01-01T11:45:00.000Z"])]
+    """
+    Session last update date
+    """
+
+
+class ProcessPaymentSucceededRecurring(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    purchase: SdkPurchaseResponse
+    status: Annotated[Literal["succeeded"], Field(examples=["succeeded"])]
+    type: Annotated[Literal["recurring"], Field(examples=["recurring"])]
+
+
+class WebhookEventCategoryDto(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    category: Annotated[str, Field(examples=["purchase"])]
+    """
+    Category key.
+    """
+    description: str
+    """
+    Category description.
+    """
+    events: list[WebhookEventDefinitionDto]
+    """
+    Events in this category.
+    """
+    label: Annotated[str, Field(examples=["Purchases & subscriptions"])]
+    """
+    Human-readable category label.
+    """
+
+
+class ProcessPaymentIntentResponse(
+    RootModel[
+        ProcessPaymentSucceededRecurring
+        | ProcessPaymentSucceededOneTime
+        | ProcessPaymentSucceededBare
+        | ProcessPaymentProcessing
+        | ProcessPaymentTimeout
+        | ProcessPaymentFailed
+        | ProcessPaymentCancelled
+    ]
+):
+    root: (
+        ProcessPaymentSucceededRecurring
+        | ProcessPaymentSucceededOneTime
+        | ProcessPaymentSucceededBare
+        | ProcessPaymentProcessing
+        | ProcessPaymentTimeout
+        | ProcessPaymentFailed
+        | ProcessPaymentCancelled
+    )
+
+
+class ListWebhookEventTypesResponse(RootModel[list[WebhookEventCategoryDto]]):
+    root: list[WebhookEventCategoryDto]