@wildo-ai/external-connectors-models 1.1.10 → 1.1.11

package/dist/esm/protocols/billing.standard-interface.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing.standard-interface.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/billing.standard-interface.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Standard Billing Interface\n * --------\n * This is the canonical interface that Wildo uses internally for all billing\n * operations. The ETL layer transforms these standard requests into\n * provider-specific API calls (e.g., Stripe, Paddle, LemonSqueezy).\n *\n * Design Principles:\n * 1. Provider-agnostic — works with any billing provider\n * 2. Hosted-first — uses provider-hosted checkout and portals (no PCI scope)\n * 3. Webhook-driven — state changes flow in via webhooks, not polling\n * 4. Scope-agnostic — billing accounts map to any Wildo scope (org, user)\n *\n * @see billing-and-features-system.md §7.1 (Standard Billing Interface)\n */\n\n// ===============================================================\n// Billing Interface Enums (canonical source, re-exported by saas-models)\n// ===============================================================\n\n/**\n * Pricing model for a price entry.\n */\nexport enum PricingModel {\n  FLAT = 'flat',\n  PER_UNIT = 'per_unit',\n  /** Volume pricing (all units at tier price) */\n  TIERED = 'tiered',\n  /** Incremental (each tier priced independently) */\n  GRADUATED = 'graduated',\n  /** Price per package of N units */\n  PACKAGE = 'package',\n}\n\n/**\n * Billing interval for recurring prices.\n */\nexport enum BillingInterval {\n  MONTH = 'month',\n  YEAR = 'year',\n}\n\n/**\n * Tax display mode: how prices are displayed (HT vs TTC).\n */\nexport enum TaxDisplayMode {\n  /** Price amounts are HT (tax added at checkout) */\n  EXCLUSIVE = 'exclusive',\n  /** Price amounts are TTC (tax embedded) */\n  INCLUSIVE = 'inclusive',\n}\n\n/**\n * How a mid-cycle subscription change is settled.\n *\n * A PROTOCOL vocabulary, and it lives here for the same reason {@link TaxDisplayMode} does: these three\n * values are the wire values a billing provider accepts. It was declared in `@wildo-ai/saas-models`\n * until 2026-09-08 and re-exported the other way round, which is why an authored proration could be\n * resolved by the engine and had no field on the request to travel in — the request contract could not\n * name the type without a package cycle, so the resolved value was sent as provider METADATA and\n * ignored (#516).\n *\n * `@wildo-ai/saas-models` re-exports it, so every existing consumer is unchanged.\n */\nexport enum ProrationBehavior {\n  /** Credit the unused time and charge the new price pro rata, settled on the next invoice. */\n  CREATE_PRORATIONS = 'create_prorations',\n  /** No proration: the change takes effect and the next invoice is the new price in full. */\n  NONE = 'none',\n  /** Prorate and invoice the difference IMMEDIATELY rather than at the next cycle. */\n  ALWAYS_INVOICE = 'always_invoice',\n}\n\n/**\n * How the provider treats a subscription change whose resulting payment does not succeed (#535, decision D6).\n *\n * Wildo applies a confirmed plan change IMMEDIATELY: entitlements move at local completion, and a failed proration\n * payment moves the subscription to `past_due` through the webhook projection, where dunning owns what happens next.\n * The value is DECLARED on every engine-issued change rather than left to the provider's default, so a change of that\n * default can never silently change the semantics.\n *\n * Deliberately a one-member vocabulary. `pending_if_incomplete` (apply only after payment, expire after 23 h) was\n * weighed and rejected in #535; add a member only with a decision that changes D6.\n *\n * spec-cite: https://docs.stripe.com/api/subscriptions/update — `payment_behavior`; the value equals Stripe's wire value,\n * so the Stripe adapter passes it untranslated, as it does `ProrationBehavior`.\n */\nexport enum StandardBilling_SubscriptionPaymentBehavior {\n  /** Apply the change now; an unpaid resulting invoice leaves the subscription `past_due`. */\n  ALLOW_INCOMPLETE = 'allow_incomplete',\n}\n\n/**\n * What a FAILED provider mutation tells the caller about whether the change took effect (#535, decision D3).\n *\n * The distinction that matters is not the HTTP status but what may be recorded next: a conclusive refusal and a request\n * that never executed may both be recorded as \"no effect\", while an indeterminate outcome must NEVER be — the provider\n * may have applied it, or may still apply it. Only the adapter can read its vendor's error shape, so each adapter\n * classifies (`StandardBilling_Interface.classifyMutationError`) and the engine decides on the class alone.\n *\n * spec-cite: https://docs.stripe.com/error-low-level — \"Network errors\", \"Server errors\", \"Content errors\" (the\n * source of the classes for the Stripe adapter; other adapters map their own vendor's equivalents).\n */\nexport enum StandardBilling_MutationErrorClass {\n  /** The provider evaluated the request and refused it (e.g. a declined card, a missing object). No effect. */\n  CONCLUSIVE_REJECTION = 'conclusive_rejection',\n  /** Refused before execution (rate limit, authentication). No effect; a later attempt must use a NEW idempotency key. */\n  NOT_EXECUTED = 'not_executed',\n  /** Another request with the same idempotency key is still being processed. The outcome is not known yet. */\n  IN_FLIGHT_CONFLICT = 'in_flight_conflict',\n  /** Timeout, connection loss, server error, or a failure after the provider answered. The change may have applied. */\n  INDETERMINATE = 'indeterminate',\n}\n\n/**\n * Subscription status values (maps to Stripe subscription statuses).\n */\nexport enum SubscriptionStatus {\n  ACTIVE = 'active',\n  PAST_DUE = 'past_due',\n  UNPAID = 'unpaid',\n  CANCELLED = 'cancelled',\n  /** Stripe: first payment never completed within 23h window */\n  INCOMPLETE = 'incomplete',\n  INCOMPLETE_EXPIRED = 'incomplete_expired',\n  TRIALING = 'trialing',\n  PAUSED = 'paused',\n}\n\n/**\n * Invoice lifecycle status, as the PROVIDER reports it.\n *\n * A PROTOCOL vocabulary for the same reason {@link SubscriptionStatus} is one: these are the states\n * a billing provider puts an invoice in, and the adapter's job is to map its own wire values onto\n * them. It was declared in `@wildo-ai/saas-models` until 2026-09-09 and could not be named by this\n * package at all, so `listInvoices` — the read the reconciliation sweep needs — had no way to type\n * the one field the sweep compares.\n *\n * Moved rather than duplicated: a second enum with the same five members would be two sources for\n * one closed vocabulary, which is what `CLAUDE.md` forbids. `@wildo-ai/saas-models` re-exports it\n * exactly as it already re-exports `SubscriptionStatus`, `TaxDisplayMode` and `ProrationBehavior`,\n * so every existing consumer — including the `invoiceRefs` schema, the badge palette and the\n * documentation catalogue — imports the same specifier it always did.\n */\nexport enum InvoiceStatus {\n  /** Not finalized: the provider has not issued it for collection and it may still change. */\n  DRAFT = 'draft',\n  /** Finalized and awaiting payment. */\n  OPEN = 'open',\n  /** Settled. */\n  PAID = 'paid',\n  /** Cancelled by the provider or the merchant; never collectable. */\n  VOID = 'void',\n  /** Written off — payment was attempted and abandoned. */\n  UNCOLLECTIBLE = 'uncollectible',\n}\n\n// ===============================================================\n// Standard Billing Event Types\n// ===============================================================\n\n/**\n * Canonical billing events the system cares about.\n * Provider-specific events are mapped to these types by the transformer.\n * Only events that affect local state (features, status) need to be handled.\n */\nexport enum StandardBilling_EventType {\n  // Subscription lifecycle (→ feature sync)\n  SUBSCRIPTION_CREATED = 'subscription.created',\n  SUBSCRIPTION_UPDATED = 'subscription.updated',\n  SUBSCRIPTION_DELETED = 'subscription.deleted',\n  SUBSCRIPTION_TRIAL_WILL_END = 'subscription.trial_will_end',\n\n  // Invoice status (→ billing status tracking, past_due detection)\n  INVOICE_PAID = 'invoice.paid',\n  INVOICE_PAYMENT_FAILED = 'invoice.payment_failed',\n  INVOICE_FINALIZED = 'invoice.finalized',\n\n  // Checkout (→ one-off purchase completion for ONE_TIME, CREDIT_PACK, ITEM products)\n  CHECKOUT_SESSION_COMPLETED = 'checkout.session.completed',\n\n  // Customer (→ billing account sync)\n  CUSTOMER_UPDATED = 'customer.updated',\n  CUSTOMER_DELETED = 'customer.deleted',\n\n  // Coupon (→ no local action; coupons are managed through Wildo's promotion system.\n  // Included for logging/audit in case coupons are modified directly on the provider.)\n  COUPON_CREATED = 'coupon.created',\n  COUPON_UPDATED = 'coupon.updated',\n  COUPON_DELETED = 'coupon.deleted',\n\n  // Customer discount (→ subscription re-sync to pick up discount changes)\n  CUSTOMER_DISCOUNT_CREATED = 'customer.discount.created',\n  CUSTOMER_DISCOUNT_UPDATED = 'customer.discount.updated',\n  CUSTOMER_DISCOUNT_DELETED = 'customer.discount.deleted',\n\n  // Payment method (→ no local action needed; provider manages via Customer Portal.\n  // Included for completeness: apps can optionally log these events for audit trails.)\n  PAYMENT_METHOD_ATTACHED = 'payment_method.attached',\n  PAYMENT_METHOD_DETACHED = 'payment_method.detached',\n}\n\n// ===============================================================\n// Standard Billing Webhook Event\n// ===============================================================\n\n/**\n * Canonical webhook event representation.\n * Provider transformers parse raw webhook payloads into this shape.\n */\nexport interface StandardBilling_WebhookEvent {\n  /** Canonical event type */\n  type: StandardBilling_EventType;\n  /** Provider-assigned event ID (for idempotency) */\n  providerEventId: string;\n  /** Event payload — shape varies by event type */\n  data: Record<string, unknown>;\n  /** When the event occurred at the provider */\n  createdAt: Date;\n}\n\n// ===============================================================\n// Request/Response Types\n// ===============================================================\n\n// ── Customer ────────────────────────────────────────────────────\n\nexport interface StandardBilling_CreateCustomerRequest {\n  /**\n   * Descriptive name — the organisation's name for an org-scoped account, the person's display name\n   * for a user-scoped one.\n   *\n   * OPTIONAL, and that is the point (issue #486). It was required, and a caller that could not\n   * resolve one therefore had to INVENT it: the engine sent the literal `'Unknown'` for every\n   * customer it ever created. A contract that cannot express \"we do not know\" forces every caller to\n   * lie, and a fabricated value is worse than an absent one — an operator reading the provider\n   * dashboard cannot tell it from a real answer.\n   */\n  name?: string;\n  /**\n   * Contact email for invoices and receipts.\n   *\n   * OPTIONAL for the same reason as `name`, and additionally because **an organisation frequently has\n   * no billing email at all**. Sending a natural person's address for an ORGANISATION's customer\n   * record would put personal data on a record that is not about a person — the opposite of data\n   * minimisation, which asks that personal data be \"adequate, relevant and limited to what is\n   * necessary\".\n   * spec-cite: GDPR Art. 5(1)(c) — https://gdpr-info.eu/art-5-gdpr/\n   *\n   * It also makes the later erasure story cheap: an organisation record carrying no individual's\n   * identity never has to be visited when that individual exercises their right to erasure, so the\n   * obligation to inform recipients of an erasure does not reach it.\n   * spec-cite: GDPR Art. 17(2) — https://gdpr-info.eu/art-17-gdpr/\n   *\n   * Absent is a legitimate value at the provider: Stripe's own customer `email` is optional.\n   * spec-cite: N/A — describes the Stripe Customer object's declared optionality in this\n   * repository's own words (https://docs.stripe.com/api/customers/object).\n   */\n  email?: string;\n  /** Arbitrary key-value metadata stored on the provider customer */\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCustomerResponse {\n  providerCustomerId: string;\n}\n\n/**\n * Postal address on a provider customer record.\n *\n * Every field is independently clearable (`null`) rather than merely omittable: `undefined` means\n * \"leave whatever the provider already has\", `null` means \"blank it\". Subject erasure needs the\n * second meaning — an address that is silently preserved because the request could only express\n * \"no change\" is personal data surviving an erasure.\n */\nexport interface StandardBilling_CustomerAddress {\n  line1?: string | null;\n  line2?: string | null;\n  city?: string | null;\n  state?: string | null;\n  postalCode?: string | null;\n  /** ISO 3166-1 alpha-2 country code. */\n  country?: string | null;\n}\n\nexport interface StandardBilling_UpdateCustomerRequest {\n  name?: string;\n  email?: string;\n  metadata?: Record<string, string>;\n  /**\n   * Contact phone. `null` clears it at the provider — see {@link StandardBilling_CustomerAddress}\n   * for why clearability is expressed separately from omission.\n   */\n  phone?: string | null;\n  /**\n   * Billing address. `null` clears the whole address; a partial object clears only the fields it\n   * sets to `null` and leaves the rest untouched.\n   */\n  address?: StandardBilling_CustomerAddress | null;\n}\n\n/**\n * A stored payment instrument attached to a provider customer.\n *\n * Deliberately thin: enough to identify an instrument for detachment and to render a\n * \"•••• 4242\"-style hint, and nothing more. Wildo never handles raw instrument data — that is the\n * whole point of routing users through the provider-hosted portal — so this carries no PAN, no\n * expiry, and no billing details.\n */\nexport interface StandardBilling_PaymentMethodSummary {\n  providerPaymentMethodId: string;\n  /**\n   * Instrument kind as the provider names it (`'card'`, `'sepa_debit'`, `'us_bank_account'`, …).\n   * Intentionally an OPEN provider identifier, not a closed Wildo vocabulary: the set differs per\n   * provider and grows without our involvement, and nothing in the framework branches on it — it\n   * is carried for display and diagnostics only.\n   */\n  type: string;\n  /** Last four digits, when the instrument exposes them. */\n  last4?: string;\n}\n\n// ── Product/Price Sync ──────────────────────────────────────────\n\nexport interface StandardBilling_SyncProductRequest {\n  /** Internal Wildo product key (stored in metadata for reverse lookup) */\n  productKey: string;\n  name: string;\n  description?: string;\n  /** If set, updates existing provider product instead of creating new */\n  providerProductId?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_SyncProductResponse {\n  providerProductId: string;\n}\n\nexport interface StandardBilling_SyncPriceRequest {\n  providerProductId: string;\n  model: PricingModel;\n  /** Amount in smallest currency unit (cents) */\n  amount: number;\n  currency: string;\n  interval?: BillingInterval;\n  /** Multiplier of the recurring interval (3 months = quarterly). Omitted means 1; ignored for one-time prices. */\n  intervalCount?: number;\n  /** For TIERED/VOLUME pricing models */\n  tiers?: Array<{\n    upTo: number | null;\n    unitAmount: number;\n    flatAmount?: number;\n  }>;\n  /** For PACKAGE pricing */\n  packageSize?: number;\n  /** Tax behavior */\n  taxBehavior?: TaxDisplayMode;\n  /** If set, updates existing provider price instead of creating new */\n  providerPriceId?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_SyncPriceResponse {\n  providerPriceId: string;\n}\n\n// ── Subscription Lifecycle ──────────────────────────────────────\n\nexport interface StandardBilling_CreateSubscriptionRequest {\n  providerCustomerId: string;\n  items: Array<{\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  trialPeriodDays?: number;\n  /** Provider promotion code to apply */\n  providerPromotionCodeId?: string;\n  /**\n   * Ask the provider to compute tax on this purchase (#408, 2026-09-08).\n   *\n   * Set from the application's `billing.tax.calculationMode`, which is PROVIDER_MANAGED or\n   * DISABLED — Wildo never calculates tax locally, so the only question a provider is asked is\n   * whether to calculate at all. A provider that cannot compute tax ignores this; one that can and\n   * is not configured for the customer's jurisdiction will say so at the call, which is the right\n   * place for that failure.\n   *\n   * Distinct from a price's `taxBehavior`, which says whether a displayed amount INCLUDES tax.\n   * That one has always reached the provider; this one decides whether tax is computed.\n   */\n  automaticTax?: boolean;\n  /**\n   * Require a payment method up front for a trial (#408, 2026-09-08).\n   *\n   * Set from the product's `behaviorPolicy.trial.requirePaymentMethod`, which was declared,\n   * labelled, rendered on billing screens and passed to no provider call — so a trial declared as\n   * requiring a card behaved identically to one that did not. Wonder Todos' enterprise plan\n   * (`true`) and professional plan (`false`) were indistinguishable at the provider.\n   *\n   * Two provider-side consequences follow and a connector should honour both: collect the payment\n   * method during checkout, and decide what happens if the trial ends without one.\n   */\n  requirePaymentMethodForTrial?: boolean;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateSubscriptionResponse {\n  providerSubscriptionId: string;\n  status: string;\n}\n\n/** Provider-confirmed identities of correlated additions from the same update operation. */\nexport interface StandardBilling_UpdateSubscriptionResponse {\n  createdItems: Array<{ clientItemKey: string; providerSubscriptionItemId: string }>;\n}\n\nexport interface StandardBilling_UpdateSubscriptionRequest {\n  /**\n   * Server-owned identity of one attempted change, reused with the SAME subscription and payload\n   * when recovering a lost response. Never generate a new key for a retry. Provider retention is\n   * bounded: this does not replace confirmation consumption, freshness checks or reconciliation.\n   * This is request transport metadata, not subscription metadata or a browser authoring field.\n   */\n  idempotencyKey?: string;\n  /** Item patches: omitted existing items are retained; an item without an ID is added. */\n  items?: Array<{\n    /** Provider-side subscription item ID to update. Omit only when adding a new item. */\n    providerSubscriptionItemId?: string;\n    /** Backend-generated correlation key for an intentional new item; echoed with its created provider ID. */\n    clientItemKey?: string;\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  /** Explicit provider-side item IDs to remove. Omitting an item from `items` never removes it. */\n  removedProviderSubscriptionItemIds?: string[];\n  /** Provider promotion code to apply */\n  providerPromotionCodeId?: string;\n  /**\n   * How the provider settles this mid-cycle change (#516).\n   *\n   * The engine resolves it from the target product's `upgrade`/`downgrade` behaviour policy and it\n   * had nowhere to travel: it was put in `metadata`, a free-form bag the provider does not read, so a\n   * product declaring `NONE` for a downgrade was still prorated by the provider's own default. Absent\n   * means \"do not send one\" — the provider applies its account default, which is what every\n   * subscription update did before this field existed.\n   */\n  prorationBehavior?: ProrationBehavior;\n  /**\n   * How the provider treats an unpaid resulting invoice (#535, D6). Absent sends none, so the provider's default\n   * applies; the engine's own plan-change dispatch always declares it.\n   */\n  paymentBehavior?: StandardBilling_SubscriptionPaymentBehavior;\n  /** Unix seconds used for proration. Reuse the preview instant when confirming the same change. */\n  prorationDate?: number;\n  metadata?: Record<string, string>;\n}\n\n/**\n * Hypothetical item patch for an upcoming invoice. Item identity, quantity and proration must match\n * the eventual update; selecting the first provider item can accidentally preview an addon change.\n * Omitted items remain on the subscription. This request never changes the subscription itself.\n */\nexport type StandardBilling_SubscriptionPreviewRequest = Pick<StandardBilling_UpdateSubscriptionRequest,\n  'items' | 'removedProviderSubscriptionItemIds' | 'prorationBehavior' | 'prorationDate'>;\n\n/**\n * Request transport options shared by the subscription mutations that carry no payload of their own.\n *\n * `idempotencyKey` has the same contract as on {@link StandardBilling_UpdateSubscriptionRequest}: a server-owned\n * identity of ONE attempted change, reused with the same subscription and options only to recover a lost response.\n */\nexport interface StandardBilling_SubscriptionMutationOptions {\n  idempotencyKey?: string;\n}\n\n/**\n * A plan change deferred to the end of the subscription's current period (#1868).\n *\n * The provider keeps the subscription as it is until the period ends and then moves it onto `items`. Stripe does this with a\n * subscription schedule: one phase holding the current lines until `current_period_end`, a second holding `items`, released\n * afterwards so the subscription runs on without it. The adapter derives the current lines and the period end from the\n * subscription itself, so the change always lands at the renewal of the period it was confirmed in.\n */\nexport interface StandardBilling_SchedulePlanChangeRequest extends StandardBilling_SubscriptionMutationOptions {\n  /** Every line the subscription carries from the next period: the new plan and the add-ons that carry over. */\n  items: Array<{ providerPriceId: string; quantity: number }>;\n  /** How the provider settles the move into the new lines at renewal. Absent sends none. */\n  prorationBehavior?: ProrationBehavior;\n  /** Written on the schedule, so a later read can name the change that created it (`wildo_mutation`). */\n  metadata?: Record<string, string>;\n}\n\n/** The provider's handle on a deferred plan change: what `releaseSubscriptionSchedule` withdraws. */\nexport interface StandardBilling_SchedulePlanChangeResponse {\n  providerScheduleId: string;\n}\n\n/** How a schedule is released (#1868). */\nexport interface StandardBilling_ReleaseScheduleOptions extends StandardBilling_SubscriptionMutationOptions {\n  /**\n   * Release only while the schedule still has a phase AHEAD of the current one — a WITHDRAWAL of a change that has not taken effect. A\n   * schedule still managing the subscription with its next phase begun is refused conclusively, nothing sent: releasing it then would\n   * keep the subscription on the lines the change moved it to, while the caller believed the change withdrawn. A schedule already\n   * released, cancelled or completed succeeds only when the caller's key replays its own earlier release; otherwise it answers an\n   * INDETERMINATE failure — it may be this caller's release, so only a read of what the provider bills can say whether the withdrawal\n   * happened. Absent, a schedule is released whatever phase it is in, which is\n   * how the engine lets go of a schedule whose change has already landed.\n   */\n  onlyBeforeNextPhase?: boolean;\n}\n\nexport interface StandardBilling_CancelSubscriptionOptions extends StandardBilling_SubscriptionMutationOptions {\n  /** If true, subscription remains active until current period ends */\n  atPeriodEnd?: boolean;\n}\n\n// ── Read/Sync (Reconciliation) ──────────────────────────────────\n\n/**\n * StandardBilling_SubscriptionData: canonical subscription representation\n * returned by the provider adapter's retrieveSubscription().\n * Used for reconciliation when webhooks may have been missed.\n */\nexport interface StandardBilling_SubscriptionData {\n  providerSubscriptionId: string;\n  status: SubscriptionStatus;\n  currentPeriodStart: Date;\n  currentPeriodEnd: Date;\n  cancelAtPeriodEnd: boolean;\n  /**\n   * When the subscription's trial began and ends, if it had one. The provider keeps both after the trial\n   * is over, so a subscription that trialed carries them for its whole life, and one that never did\n   * carries neither.\n   */\n  trialStart?: Date;\n  trialEnd?: Date;\n  /**\n   * The schedule the provider holds on this subscription, if any (#1868): how a deferred plan change is kept until renewal.\n   * `upcomingPhase` is the phase after the current one — the lines the subscription moves to and when — and is absent once\n   * the last phase is current, which for an engine-created schedule means its change has taken effect. `metadata` carries\n   * the reference of the engine mutation that created the schedule (`wildo_mutation`), absent on one made elsewhere.\n   */\n  schedule?: {\n    providerScheduleId: string;\n    metadata: Record<string, string>;\n    upcomingPhase?: { startsAt: Date; items: Array<{ providerPriceId: string; quantity: number }> };\n  };\n  items: Array<{\n    providerSubscriptionItemId: string;\n    providerProductId: string;\n    providerPriceId: string;\n    quantity: number;\n  }>;\n  /**\n   * Every subscription-level discount the provider applies, from coupons and promotion codes, in the order the provider\n   * applies them. Absent or empty when none applies, including after the last one has ended.\n   *\n   * ALL of them, because a subscription can hold several — a referral reward (`addSubscriptionDiscount`) is added BESIDE\n   * a promotion the checkout applied — and each is charged (#1948). An adapter that reported only the first would leave\n   * the application showing one discount while the customer is billed for two.\n   * `duration` is a `PromotionDuration` value: `once`, `repeating` or `forever`.\n   */\n  discounts?: Array<{\n    providerCouponId: string;\n    percentOff?: number;\n    amountOff?: number;\n    currency?: string;\n    duration: string;\n    durationInMonths?: number;\n    end?: Date;\n  }>;\n}\n\n/**\n * StandardBilling_InvoicePreview: canonical upcoming invoice from provider.\n * Returned by retrieveUpcomingInvoice() for plan change previews.\n */\nexport interface StandardBilling_InvoicePreview {\n  /** Upcoming invoice amount due, in currency minor units; not a promise of an immediate charge. */\n  amount: number;\n  currency: string;\n  lineItems: Array<{\n    description: string;\n    amount: number;\n    quantity: number;\n    providerPriceId?: string;\n  }>;\n  periodStart: Date;\n  periodEnd: Date;\n}\n\n/**\n * StandardBilling_InvoiceData: an invoice the provider ALREADY holds.\n *\n * Distinct from {@link StandardBilling_InvoicePreview}, and the distinction is the point: a preview\n * is a hypothetical the provider computes on request and never stores, while this is a record that\n * exists at the provider whether or not Wildo ever heard about it. The second is what a\n * reconciliation sweep needs — a webhook that was never delivered leaves an invoice that exists\n * there and nowhere here, and no amount of previewing finds it.\n *\n * Deliberately thin. It carries what `invoiceRefs` stores and nothing else: line items, tax\n * breakdowns and payment attempts live at the provider, and the customer reaches them through the\n * provider-hosted portal.\n */\nexport interface StandardBilling_InvoiceData {\n  providerInvoiceId: string;\n  /** The customer the invoice was billed to — the key that maps it back to a local billing account. */\n  providerCustomerId: string;\n  status: InvoiceStatus;\n  /**\n   * The invoice TOTAL, in the CURRENCY's smallest unit.\n   *\n   * The total, not the amount PAID: an invoice's value does not depend on whether it has been\n   * settled, and an unpaid invoice recorded at zero is indistinguishable from a zero invoice.\n   */\n  total: number;\n  currency: string;\n  hostedInvoiceUrl?: string;\n  invoicePdfUrl?: string;\n  /** When the provider created the invoice — used to bound how far back a sweep looks. */\n  createdAt: Date;\n}\n\n// ── Checkout / Portal (Provider-Hosted UI) ──────────────────────\n\nexport interface StandardBilling_CreateCheckoutSessionRequest {\n  providerCustomerId: string;\n  lineItems: Array<{\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  /** Checkout mode: 'subscription' for recurring, 'payment' for one-time */\n  mode: 'subscription' | 'payment';\n  successUrl: string;\n  cancelUrl: string;\n  /** Allow promotion codes in checkout */\n  allowPromotionCodes?: boolean;\n  /** Pre-fill promotion code */\n  providerPromotionCodeId?: string;\n  /** Trial period for subscriptions */\n  trialPeriodDays?: number;\n  /**\n   * Ask the provider to compute tax on this purchase (#408, 2026-09-08).\n   *\n   * Set from the application's `billing.tax.calculationMode`, which is PROVIDER_MANAGED or\n   * DISABLED — Wildo never calculates tax locally, so the only question a provider is asked is\n   * whether to calculate at all. A provider that cannot compute tax ignores this; one that can and\n   * is not configured for the customer's jurisdiction will say so at the call, which is the right\n   * place for that failure.\n   *\n   * Distinct from a price's `taxBehavior`, which says whether a displayed amount INCLUDES tax.\n   * That one has always reached the provider; this one decides whether tax is computed.\n   */\n  automaticTax?: boolean;\n  /**\n   * Require a payment method up front for a trial (#408, 2026-09-08).\n   *\n   * Set from the product's `behaviorPolicy.trial.requirePaymentMethod`, which was declared,\n   * labelled, rendered on billing screens and passed to no provider call — so a trial declared as\n   * requiring a card behaved identically to one that did not. Wonder Todos' enterprise plan\n   * (`true`) and professional plan (`false`) were indistinguishable at the provider.\n   *\n   * Two provider-side consequences follow and a connector should honour both: collect the payment\n   * method during checkout, and decide what happens if the trial ends without one.\n   */\n  requirePaymentMethodForTrial?: boolean;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCheckoutSessionResponse {\n  /** Redirect URL for the hosted checkout page */\n  url: string;\n  sessionId: string;\n}\n\nexport interface StandardBilling_CreateCustomerPortalSessionResponse {\n  /** Redirect URL for the customer portal */\n  url: string;\n}\n\n// ── Usage Reporting (METERED products via Billing Meter Events) ─\n\nexport interface StandardBilling_ReportUsageRequest {\n  /** Meter event name (corresponds to the meter's event_name) */\n  meterEventName: string;\n  /** Provider customer ID (maps to payload.stripe_customer_id in Stripe) */\n  providerCustomerId: string;\n  /** Usage value to report */\n  value: number;\n  /** Optional event timestamp */\n  timestamp?: Date;\n  /** Optional unique event identifier (for idempotency) */\n  identifier?: string;\n}\n\n// ── Promotions ──────────────────────────────────────────────────\n\nexport interface StandardBilling_CreateCouponRequest {\n  /** Discount amount in smallest currency unit (for fixed discounts) */\n  amountOff?: number;\n  /** Discount percentage (for percentage discounts) */\n  percentOff?: number;\n  currency?: string;\n  duration: 'once' | 'repeating' | 'forever';\n  durationInMonths?: number;\n  maxRedemptions?: number;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCouponResponse {\n  providerCouponId: string;\n}\n\nexport interface StandardBilling_CreatePromotionCodeResponse {\n  providerPromotionId: string;\n}\n\n/**\n * A percentage discount GIVEN to one subscription — a referral reward (#1802) — rather than redeemed by the\n * customer from a code.\n */\nexport interface StandardBilling_AddSubscriptionDiscountRequest {\n  /** Percentage taken off, 1–100. */\n  percentOff: number;\n  duration: 'once' | 'repeating' | 'forever';\n  /** Months, for a `repeating` discount. */\n  durationInMonths?: number;\n  /**\n   * Stable per grant. The adapter derives the provider coupon's identity and its idempotency keys from it, so\n   * a repeated call with the same key adds the discount once.\n   */\n  grantKey: string;\n  metadata?: Record<string, string>;\n}\n\n// ===============================================================\n// Standard Billing Interface\n// ===============================================================\n\n/**\n * Provider-agnostic billing interface.\n * Each billing provider (Stripe, Paddle, etc.) implements this interface\n * through a transformer that maps canonical operations to provider SDK calls.\n */\nexport interface StandardBilling_Interface {\n  // ── Customer (maps to BillingAccount) ──\n  createCustomer(request: StandardBilling_CreateCustomerRequest): Promise<StandardBilling_CreateCustomerResponse>;\n  updateCustomer(providerCustomerId: string, request: StandardBilling_UpdateCustomerRequest): Promise<void>;\n  /**\n   * Hard-delete the provider customer.\n   *\n   * ⚠️ NOT the subject-erasure path. Erasing a subject ANONYMIZES this customer (blank the personal\n   * fields, keep the record) because the financial history hanging off it — invoices, subscriptions,\n   * usage — is retained under a legal obligation and must stay attributable to its provider record.\n   * Deleting the customer would strand exactly the audit trail retention exists to preserve.\n   * Reserve this for a genuine account teardown with no retained history.\n   */\n  deleteCustomer(providerCustomerId: string): Promise<void>;\n\n  // ── Payment instruments ──\n  /**\n   * Stored payment instruments for a customer. Used by subject erasure to enumerate what must be\n   * detached; day-to-day management belongs in the provider-hosted portal.\n   */\n  listPaymentMethods(providerCustomerId: string): Promise<StandardBilling_PaymentMethodSummary[]>;\n  /**\n   * Detach an instrument from its customer. Detaching does NOT delete the instrument's transaction\n   * history at the provider — it stops future charges and unlinks it from the customer, which is\n   * what erasure needs and what the retained invoice record requires.\n   */\n  detachPaymentMethod(providerPaymentMethodId: string): Promise<void>;\n  /**\n   * Blank the personal data an instrument carries about whoever paid with it — the cardholder's name,\n   * email, phone and billing address — keeping the instrument itself (#869).\n   *\n   * Detaching does not do this: a detached instrument still exists at the provider with its billing\n   * details intact, and on Stripe it can no longer be edited once detached (\"You must save this\n   * PaymentMethod to a customer before you can update it\", measured 2026-09-25). So subject erasure\n   * calls this BEFORE {@link detachPaymentMethod}. A provider field that cannot be unset stays: Stripe\n   * refuses to clear `address.country`, which identifies nobody on its own.\n   *\n   * The card network data (brand, last four digits, expiry, fingerprint) is the instrument, not contact\n   * data, and stays with the retained transaction record it belongs to.\n   */\n  redactPaymentMethodBillingDetails(providerPaymentMethodId: string): Promise<void>;\n\n  // ── Product/Price sync (Wildo → Provider) ──\n  syncProduct(request: StandardBilling_SyncProductRequest): Promise<StandardBilling_SyncProductResponse>;\n  syncPrice(request: StandardBilling_SyncPriceRequest): Promise<StandardBilling_SyncPriceResponse>;\n  /**\n   * Whether the provider price a local price is LINKED to still carries the local terms (#1907): active, on the\n   * requested product, and equal in amount, currency, cadence, tiers, packaging and tax behaviour.\n   *\n   * A provider price is immutable, so a link made under an earlier amount convention — or before a catalogue edit —\n   * keeps charging the old amount unless something compares the two. The catalogue sync asks this of every linked\n   * price and re-syncs one that answers `false`. Answer `false` when the price cannot be read: the caller then\n   * creates a correct price rather than keeping a link nobody could check.\n   */\n  linkedPriceMatches(providerPriceId: string, request: StandardBilling_SyncPriceRequest): Promise<boolean>;\n\n  // ── Subscription lifecycle ──\n  // NOTE: User-initiated plan changes, cancellation, and payment method management\n  // should use createCustomerPortalSession() instead of calling these directly.\n  // These methods are for: initial checkout completion, backend-driven upgrades,\n  // admin-triggered changes, and webhook-driven updates.\n  createSubscription(request: StandardBilling_CreateSubscriptionRequest): Promise<StandardBilling_CreateSubscriptionResponse>;\n  updateSubscription(providerSubscriptionId: string, request: StandardBilling_UpdateSubscriptionRequest): Promise<StandardBilling_UpdateSubscriptionResponse>;\n  cancelSubscription(providerSubscriptionId: string, options?: StandardBilling_CancelSubscriptionOptions): Promise<void>;\n  pauseSubscription(providerSubscriptionId: string): Promise<void>;\n  /** Resume paused payment collection; does not undo a scheduled cancellation. */\n  resumeSubscription(providerSubscriptionId: string): Promise<void>;\n  /** Remove a pending period-end cancellation without changing collection or lifecycle status. */\n  removeScheduledCancellation(providerSubscriptionId: string, options?: StandardBilling_SubscriptionMutationOptions): Promise<void>;\n  /**\n   * Defer a plan change to the end of the current period (#1868). One deferred change at a time: the engine refuses a second\n   * while one is pending, and it is withdrawn (`releaseSubscriptionSchedule`) before another is made.\n   */\n  schedulePlanChange(providerSubscriptionId: string, request: StandardBilling_SchedulePlanChangeRequest): Promise<StandardBilling_SchedulePlanChangeResponse>;\n  /**\n   * Withdraw a schedule from its subscription, leaving the subscription running as it is now (#1868). Releasing a schedule that is\n   * already released succeeds: the state asked for holds — except with `onlyBeforeNextPhase`, where it succeeds only as a replay of the\n   * caller's own release and otherwise answers an INDETERMINATE failure, and the caller decides from what the provider bills.\n   */\n  releaseSubscriptionSchedule(providerScheduleId: string, options?: StandardBilling_ReleaseScheduleOptions): Promise<void>;\n  /**\n   * Classify an error thrown by `updateSubscription`, `cancelSubscription`, `removeScheduledCancellation`, `schedulePlanChange` or\n   * `releaseSubscriptionSchedule` (#535, D3).\n   *\n   * Must answer {@link StandardBilling_MutationErrorClass.INDETERMINATE} for anything the adapter cannot positively place\n   * — including an error the adapter itself threw AFTER the provider answered — because every other class licenses the\n   * caller to record that the change did not happen.\n   */\n  classifyMutationError(error: unknown): StandardBilling_MutationErrorClass;\n\n  // ── Read/sync (for reconciliation and upcoming cost preview) ──\n  /** On-demand retrieval for reconciliation (if webhook missed) */\n  retrieveSubscription(providerSubscriptionId: string): Promise<StandardBilling_SubscriptionData>;\n  /** Preview the upcoming invoice for an optional item change; the amount is not necessarily charged immediately. */\n  retrieveUpcomingInvoice(providerSubscriptionId: string, request?: StandardBilling_SubscriptionPreviewRequest): Promise<StandardBilling_InvoicePreview>;\n  /**\n   * Invoices the provider holds for one customer, newest first.\n   *\n   * The RECOVERY read for {@link StandardBilling_EventType.INVOICE_PAID} and its siblings. Wildo\n   * never creates an invoice — every local `invoiceRefs` row exists because a webhook arrived — so a\n   * delivery that is lost, or that arrives while the application is down and exhausts the provider's\n   * retries, leaves an invoice with no local trace and nothing that could notice. This is the only\n   * call that can find one.\n   *\n   * `limit` bounds one page and an adapter may cap it lower; the sweep asks for a recent window\n   * rather than the whole history, because an invoice older than the window has either been\n   * reconciled already or is a backlog no single tick should try to drain.\n   */\n  listInvoices(providerCustomerId: string, options?: { limit?: number }): Promise<StandardBilling_InvoiceData[]>;\n\n  // ── Provider-hosted UI (primary user-facing interactions) ──\n  /** Hosted checkout page — NO Stripe Elements needed, no PCI scope */\n  createCheckoutSession(request: StandardBilling_CreateCheckoutSessionRequest): Promise<StandardBilling_CreateCheckoutSessionResponse>;\n  /** Customer portal for: invoices, payment methods, billing address, cancel */\n  createCustomerPortalSession(providerCustomerId: string, returnUrl: string): Promise<StandardBilling_CreateCustomerPortalSessionResponse>;\n\n  // ── Usage reporting (for METERED products) ──\n  reportUsage(request: StandardBilling_ReportUsageRequest): Promise<void>;\n\n  // ── Webhooks ──\n  /** HTTP header name that carries the webhook signature (e.g., 'stripe-signature') */\n  readonly webhookSignatureHeaderName: string;\n  verifyWebhookSignature(payload: string | Uint8Array, signature: string, secret: string): boolean;\n  /** Parse a raw webhook payload into a canonical event. Returns null for unknown/unhandled event types. */\n  parseWebhookEvent(payload: string | Uint8Array): StandardBilling_WebhookEvent | null;\n\n  // ── Promotions (synced to provider) ──\n  createCoupon(request: StandardBilling_CreateCouponRequest): Promise<StandardBilling_CreateCouponResponse>;\n  createPromotionCode(providerCouponId: string, code: string): Promise<StandardBilling_CreatePromotionCodeResponse>;\n  /**\n   * Add a discount to a subscription, KEEPING any discount it already carries (#1802). Idempotent on\n   * `request.grantKey`: a second call with the same key finds its discount already applied and adds nothing.\n   */\n  addSubscriptionDiscount(providerSubscriptionId: string, request: StandardBilling_AddSubscriptionDiscountRequest): Promise<void>;\n}\n"]}
+{"version":3,"file":"billing.standard-interface.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/billing.standard-interface.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Standard Billing Interface\n * --------\n * This is the canonical interface that Wildo uses internally for all billing\n * operations. The ETL layer transforms these standard requests into\n * provider-specific API calls (e.g., Stripe, Paddle, LemonSqueezy).\n *\n * Design Principles:\n * 1. Provider-agnostic — works with any billing provider\n * 2. Hosted-first — uses provider-hosted checkout and portals (no PCI scope)\n * 3. Webhook-driven — state changes flow in via webhooks, not polling\n * 4. Scope-agnostic — billing accounts map to any Wildo scope (org, user)\n *\n * @see billing-and-features-system.md §7.1 (Standard Billing Interface)\n */\n\n// ===============================================================\n// Billing Interface Enums (canonical source, re-exported by saas-models)\n// ===============================================================\n\n/**\n * Pricing model for a price entry.\n */\nexport enum PricingModel {\n  FLAT = 'flat',\n  PER_UNIT = 'per_unit',\n  /** Volume pricing (all units at tier price) */\n  TIERED = 'tiered',\n  /** Incremental (each tier priced independently) */\n  GRADUATED = 'graduated',\n  /** Price per package of N units */\n  PACKAGE = 'package',\n}\n\n/**\n * Billing interval for recurring prices.\n */\nexport enum BillingInterval {\n  MONTH = 'month',\n  YEAR = 'year',\n}\n\n/**\n * Tax display mode: how prices are displayed (HT vs TTC).\n */\nexport enum TaxDisplayMode {\n  /** Price amounts are HT (tax added at checkout) */\n  EXCLUSIVE = 'exclusive',\n  /** Price amounts are TTC (tax embedded) */\n  INCLUSIVE = 'inclusive',\n}\n\n/**\n * How a mid-cycle subscription change is settled.\n *\n * A PROTOCOL vocabulary, and it lives here for the same reason {@link TaxDisplayMode} does: these three\n * values are the wire values a billing provider accepts. It was declared in `@wildo-ai/saas-models`\n * until 2026-09-08 and re-exported the other way round, which is why an authored proration could be\n * resolved by the engine and had no field on the request to travel in — the request contract could not\n * name the type without a package cycle, so the resolved value was sent as provider METADATA and\n * ignored (#516).\n *\n * `@wildo-ai/saas-models` re-exports it, so every existing consumer is unchanged.\n */\nexport enum ProrationBehavior {\n  /** Credit the unused time and charge the new price pro rata, settled on the next invoice. */\n  CREATE_PRORATIONS = 'create_prorations',\n  /** No proration: the change takes effect and the next invoice is the new price in full. */\n  NONE = 'none',\n  /** Prorate and invoice the difference IMMEDIATELY rather than at the next cycle. */\n  ALWAYS_INVOICE = 'always_invoice',\n}\n\n/**\n * How the provider treats a subscription change whose resulting payment does not succeed (#535, decision D6).\n *\n * Wildo applies a confirmed plan change IMMEDIATELY: entitlements move at local completion, and a failed proration\n * payment moves the subscription to `past_due` through the webhook projection, where dunning owns what happens next.\n * The value is DECLARED on every engine-issued change rather than left to the provider's default, so a change of that\n * default can never silently change the semantics.\n *\n * Deliberately a one-member vocabulary. `pending_if_incomplete` (apply only after payment, expire after 23 h) was\n * weighed and rejected in #535; add a member only with a decision that changes D6.\n *\n * spec-cite: https://docs.stripe.com/api/subscriptions/update — `payment_behavior`; the value equals Stripe's wire value,\n * so the Stripe adapter passes it untranslated, as it does `ProrationBehavior`.\n */\nexport enum StandardBilling_SubscriptionPaymentBehavior {\n  /** Apply the change now; an unpaid resulting invoice leaves the subscription `past_due`. */\n  ALLOW_INCOMPLETE = 'allow_incomplete',\n}\n\n/**\n * What a FAILED provider mutation tells the caller about whether the change took effect (#535, decision D3).\n *\n * The distinction that matters is not the HTTP status but what may be recorded next: a conclusive refusal and a request\n * that never executed may both be recorded as \"no effect\", while an indeterminate outcome must NEVER be — the provider\n * may have applied it, or may still apply it. Only the adapter can read its vendor's error shape, so each adapter\n * classifies (`StandardBilling_Interface.classifyMutationError`) and the engine decides on the class alone.\n *\n * spec-cite: https://docs.stripe.com/error-low-level — \"Network errors\", \"Server errors\", \"Content errors\" (the\n * source of the classes for the Stripe adapter; other adapters map their own vendor's equivalents).\n */\nexport enum StandardBilling_MutationErrorClass {\n  /** The provider evaluated the request and refused it (e.g. a declined card, a missing object). No effect. */\n  CONCLUSIVE_REJECTION = 'conclusive_rejection',\n  /** Refused before execution (rate limit, authentication). No effect; a later attempt must use a NEW idempotency key. */\n  NOT_EXECUTED = 'not_executed',\n  /** Another request with the same idempotency key is still being processed. The outcome is not known yet. */\n  IN_FLIGHT_CONFLICT = 'in_flight_conflict',\n  /** Timeout, connection loss, server error, or a failure after the provider answered. The change may have applied. */\n  INDETERMINATE = 'indeterminate',\n}\n\n/**\n * Subscription status values (maps to Stripe subscription statuses).\n */\nexport enum SubscriptionStatus {\n  ACTIVE = 'active',\n  PAST_DUE = 'past_due',\n  UNPAID = 'unpaid',\n  CANCELLED = 'cancelled',\n  /** Stripe: first payment never completed within 23h window */\n  INCOMPLETE = 'incomplete',\n  INCOMPLETE_EXPIRED = 'incomplete_expired',\n  TRIALING = 'trialing',\n  PAUSED = 'paused',\n}\n\n/**\n * Invoice lifecycle status, as the PROVIDER reports it.\n *\n * A PROTOCOL vocabulary for the same reason {@link SubscriptionStatus} is one: these are the states\n * a billing provider puts an invoice in, and the adapter's job is to map its own wire values onto\n * them. It was declared in `@wildo-ai/saas-models` until 2026-09-09 and could not be named by this\n * package at all, so `listInvoices` — the read the reconciliation sweep needs — had no way to type\n * the one field the sweep compares.\n *\n * Moved rather than duplicated: a second enum with the same five members would be two sources for\n * one closed vocabulary, which is what `CLAUDE.md` forbids. `@wildo-ai/saas-models` re-exports it\n * exactly as it already re-exports `SubscriptionStatus`, `TaxDisplayMode` and `ProrationBehavior`,\n * so every existing consumer — including the `invoiceRefs` schema, the badge palette and the\n * documentation catalogue — imports the same specifier it always did.\n */\nexport enum InvoiceStatus {\n  /** Not finalized: the provider has not issued it for collection and it may still change. */\n  DRAFT = 'draft',\n  /** Finalized and awaiting payment. */\n  OPEN = 'open',\n  /** Settled. */\n  PAID = 'paid',\n  /** Cancelled by the provider or the merchant; never collectable. */\n  VOID = 'void',\n  /** Written off — payment was attempted and abandoned. */\n  UNCOLLECTIBLE = 'uncollectible',\n}\n\n// ===============================================================\n// Standard Billing Event Types\n// ===============================================================\n\n/**\n * Canonical billing events the system cares about.\n * Provider-specific events are mapped to these types by the transformer.\n * Only events that affect local state (features, status) need to be handled.\n */\nexport enum StandardBilling_EventType {\n  // Subscription lifecycle (→ feature sync)\n  SUBSCRIPTION_CREATED = 'subscription.created',\n  SUBSCRIPTION_UPDATED = 'subscription.updated',\n  SUBSCRIPTION_DELETED = 'subscription.deleted',\n  SUBSCRIPTION_TRIAL_WILL_END = 'subscription.trial_will_end',\n\n  // Invoice status (→ billing status tracking, past_due detection)\n  INVOICE_PAID = 'invoice.paid',\n  /**\n   * A payment of the invoice failed. The invoice stays OPEN while the provider retries: a failed attempt is not a\n   * status, and only {@link INVOICE_MARKED_UNCOLLECTIBLE} says the invoice will not be collected (#2929).\n   */\n  INVOICE_PAYMENT_FAILED = 'invoice.payment_failed',\n  INVOICE_FINALIZED = 'invoice.finalized',\n  /** The invoice was marked uncollectible: by the provider once its retries are exhausted, or by hand. */\n  INVOICE_MARKED_UNCOLLECTIBLE = 'invoice.marked_uncollectible',\n  /** The invoice was voided: it is no longer owed. */\n  INVOICE_VOIDED = 'invoice.voided',\n\n  // Checkout (→ one-off purchase completion for ONE_TIME, CREDIT_PACK, ITEM products)\n  CHECKOUT_SESSION_COMPLETED = 'checkout.session.completed',\n\n  // Customer (→ billing account sync)\n  CUSTOMER_UPDATED = 'customer.updated',\n  CUSTOMER_DELETED = 'customer.deleted',\n\n  // Coupon (→ no local action; coupons are managed through Wildo's promotion system.\n  // Included for logging/audit in case coupons are modified directly on the provider.)\n  COUPON_CREATED = 'coupon.created',\n  COUPON_UPDATED = 'coupon.updated',\n  COUPON_DELETED = 'coupon.deleted',\n\n  // Customer discount (→ subscription re-sync to pick up discount changes)\n  CUSTOMER_DISCOUNT_CREATED = 'customer.discount.created',\n  CUSTOMER_DISCOUNT_UPDATED = 'customer.discount.updated',\n  CUSTOMER_DISCOUNT_DELETED = 'customer.discount.deleted',\n\n  // Payment method (→ no local action needed; provider manages via Customer Portal.\n  // Included for completeness: apps can optionally log these events for audit trails.)\n  PAYMENT_METHOD_ATTACHED = 'payment_method.attached',\n  PAYMENT_METHOD_DETACHED = 'payment_method.detached',\n}\n\n// ===============================================================\n// Standard Billing Webhook Event\n// ===============================================================\n\n/**\n * Canonical webhook event representation.\n * Provider transformers parse raw webhook payloads into this shape.\n */\nexport interface StandardBilling_WebhookEvent {\n  /** Canonical event type */\n  type: StandardBilling_EventType;\n  /** Provider-assigned event ID (for idempotency) */\n  providerEventId: string;\n  /** Event payload — shape varies by event type */\n  data: Record<string, unknown>;\n  /** When the event occurred at the provider */\n  createdAt: Date;\n}\n\n// ===============================================================\n// Request/Response Types\n// ===============================================================\n\n// ── Customer ────────────────────────────────────────────────────\n\nexport interface StandardBilling_CreateCustomerRequest {\n  /**\n   * Descriptive name — the organisation's name for an org-scoped account, the person's display name\n   * for a user-scoped one.\n   *\n   * OPTIONAL, and that is the point (issue #486). It was required, and a caller that could not\n   * resolve one therefore had to INVENT it: the engine sent the literal `'Unknown'` for every\n   * customer it ever created. A contract that cannot express \"we do not know\" forces every caller to\n   * lie, and a fabricated value is worse than an absent one — an operator reading the provider\n   * dashboard cannot tell it from a real answer.\n   */\n  name?: string;\n  /**\n   * Contact email for invoices and receipts.\n   *\n   * OPTIONAL for the same reason as `name`, and additionally because **an organisation frequently has\n   * no billing email at all**. Sending a natural person's address for an ORGANISATION's customer\n   * record would put personal data on a record that is not about a person — the opposite of data\n   * minimisation, which asks that personal data be \"adequate, relevant and limited to what is\n   * necessary\".\n   * spec-cite: GDPR Art. 5(1)(c) — https://gdpr-info.eu/art-5-gdpr/\n   *\n   * It also makes the later erasure story cheap: an organisation record carrying no individual's\n   * identity never has to be visited when that individual exercises their right to erasure, so the\n   * obligation to inform recipients of an erasure does not reach it.\n   * spec-cite: GDPR Art. 17(2) — https://gdpr-info.eu/art-17-gdpr/\n   *\n   * Absent is a legitimate value at the provider: Stripe's own customer `email` is optional.\n   * spec-cite: N/A — describes the Stripe Customer object's declared optionality in this\n   * repository's own words (https://docs.stripe.com/api/customers/object).\n   */\n  email?: string;\n  /** Arbitrary key-value metadata stored on the provider customer */\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCustomerResponse {\n  providerCustomerId: string;\n}\n\n/**\n * Postal address on a provider customer record.\n *\n * Every field is independently clearable (`null`) rather than merely omittable: `undefined` means\n * \"leave whatever the provider already has\", `null` means \"blank it\". Subject erasure needs the\n * second meaning — an address that is silently preserved because the request could only express\n * \"no change\" is personal data surviving an erasure.\n */\nexport interface StandardBilling_CustomerAddress {\n  line1?: string | null;\n  line2?: string | null;\n  city?: string | null;\n  state?: string | null;\n  postalCode?: string | null;\n  /** ISO 3166-1 alpha-2 country code. */\n  country?: string | null;\n}\n\nexport interface StandardBilling_UpdateCustomerRequest {\n  name?: string;\n  email?: string;\n  metadata?: Record<string, string>;\n  /**\n   * Contact phone. `null` clears it at the provider — see {@link StandardBilling_CustomerAddress}\n   * for why clearability is expressed separately from omission.\n   */\n  phone?: string | null;\n  /**\n   * Billing address. `null` clears the whole address; a partial object clears only the fields it\n   * sets to `null` and leaves the rest untouched.\n   */\n  address?: StandardBilling_CustomerAddress | null;\n}\n\n/**\n * A stored payment instrument attached to a provider customer.\n *\n * Deliberately thin: enough to identify an instrument for detachment and to render a\n * \"•••• 4242\"-style hint, and nothing more. Wildo never handles raw instrument data — that is the\n * whole point of routing users through the provider-hosted portal — so this carries no PAN, no\n * expiry, and no billing details.\n */\nexport interface StandardBilling_PaymentMethodSummary {\n  providerPaymentMethodId: string;\n  /**\n   * Instrument kind as the provider names it (`'card'`, `'sepa_debit'`, `'us_bank_account'`, …).\n   * Intentionally an OPEN provider identifier, not a closed Wildo vocabulary: the set differs per\n   * provider and grows without our involvement, and nothing in the framework branches on it — it\n   * is carried for display and diagnostics only.\n   */\n  type: string;\n  /** Last four digits, when the instrument exposes them. */\n  last4?: string;\n}\n\n// ── Product/Price Sync ──────────────────────────────────────────\n\nexport interface StandardBilling_SyncProductRequest {\n  /** Internal Wildo product key (stored in metadata for reverse lookup) */\n  productKey: string;\n  name: string;\n  description?: string;\n  /** If set, updates existing provider product instead of creating new */\n  providerProductId?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_SyncProductResponse {\n  providerProductId: string;\n}\n\nexport interface StandardBilling_SyncPriceRequest {\n  providerProductId: string;\n  model: PricingModel;\n  /** Amount in smallest currency unit (cents) */\n  amount: number;\n  currency: string;\n  interval?: BillingInterval;\n  /** Multiplier of the recurring interval (3 months = quarterly). Omitted means 1; ignored for one-time prices. */\n  intervalCount?: number;\n  /** For TIERED/VOLUME pricing models */\n  tiers?: Array<{\n    upTo: number | null;\n    unitAmount: number;\n    flatAmount?: number;\n  }>;\n  /** For PACKAGE pricing */\n  packageSize?: number;\n  /** Tax behavior */\n  taxBehavior?: TaxDisplayMode;\n  /** If set, updates existing provider price instead of creating new */\n  providerPriceId?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_SyncPriceResponse {\n  providerPriceId: string;\n}\n\n// ── Subscription Lifecycle ──────────────────────────────────────\n\nexport interface StandardBilling_CreateSubscriptionRequest {\n  providerCustomerId: string;\n  items: Array<{\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  trialPeriodDays?: number;\n  /** Provider promotion code to apply */\n  providerPromotionCodeId?: string;\n  /**\n   * Ask the provider to compute tax on this purchase (#408, 2026-09-08).\n   *\n   * Set from the application's `billing.tax.calculationMode`, which is PROVIDER_MANAGED or\n   * DISABLED — Wildo never calculates tax locally, so the only question a provider is asked is\n   * whether to calculate at all. A provider that cannot compute tax ignores this; one that can and\n   * is not configured for the customer's jurisdiction will say so at the call, which is the right\n   * place for that failure.\n   *\n   * Distinct from a price's `taxBehavior`, which says whether a displayed amount INCLUDES tax.\n   * That one has always reached the provider; this one decides whether tax is computed.\n   */\n  automaticTax?: boolean;\n  /**\n   * Require a payment method up front for a trial (#408, 2026-09-08).\n   *\n   * Set from the product's `behaviorPolicy.trial.requirePaymentMethod`, which was declared,\n   * labelled, rendered on billing screens and passed to no provider call — so a trial declared as\n   * requiring a card behaved identically to one that did not. Wonder Todos' enterprise plan\n   * (`true`) and professional plan (`false`) were indistinguishable at the provider.\n   *\n   * Two provider-side consequences follow and a connector should honour both: collect the payment\n   * method during checkout, and decide what happens if the trial ends without one.\n   */\n  requirePaymentMethodForTrial?: boolean;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateSubscriptionResponse {\n  providerSubscriptionId: string;\n  status: string;\n}\n\n/** Provider-confirmed identities of correlated additions from the same update operation. */\nexport interface StandardBilling_UpdateSubscriptionResponse {\n  createdItems: Array<{ clientItemKey: string; providerSubscriptionItemId: string }>;\n}\n\nexport interface StandardBilling_UpdateSubscriptionRequest {\n  /**\n   * Server-owned identity of one attempted change, reused with the SAME subscription and payload\n   * when recovering a lost response. Never generate a new key for a retry. Provider retention is\n   * bounded: this does not replace confirmation consumption, freshness checks or reconciliation.\n   * This is request transport metadata, not subscription metadata or a browser authoring field.\n   */\n  idempotencyKey?: string;\n  /** Item patches: omitted existing items are retained; an item without an ID is added. */\n  items?: Array<{\n    /** Provider-side subscription item ID to update. Omit only when adding a new item. */\n    providerSubscriptionItemId?: string;\n    /** Backend-generated correlation key for an intentional new item; echoed with its created provider ID. */\n    clientItemKey?: string;\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  /** Explicit provider-side item IDs to remove. Omitting an item from `items` never removes it. */\n  removedProviderSubscriptionItemIds?: string[];\n  /** Provider promotion code to apply */\n  providerPromotionCodeId?: string;\n  /**\n   * How the provider settles this mid-cycle change (#516).\n   *\n   * The engine resolves it from the target product's `upgrade`/`downgrade` behaviour policy and it\n   * had nowhere to travel: it was put in `metadata`, a free-form bag the provider does not read, so a\n   * product declaring `NONE` for a downgrade was still prorated by the provider's own default. Absent\n   * means \"do not send one\" — the provider applies its account default, which is what every\n   * subscription update did before this field existed.\n   */\n  prorationBehavior?: ProrationBehavior;\n  /**\n   * How the provider treats an unpaid resulting invoice (#535, D6). Absent sends none, so the provider's default\n   * applies; the engine's own plan-change dispatch always declares it.\n   */\n  paymentBehavior?: StandardBilling_SubscriptionPaymentBehavior;\n  /** Unix seconds used for proration. Reuse the preview instant when confirming the same change. */\n  prorationDate?: number;\n  metadata?: Record<string, string>;\n}\n\n/**\n * Hypothetical item patch for an upcoming invoice. Item identity, quantity and proration must match\n * the eventual update; selecting the first provider item can accidentally preview an addon change.\n * Omitted items remain on the subscription. This request never changes the subscription itself.\n */\nexport type StandardBilling_SubscriptionPreviewRequest = Pick<StandardBilling_UpdateSubscriptionRequest,\n  'items' | 'removedProviderSubscriptionItemIds' | 'prorationBehavior' | 'prorationDate'>;\n\n/**\n * Request transport options shared by the subscription mutations that carry no payload of their own.\n *\n * `idempotencyKey` has the same contract as on {@link StandardBilling_UpdateSubscriptionRequest}: a server-owned\n * identity of ONE attempted change, reused with the same subscription and options only to recover a lost response.\n */\nexport interface StandardBilling_SubscriptionMutationOptions {\n  idempotencyKey?: string;\n}\n\n/**\n * A plan change deferred to the end of the subscription's current period (#1868).\n *\n * The provider keeps the subscription as it is until the period ends and then moves it onto `items`. Stripe does this with a\n * subscription schedule: one phase holding the current lines until `current_period_end`, a second holding `items`, released\n * afterwards so the subscription runs on without it. The adapter derives the current lines and the period end from the\n * subscription itself, so the change always lands at the renewal of the period it was confirmed in.\n */\nexport interface StandardBilling_SchedulePlanChangeRequest extends StandardBilling_SubscriptionMutationOptions {\n  /** Every line the subscription carries from the next period: the new plan and the add-ons that carry over. */\n  items: Array<{ providerPriceId: string; quantity: number }>;\n  /** How the provider settles the move into the new lines at renewal. Absent sends none. */\n  prorationBehavior?: ProrationBehavior;\n  /** Written on the schedule, so a later read can name the change that created it (`wildo_mutation`). */\n  metadata?: Record<string, string>;\n}\n\n/** The provider's handle on a deferred plan change: what `releaseSubscriptionSchedule` withdraws. */\nexport interface StandardBilling_SchedulePlanChangeResponse {\n  providerScheduleId: string;\n}\n\n/** How a schedule is released (#1868). */\nexport interface StandardBilling_ReleaseScheduleOptions extends StandardBilling_SubscriptionMutationOptions {\n  /**\n   * Release only while the schedule still has a phase AHEAD of the current one — a WITHDRAWAL of a change that has not taken effect. A\n   * schedule still managing the subscription with its next phase begun is refused conclusively, nothing sent: releasing it then would\n   * keep the subscription on the lines the change moved it to, while the caller believed the change withdrawn. A schedule already\n   * released, cancelled or completed succeeds only when the caller's key replays its own earlier release; otherwise it answers an\n   * INDETERMINATE failure — it may be this caller's release, so only a read of what the provider bills can say whether the withdrawal\n   * happened. Absent, a schedule is released whatever phase it is in, which is\n   * how the engine lets go of a schedule whose change has already landed.\n   */\n  onlyBeforeNextPhase?: boolean;\n}\n\nexport interface StandardBilling_CancelSubscriptionOptions extends StandardBilling_SubscriptionMutationOptions {\n  /** If true, subscription remains active until current period ends */\n  atPeriodEnd?: boolean;\n}\n\n// ── Read/Sync (Reconciliation) ──────────────────────────────────\n\n/**\n * StandardBilling_SubscriptionData: canonical subscription representation\n * returned by the provider adapter's retrieveSubscription().\n * Used for reconciliation when webhooks may have been missed.\n */\nexport interface StandardBilling_SubscriptionData {\n  providerSubscriptionId: string;\n  status: SubscriptionStatus;\n  currentPeriodStart: Date;\n  currentPeriodEnd: Date;\n  cancelAtPeriodEnd: boolean;\n  /**\n   * When the subscription's trial began and ends, if it had one. The provider keeps both after the trial\n   * is over, so a subscription that trialed carries them for its whole life, and one that never did\n   * carries neither.\n   */\n  trialStart?: Date;\n  trialEnd?: Date;\n  /**\n   * The schedule the provider holds on this subscription, if any (#1868): how a deferred plan change is kept until renewal.\n   * `upcomingPhase` is the phase after the current one — the lines the subscription moves to and when — and is absent once\n   * the last phase is current, which for an engine-created schedule means its change has taken effect. `metadata` carries\n   * the reference of the engine mutation that created the schedule (`wildo_mutation`), absent on one made elsewhere.\n   */\n  schedule?: {\n    providerScheduleId: string;\n    metadata: Record<string, string>;\n    upcomingPhase?: { startsAt: Date; items: Array<{ providerPriceId: string; quantity: number }> };\n  };\n  items: Array<{\n    providerSubscriptionItemId: string;\n    providerProductId: string;\n    providerPriceId: string;\n    quantity: number;\n  }>;\n  /**\n   * Every subscription-level discount the provider applies, from coupons and promotion codes, in the order the provider\n   * applies them. Absent or empty when none applies, including after the last one has ended.\n   *\n   * ALL of them, because a subscription can hold several — a referral reward (`addSubscriptionDiscount`) is added BESIDE\n   * a promotion the checkout applied — and each is charged (#1948). An adapter that reported only the first would leave\n   * the application showing one discount while the customer is billed for two.\n   * `duration` is a `PromotionDuration` value: `once`, `repeating` or `forever`.\n   */\n  discounts?: Array<{\n    providerCouponId: string;\n    percentOff?: number;\n    amountOff?: number;\n    currency?: string;\n    duration: string;\n    durationInMonths?: number;\n    end?: Date;\n  }>;\n}\n\n/**\n * StandardBilling_InvoicePreview: canonical upcoming invoice from provider.\n * Returned by retrieveUpcomingInvoice() for plan change previews.\n */\nexport interface StandardBilling_InvoicePreview {\n  /** Upcoming invoice amount due, in currency minor units; not a promise of an immediate charge. */\n  amount: number;\n  currency: string;\n  lineItems: Array<{\n    description: string;\n    amount: number;\n    quantity: number;\n    providerPriceId?: string;\n  }>;\n  periodStart: Date;\n  periodEnd: Date;\n}\n\n/**\n * StandardBilling_InvoiceData: an invoice the provider ALREADY holds.\n *\n * Distinct from {@link StandardBilling_InvoicePreview}, and the distinction is the point: a preview\n * is a hypothetical the provider computes on request and never stores, while this is a record that\n * exists at the provider whether or not Wildo ever heard about it. The second is what a\n * reconciliation sweep needs — a webhook that was never delivered leaves an invoice that exists\n * there and nowhere here, and no amount of previewing finds it.\n *\n * Deliberately thin. It carries what `invoiceRefs` stores and nothing else: line items, tax\n * breakdowns and payment attempts live at the provider, and the customer reaches them through the\n * provider-hosted portal.\n */\nexport interface StandardBilling_InvoiceData {\n  providerInvoiceId: string;\n  /** The customer the invoice was billed to — the key that maps it back to a local billing account. */\n  providerCustomerId: string;\n  status: InvoiceStatus;\n  /**\n   * The invoice TOTAL, in the CURRENCY's smallest unit.\n   *\n   * The total, not the amount PAID: an invoice's value does not depend on whether it has been\n   * settled, and an unpaid invoice recorded at zero is indistinguishable from a zero invoice.\n   */\n  total: number;\n  currency: string;\n  hostedInvoiceUrl?: string;\n  invoicePdfUrl?: string;\n  /** When the provider created the invoice — used to bound how far back a sweep looks. */\n  createdAt: Date;\n}\n\n// ── Checkout / Portal (Provider-Hosted UI) ──────────────────────\n\nexport interface StandardBilling_CreateCheckoutSessionRequest {\n  providerCustomerId: string;\n  lineItems: Array<{\n    providerPriceId: string;\n    quantity?: number;\n  }>;\n  /** Checkout mode: 'subscription' for recurring, 'payment' for one-time */\n  mode: 'subscription' | 'payment';\n  successUrl: string;\n  cancelUrl: string;\n  /** Allow promotion codes in checkout */\n  allowPromotionCodes?: boolean;\n  /** Pre-fill promotion code */\n  providerPromotionCodeId?: string;\n  /** Trial period for subscriptions */\n  trialPeriodDays?: number;\n  /**\n   * Ask the provider to compute tax on this purchase (#408, 2026-09-08).\n   *\n   * Set from the application's `billing.tax.calculationMode`, which is PROVIDER_MANAGED or\n   * DISABLED — Wildo never calculates tax locally, so the only question a provider is asked is\n   * whether to calculate at all. A provider that cannot compute tax ignores this; one that can and\n   * is not configured for the customer's jurisdiction will say so at the call, which is the right\n   * place for that failure.\n   *\n   * Distinct from a price's `taxBehavior`, which says whether a displayed amount INCLUDES tax.\n   * That one has always reached the provider; this one decides whether tax is computed.\n   */\n  automaticTax?: boolean;\n  /**\n   * Require a payment method up front for a trial (#408, 2026-09-08).\n   *\n   * Set from the product's `behaviorPolicy.trial.requirePaymentMethod`, which was declared,\n   * labelled, rendered on billing screens and passed to no provider call — so a trial declared as\n   * requiring a card behaved identically to one that did not. Wonder Todos' enterprise plan\n   * (`true`) and professional plan (`false`) were indistinguishable at the provider.\n   *\n   * Two provider-side consequences follow and a connector should honour both: collect the payment\n   * method during checkout, and decide what happens if the trial ends without one.\n   */\n  requirePaymentMethodForTrial?: boolean;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCheckoutSessionResponse {\n  /** Redirect URL for the hosted checkout page */\n  url: string;\n  sessionId: string;\n}\n\nexport interface StandardBilling_CreateCustomerPortalSessionResponse {\n  /** Redirect URL for the customer portal */\n  url: string;\n}\n\n// ── Usage Reporting (METERED products via Billing Meter Events) ─\n\nexport interface StandardBilling_ReportUsageRequest {\n  /** Meter event name (corresponds to the meter's event_name) */\n  meterEventName: string;\n  /** Provider customer ID (maps to payload.stripe_customer_id in Stripe) */\n  providerCustomerId: string;\n  /** Usage value to report */\n  value: number;\n  /** Optional event timestamp */\n  timestamp?: Date;\n  /** Optional unique event identifier (for idempotency) */\n  identifier?: string;\n}\n\n// ── Promotions ──────────────────────────────────────────────────\n\nexport interface StandardBilling_CreateCouponRequest {\n  /** Discount amount in smallest currency unit (for fixed discounts) */\n  amountOff?: number;\n  /** Discount percentage (for percentage discounts) */\n  percentOff?: number;\n  currency?: string;\n  duration: 'once' | 'repeating' | 'forever';\n  durationInMonths?: number;\n  maxRedemptions?: number;\n  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CreateCouponResponse {\n  providerCouponId: string;\n}\n\nexport interface StandardBilling_CreatePromotionCodeResponse {\n  providerPromotionId: string;\n}\n\n/**\n * A percentage discount GIVEN to one subscription — a referral reward (#1802) — rather than redeemed by the\n * customer from a code.\n */\nexport interface StandardBilling_AddSubscriptionDiscountRequest {\n  /** Percentage taken off, 1–100. */\n  percentOff: number;\n  duration: 'once' | 'repeating' | 'forever';\n  /** Months, for a `repeating` discount. */\n  durationInMonths?: number;\n  /**\n   * Stable per grant. The adapter derives the provider coupon's identity and its idempotency keys from it, so\n   * a repeated call with the same key adds the discount once.\n   */\n  grantKey: string;\n  metadata?: Record<string, string>;\n}\n\n// ===============================================================\n// Standard Billing Interface\n// ===============================================================\n\n/**\n * Provider-agnostic billing interface.\n * Each billing provider (Stripe, Paddle, etc.) implements this interface\n * through a transformer that maps canonical operations to provider SDK calls.\n */\nexport interface StandardBilling_Interface {\n  // ── Customer (maps to BillingAccount) ──\n  createCustomer(request: StandardBilling_CreateCustomerRequest): Promise<StandardBilling_CreateCustomerResponse>;\n  updateCustomer(providerCustomerId: string, request: StandardBilling_UpdateCustomerRequest): Promise<void>;\n  /**\n   * Hard-delete the provider customer.\n   *\n   * ⚠️ NOT the subject-erasure path. Erasing a subject ANONYMIZES this customer (blank the personal\n   * fields, keep the record) because the financial history hanging off it — invoices, subscriptions,\n   * usage — is retained under a legal obligation and must stay attributable to its provider record.\n   * Deleting the customer would strand exactly the audit trail retention exists to preserve.\n   * Reserve this for a genuine account teardown with no retained history.\n   */\n  deleteCustomer(providerCustomerId: string): Promise<void>;\n\n  // ── Payment instruments ──\n  /**\n   * Stored payment instruments for a customer. Used by subject erasure to enumerate what must be\n   * detached; day-to-day management belongs in the provider-hosted portal.\n   */\n  listPaymentMethods(providerCustomerId: string): Promise<StandardBilling_PaymentMethodSummary[]>;\n  /**\n   * Detach an instrument from its customer. Detaching does NOT delete the instrument's transaction\n   * history at the provider — it stops future charges and unlinks it from the customer, which is\n   * what erasure needs and what the retained invoice record requires.\n   */\n  detachPaymentMethod(providerPaymentMethodId: string): Promise<void>;\n  /**\n   * Blank the personal data an instrument carries about whoever paid with it — the cardholder's name,\n   * email, phone and billing address — keeping the instrument itself (#869).\n   *\n   * Detaching does not do this: a detached instrument still exists at the provider with its billing\n   * details intact, and on Stripe it can no longer be edited once detached (\"You must save this\n   * PaymentMethod to a customer before you can update it\", measured 2026-09-25). So subject erasure\n   * calls this BEFORE {@link detachPaymentMethod}. A provider field that cannot be unset stays: Stripe\n   * refuses to clear `address.country`, which identifies nobody on its own.\n   *\n   * The card network data (brand, last four digits, expiry, fingerprint) is the instrument, not contact\n   * data, and stays with the retained transaction record it belongs to.\n   */\n  redactPaymentMethodBillingDetails(providerPaymentMethodId: string): Promise<void>;\n\n  // ── Product/Price sync (Wildo → Provider) ──\n  syncProduct(request: StandardBilling_SyncProductRequest): Promise<StandardBilling_SyncProductResponse>;\n  syncPrice(request: StandardBilling_SyncPriceRequest): Promise<StandardBilling_SyncPriceResponse>;\n  /**\n   * Whether the provider price a local price is LINKED to still carries the local terms (#1907): active, on the\n   * requested product, and equal in amount, currency, cadence, tiers, packaging and tax behaviour.\n   *\n   * A provider price is immutable, so a link made under an earlier amount convention — or before a catalogue edit —\n   * keeps charging the old amount unless something compares the two. The catalogue sync asks this of every linked\n   * price and re-syncs one that answers `false`. Answer `false` when the price cannot be read: the caller then\n   * creates a correct price rather than keeping a link nobody could check.\n   */\n  linkedPriceMatches(providerPriceId: string, request: StandardBilling_SyncPriceRequest): Promise<boolean>;\n\n  // ── Subscription lifecycle ──\n  // NOTE: User-initiated plan changes, cancellation, and payment method management\n  // should use createCustomerPortalSession() instead of calling these directly.\n  // These methods are for: initial checkout completion, backend-driven upgrades,\n  // admin-triggered changes, and webhook-driven updates.\n  createSubscription(request: StandardBilling_CreateSubscriptionRequest): Promise<StandardBilling_CreateSubscriptionResponse>;\n  updateSubscription(providerSubscriptionId: string, request: StandardBilling_UpdateSubscriptionRequest): Promise<StandardBilling_UpdateSubscriptionResponse>;\n  cancelSubscription(providerSubscriptionId: string, options?: StandardBilling_CancelSubscriptionOptions): Promise<void>;\n  pauseSubscription(providerSubscriptionId: string): Promise<void>;\n  /** Resume paused payment collection; does not undo a scheduled cancellation. */\n  resumeSubscription(providerSubscriptionId: string): Promise<void>;\n  /** Remove a pending period-end cancellation without changing collection or lifecycle status. */\n  removeScheduledCancellation(providerSubscriptionId: string, options?: StandardBilling_SubscriptionMutationOptions): Promise<void>;\n  /**\n   * Defer a plan change to the end of the current period (#1868). One deferred change at a time: the engine refuses a second\n   * while one is pending, and it is withdrawn (`releaseSubscriptionSchedule`) before another is made.\n   */\n  schedulePlanChange(providerSubscriptionId: string, request: StandardBilling_SchedulePlanChangeRequest): Promise<StandardBilling_SchedulePlanChangeResponse>;\n  /**\n   * Withdraw a schedule from its subscription, leaving the subscription running as it is now (#1868). Releasing a schedule that is\n   * already released succeeds: the state asked for holds — except with `onlyBeforeNextPhase`, where it succeeds only as a replay of the\n   * caller's own release and otherwise answers an INDETERMINATE failure, and the caller decides from what the provider bills.\n   */\n  releaseSubscriptionSchedule(providerScheduleId: string, options?: StandardBilling_ReleaseScheduleOptions): Promise<void>;\n  /**\n   * Classify an error thrown by `updateSubscription`, `cancelSubscription`, `removeScheduledCancellation`, `schedulePlanChange` or\n   * `releaseSubscriptionSchedule` (#535, D3).\n   *\n   * Must answer {@link StandardBilling_MutationErrorClass.INDETERMINATE} for anything the adapter cannot positively place\n   * — including an error the adapter itself threw AFTER the provider answered — because every other class licenses the\n   * caller to record that the change did not happen.\n   */\n  classifyMutationError(error: unknown): StandardBilling_MutationErrorClass;\n\n  // ── Read/sync (for reconciliation and upcoming cost preview) ──\n  /** On-demand retrieval for reconciliation (if webhook missed) */\n  retrieveSubscription(providerSubscriptionId: string): Promise<StandardBilling_SubscriptionData>;\n  /** Preview the upcoming invoice for an optional item change; the amount is not necessarily charged immediately. */\n  retrieveUpcomingInvoice(providerSubscriptionId: string, request?: StandardBilling_SubscriptionPreviewRequest): Promise<StandardBilling_InvoicePreview>;\n  /**\n   * Invoices the provider holds for one customer, newest first.\n   *\n   * The RECOVERY read for {@link StandardBilling_EventType.INVOICE_PAID} and its siblings. Wildo\n   * never creates an invoice — every local `invoiceRefs` row exists because a webhook arrived — so a\n   * delivery that is lost, or that arrives while the application is down and exhausts the provider's\n   * retries, leaves an invoice with no local trace and nothing that could notice. This is the only\n   * call that can find one.\n   *\n   * `limit` bounds one page and an adapter may cap it lower; the sweep asks for a recent window\n   * rather than the whole history, because an invoice older than the window has either been\n   * reconciled already or is a backlog no single tick should try to drain.\n   */\n  listInvoices(providerCustomerId: string, options?: { limit?: number }): Promise<StandardBilling_InvoiceData[]>;\n\n  // ── Provider-hosted UI (primary user-facing interactions) ──\n  /** Hosted checkout page — NO Stripe Elements needed, no PCI scope */\n  createCheckoutSession(request: StandardBilling_CreateCheckoutSessionRequest): Promise<StandardBilling_CreateCheckoutSessionResponse>;\n  /** Customer portal for: invoices, payment methods, billing address, cancel */\n  createCustomerPortalSession(providerCustomerId: string, returnUrl: string): Promise<StandardBilling_CreateCustomerPortalSessionResponse>;\n\n  // ── Usage reporting (for METERED products) ──\n  reportUsage(request: StandardBilling_ReportUsageRequest): Promise<void>;\n\n  // ── Webhooks ──\n  /** HTTP header name that carries the webhook signature (e.g., 'stripe-signature') */\n  readonly webhookSignatureHeaderName: string;\n  verifyWebhookSignature(payload: string | Uint8Array, signature: string, secret: string): boolean;\n  /** Parse a raw webhook payload into a canonical event. Returns null for unknown/unhandled event types. */\n  parseWebhookEvent(payload: string | Uint8Array): StandardBilling_WebhookEvent | null;\n\n  // ── Promotions (synced to provider) ──\n  createCoupon(request: StandardBilling_CreateCouponRequest): Promise<StandardBilling_CreateCouponResponse>;\n  createPromotionCode(providerCouponId: string, code: string): Promise<StandardBilling_CreatePromotionCodeResponse>;\n  /**\n   * Add a discount to a subscription, KEEPING any discount it already carries (#1802). Idempotent on\n   * `request.grantKey`: a second call with the same key finds its discount already applied and adds nothing.\n   */\n  addSubscriptionDiscount(providerSubscriptionId: string, request: StandardBilling_AddSubscriptionDiscountRequest): Promise<void>;\n}\n"]}

package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { ExternalProvider_ExchangeProtocol_Kind } from "../core/commons.external-connectors-models.schemas";
+/**
+ * The content-safety operation vocabulary — disjoint from every other protocol's operation keys, so a key's membership
+ * decides its protocol without inspection.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum ContentSafetyProvider_OperationKey {
+    /** Documents (third-party text entering a prompt) → whether each carries an injection attack. */
+    SCREEN_PROMPT_INJECTION = "contentSafety.screenPromptInjection",
+    /** Text a model wrote → how severe it is in each harm category the caller asks about. */
+    MODERATE_OUTPUT = "contentSafety.moderateOutput"
+}
+/**
+ * A harm category output moderation judges. The categories every major moderation vendor assesses; a vendor that
+ * assesses fewer declares which (`assessedCategories`), and an agent asking for one its provider cannot assess is
+ * refused at configuration rather than silently unjudged.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum ContentSafety_HarmCategory {
+    /** Attacks on, or discriminatory language about, a person or a group for who they are. */
+    HATE = "hate",
+    /** Sexual content. */
+    SEXUAL = "sexual",
+    /** Violence: threats, its glorification, instructions for it. */
+    VIOLENCE = "violence",
+    /** Self-harm and suicide: its encouragement, instructions for it. */
+    SELF_HARM = "self_harm"
+}
+/**
+ * How severe a text is in one harm category, from SAFE to HIGH. ORDERED: {@link contentSafetyHarmSeverityRank} gives
+ * each its rank, and an agent's policy blocks at a severity "or above".
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum ContentSafety_HarmSeverity {
+    /** Nothing harmful in this category (it may still name the subject, in a neutral context). */
+    SAFE = "safe",
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high"
+}
+/**
+ * The rank of a severity, SAFE = 0 to HIGH = 3, for comparing two severities.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare function contentSafetyHarmSeverityRank(severity: ContentSafety_HarmSeverity): number;
+/** One category's verdict, as a provider's parser returns it and the audit trail records it. */
+export declare const ContentSafety_HarmCategoryVerdictSchema: z.ZodObject<{
+    category: z.ZodEnum<typeof ContentSafety_HarmCategory>;
+    severity: z.ZodEnum<typeof ContentSafety_HarmSeverity>;
+}, z.core.$strip>;
+export type ContentSafety_HarmCategoryVerdict = z.infer<typeof ContentSafety_HarmCategoryVerdictSchema>;
+/**
+ * What a provider's `parseModerationResponse` returns: a severity for each category it was asked about, or a refusal.
+ * A category asked about and missing from the answer is read by the engine as "not moderated", never as SAFE. A
+ * refusal's `message` is operator-facing and MUST NOT contain the response body or the text: it reaches logs.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export type ContentSafety_ProviderModeration = {
+    moderated: true;
+    categories: readonly ContentSafety_HarmCategoryVerdict[];
+} | {
+    moderated: false;
+    /** Operator-facing; MUST NOT contain the response body or the text. */
+    message: string;
+};
+/**
+ * How much text one moderation request may carry, as the vendor documents it. The engine splits a longer text and
+ * judges every part, so a provider never receives a request its vendor would refuse for size. Measured in UTF-16 code
+ * units, as {@link ContentSafety_PromptInjectionLimitsSchema} is.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare const ContentSafety_OutputModerationLimitsSchema: z.ZodObject<{
+    maxCharactersPerRequest: z.ZodNumber;
+}, z.core.$strip>;
+export type ContentSafety_OutputModerationLimits = z.infer<typeof ContentSafety_OutputModerationLimitsSchema>;
+/**
+ * What a SCREENING concluded, as the engine reads a provider's verdicts (#2292): three outcomes, and only CLEAN releases
+ * the text. The content-safety protocol's own outcome vocabulary — the decision the agent runtime, the autonomous turn
+ * and the audit and evidence layers all name — so it lives with the verdict shapes it summarises.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum ContentSafetyScreeningOutcome {
+    /** Every document was screened and none was flagged. */
+    CLEAN = "clean",
+    /** A document was flagged as carrying a prompt-injection attack. */
+    ATTACK_DETECTED = "attack_detected",
+    /** The text was not (fully) screened: no answer, a refusal, a defect in the provider's functions, or too large. */
+    NOT_SCREENED = "not_screened"
+}
+/**
+ * What a MODERATION concluded (#2292 Phase 3). A caller withholds what was NOT_MODERATED, and applies its own policy to the
+ * severities of what was MODERATED.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum ContentSafetyModerationOutcome {
+    /** Every part of the text was judged in every category asked about. */
+    MODERATED = "moderated",
+    /** The text was not (fully) judged: no answer, a refusal, a category missing from an answer, a defect, or too large. */
+    NOT_MODERATED = "not_moderated"
+}
+/**
+ * What a provider's `parseScreenResponse` returns: one verdict per document sent, in the order sent, or a refusal.
+ *
+ * There is ONE failure class and so no failure vocabulary. Extraction needs two because one of them (an unreadable
+ * document) changes what the caller does with the input; here every failure means the same thing to the caller — the
+ * text was not screened — and the engine withholds it whatever the reason (fail closed). A refusal's `message` is
+ * operator-facing and MUST NOT contain the response body or any document: it reaches logs, and a vendor error body can
+ * echo request content.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export type ContentSafety_ProviderScreening = {
+    screened: true;
+    /** One per document sent, in the order sent. A count that differs from the documents sent is refused by the engine. */
+    documents: readonly {
+        readonly attackDetected: boolean;
+    }[];
+} | {
+    screened: false;
+    /** Operator-facing; MUST NOT contain the response body or a document. */
+    message: string;
+};
+/**
+ * How much one screening request may carry, as the vendor documents it. The engine splits a long text into documents no
+ * longer than `maxCharactersPerRequest` and batches them under both limits, so a provider never receives a request its
+ * vendor would refuse for size — a refusal the engine would have to read as "not screened" and withhold. Lengths are
+ * measured in UTF-16 code units, never fewer than code points, so a limit stated in characters holds either way.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare const ContentSafety_PromptInjectionLimitsSchema: z.ZodObject<{
+    maxDocumentsPerRequest: z.ZodNumber;
+    maxCharactersPerRequest: z.ZodNumber;
+}, z.core.$strip>;
+export type ContentSafety_PromptInjectionLimits = z.infer<typeof ContentSafety_PromptInjectionLimitsSchema>;
+export declare const ContentSafetyProvider_ExecutionTransportMetadataSchema: z.ZodObject<{
+    protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.CONTENT_SAFETY_PROVIDER>;
+    providerRef: z.ZodString;
+}, z.core.$strip>;
+export type ContentSafetyProvider_ExecutionTransportMetadata = z.infer<typeof ContentSafetyProvider_ExecutionTransportMetadataSchema>;
+//# sourceMappingURL=content-safety.external-connectors-models.schemas.d.ts.map

package/dist/esm/protocols/content-safety.external-connectors-models.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-safety.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/content-safety.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACL,sCAAsC,EACrC,MAAM,oDAAoD,CAAA;AAwC7D;;;;;GAKG;AACH,oBAAY,kCAAkC;IAC5C,iGAAiG;IACjG,uBAAuB,wCAAwC;IAC/D,yFAAyF;IACzF,eAAe,iCAAiC;CACjD;AAsBD;;;;;;GAMG;AACH,oBAAY,0BAA0B;IACpC,0FAA0F;IAC1F,IAAI,SAAS;IACb,sBAAsB;IACtB,MAAM,WAAW;IACjB,iEAAiE;IACjE,QAAQ,aAAa;IACrB,qEAAqE;IACrE,SAAS,cAAc;CACxB;AAED;;;;;GAKG;AACH,oBAAY,0BAA0B;IACpC,8FAA8F;IAC9F,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAUD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,0BAA0B,GAAG,MAAM,CAE1F;AAED,gGAAgG;AAChG,eAAO,MAAM,uCAAuC;;;iBAGlD,CAAA;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAA;AAEvG;;;;;;GAMG;AACH,MAAM,MAAM,gCAAgC,GACxC;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,SAAS,iCAAiC,EAAE,CAAC;CAC1D,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;GAMG;AACH,eAAO,MAAM,0CAA0C;;iBAGrD,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAA;AAE7G;;;;;;GAMG;AACH,oBAAY,6BAA6B;IACvC,wDAAwD;IACxD,KAAK,UAAU;IACf,oEAAoE;IACpE,eAAe,oBAAoB;IACnC,mHAAmH;IACnH,YAAY,iBAAiB;CAC9B;AAED;;;;;GAKG;AACH,oBAAY,8BAA8B;IACxC,uEAAuE;IACvE,SAAS,cAAc;IACvB,wHAAwH;IACxH,aAAa,kBAAkB;CAChC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,+BAA+B,GACvC;IACE,QAAQ,EAAE,IAAI,CAAC;IACf,uHAAuH;IACvH,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC5D,GACD;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;GAOG;AACH,eAAO,MAAM,yCAAyC;;;iBAKpD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;AAE5G,eAAO,MAAM,sDAAsD;;;iBAGjE,CAAC;AACH,MAAM,MAAM,gDAAgD,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sDAAsD,CAAC,CAAC"}

package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import { ExternalProvider_ExchangeProtocol_Kind, } from "../core/commons.external-connectors-models.schemas.js";
+//===============================================================
+// Content Safety Provider (#2292)
+// --------
+// Text → a classifier's verdict about it. Serves the content guardrails an agent declares
+// (`FlowsActors_Agent.contentGuardrails`): first PROMPT-INJECTION SCREENING of the third-party
+// content an agent reads (what its tools return, an inbound delivery that starts its turn), before its model reads it.
+//
+// ## What is screened, and why it is shaped this way
+//
+// Every vendor that publishes a prompt-attack API separates the same two inputs: the prompt the
+// person driving the conversation wrote, and DOCUMENTS — content somebody else wrote that reaches
+// the model as context (a record, a retrieved passage, a web page, an email). An instruction hidden
+// in a document is an INDIRECT injection: the person never wrote it and the model may still obey it.
+// Azure Prompt Shields takes `userPrompt` and `documents[]` and answers `attackDetected` per item;
+// Bedrock's ApplyGuardrail tags content and its `PROMPT_ATTACK` filter answers per assessment.
+// The engine screens DOCUMENTS: tool results and an inbound delivery's content are what an agent reads from other
+// people.
+//
+// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/quickstart-jailbreak —
+// request `userPrompt` / `documents`, response `documentsAnalysis[].attackDetected` (fetched 2026-10-12).
+// spec-cite: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use-independent-api.html —
+// `contentPolicy.filters[].type` includes `PROMPT_ATTACK` (fetched 2026-10-12).
+//
+// ## Deliberately its own protocol kind and its own engine slot
+//
+// The DOCUMENT_EXTRACTION_PROVIDER argument, unchanged: a new `runtimeContract.kind` fails
+// COMPILATION at every switch over the union, where a new operation on an existing kind fails
+// silently; and `EngineCapability.AI_CONTENT_SAFETY` lets an application choose its classifier
+// independently of its chat model — the vendor that screens a model's input should not be decided
+// by which vendor answers it.
+//
+// ## The provider never receives a personal value in clear
+//
+// The engine screens the MODEL-SIDE text: what the model is about to read, after the agent's
+// personal-data treatment has replaced every personal field with a placeholder. So a classifier
+// vendor is a recipient of exactly what the model vendor receives, and no more.
+//===============================================================
+/**
+ * The content-safety operation vocabulary — disjoint from every other protocol's operation keys, so a key's membership
+ * decides its protocol without inspection.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export var ContentSafetyProvider_OperationKey;
+(function (ContentSafetyProvider_OperationKey) {
+    /** Documents (third-party text entering a prompt) → whether each carries an injection attack. */
+    ContentSafetyProvider_OperationKey["SCREEN_PROMPT_INJECTION"] = "contentSafety.screenPromptInjection";
+    /** Text a model wrote → how severe it is in each harm category the caller asks about. */
+    ContentSafetyProvider_OperationKey["MODERATE_OUTPUT"] = "contentSafety.moderateOutput";
+})(ContentSafetyProvider_OperationKey || (ContentSafetyProvider_OperationKey = {}));
+//===============================================================
+// Output moderation (#2292 Phase 3)
+// --------
+// What a model WROTE, judged per harm category before anyone reads it, stores it or sends it.
+//
+// The engine's vocabulary is the set of harm categories the vendors publish in common, with the severity scale they
+// share. Azure AI Content Safety `text:analyze` answers `categoriesAnalysis[].severity` for `Hate`, `Sexual`,
+// `SelfHarm` and `Violence`, on the scale 0 / 2 / 4 / 6 (`outputType: "FourSeverityLevels"`) that its guardrails
+// name Safe / Low / Medium / High. Bedrock ApplyGuardrail, called with `source: "OUTPUT"`, answers each content
+// filter (`HATE`, `SEXUAL`, `VIOLENCE`, …) with a `confidence` of NONE / LOW / MEDIUM / HIGH. A provider maps its
+// vendor's answer onto these two vocabularies and declares which categories it can assess.
+//
+// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/quickstart-text — request `text`,
+// `categories`, `outputType`; response `categoriesAnalysis[].category` / `.severity` (fetched 2026-10-12).
+// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/region-availability — "Analyze text
+// API: Default maximum length: 10K characters" (fetched 2026-10-12).
+// spec-cite: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use-independent-api.html — `source`
+// INPUT / OUTPUT, `contentPolicy.filters[].confidence` NONE / LOW / MEDIUM / HIGH (fetched 2026-10-12).
+//===============================================================
+/**
+ * A harm category output moderation judges. The categories every major moderation vendor assesses; a vendor that
+ * assesses fewer declares which (`assessedCategories`), and an agent asking for one its provider cannot assess is
+ * refused at configuration rather than silently unjudged.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export var ContentSafety_HarmCategory;
+(function (ContentSafety_HarmCategory) {
+    /** Attacks on, or discriminatory language about, a person or a group for who they are. */
+    ContentSafety_HarmCategory["HATE"] = "hate";
+    /** Sexual content. */
+    ContentSafety_HarmCategory["SEXUAL"] = "sexual";
+    /** Violence: threats, its glorification, instructions for it. */
+    ContentSafety_HarmCategory["VIOLENCE"] = "violence";
+    /** Self-harm and suicide: its encouragement, instructions for it. */
+    ContentSafety_HarmCategory["SELF_HARM"] = "self_harm";
+})(ContentSafety_HarmCategory || (ContentSafety_HarmCategory = {}));
+/**
+ * How severe a text is in one harm category, from SAFE to HIGH. ORDERED: {@link contentSafetyHarmSeverityRank} gives
+ * each its rank, and an agent's policy blocks at a severity "or above".
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export var ContentSafety_HarmSeverity;
+(function (ContentSafety_HarmSeverity) {
+    /** Nothing harmful in this category (it may still name the subject, in a neutral context). */
+    ContentSafety_HarmSeverity["SAFE"] = "safe";
+    ContentSafety_HarmSeverity["LOW"] = "low";
+    ContentSafety_HarmSeverity["MEDIUM"] = "medium";
+    ContentSafety_HarmSeverity["HIGH"] = "high";
+})(ContentSafety_HarmSeverity || (ContentSafety_HarmSeverity = {}));
+/** The rank of each severity, SAFE lowest. The one place the order is written down. */
+const HARM_SEVERITY_RANK = {
+    [ContentSafety_HarmSeverity.SAFE]: 0,
+    [ContentSafety_HarmSeverity.LOW]: 1,
+    [ContentSafety_HarmSeverity.MEDIUM]: 2,
+    [ContentSafety_HarmSeverity.HIGH]: 3,
+};
+/**
+ * The rank of a severity, SAFE = 0 to HIGH = 3, for comparing two severities.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export function contentSafetyHarmSeverityRank(severity) {
+    return HARM_SEVERITY_RANK[severity];
+}
+/** One category's verdict, as a provider's parser returns it and the audit trail records it. */
+export const ContentSafety_HarmCategoryVerdictSchema = z.object({
+    category: z.enum(ContentSafety_HarmCategory),
+    severity: z.enum(ContentSafety_HarmSeverity),
+});
+/**
+ * How much text one moderation request may carry, as the vendor documents it. The engine splits a longer text and
+ * judges every part, so a provider never receives a request its vendor would refuse for size. Measured in UTF-16 code
+ * units, as {@link ContentSafety_PromptInjectionLimitsSchema} is.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export const ContentSafety_OutputModerationLimitsSchema = z.object({
+    /** Most characters one request may carry. */
+    maxCharactersPerRequest: z.number().int().positive(),
+});
+/**
+ * What a SCREENING concluded, as the engine reads a provider's verdicts (#2292): three outcomes, and only CLEAN releases
+ * the text. The content-safety protocol's own outcome vocabulary — the decision the agent runtime, the autonomous turn
+ * and the audit and evidence layers all name — so it lives with the verdict shapes it summarises.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export var ContentSafetyScreeningOutcome;
+(function (ContentSafetyScreeningOutcome) {
+    /** Every document was screened and none was flagged. */
+    ContentSafetyScreeningOutcome["CLEAN"] = "clean";
+    /** A document was flagged as carrying a prompt-injection attack. */
+    ContentSafetyScreeningOutcome["ATTACK_DETECTED"] = "attack_detected";
+    /** The text was not (fully) screened: no answer, a refusal, a defect in the provider's functions, or too large. */
+    ContentSafetyScreeningOutcome["NOT_SCREENED"] = "not_screened";
+})(ContentSafetyScreeningOutcome || (ContentSafetyScreeningOutcome = {}));
+/**
+ * What a MODERATION concluded (#2292 Phase 3). A caller withholds what was NOT_MODERATED, and applies its own policy to the
+ * severities of what was MODERATED.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export var ContentSafetyModerationOutcome;
+(function (ContentSafetyModerationOutcome) {
+    /** Every part of the text was judged in every category asked about. */
+    ContentSafetyModerationOutcome["MODERATED"] = "moderated";
+    /** The text was not (fully) judged: no answer, a refusal, a category missing from an answer, a defect, or too large. */
+    ContentSafetyModerationOutcome["NOT_MODERATED"] = "not_moderated";
+})(ContentSafetyModerationOutcome || (ContentSafetyModerationOutcome = {}));
+/**
+ * How much one screening request may carry, as the vendor documents it. The engine splits a long text into documents no
+ * longer than `maxCharactersPerRequest` and batches them under both limits, so a provider never receives a request its
+ * vendor would refuse for size — a refusal the engine would have to read as "not screened" and withhold. Lengths are
+ * measured in UTF-16 code units, never fewer than code points, so a limit stated in characters holds either way.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export const ContentSafety_PromptInjectionLimitsSchema = z.object({
+    /** Most documents one request may carry. */
+    maxDocumentsPerRequest: z.number().int().positive(),
+    /** Most characters the documents of one request may carry together. */
+    maxCharactersPerRequest: z.number().int().positive(),
+});
+export const ContentSafetyProvider_ExecutionTransportMetadataSchema = z.object({
+    protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.CONTENT_SAFETY_PROVIDER),
+    providerRef: z.string(),
+});
+//# sourceMappingURL=content-safety.external-connectors-models.schemas.js.map

package/dist/esm/protocols/content-safety.external-connectors-models.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-safety.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/content-safety.external-connectors-models.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\"\nimport {\n  ExternalProvider_ExchangeProtocol_Kind,\n  } from \"../core/commons.external-connectors-models.schemas\"\n\n//===============================================================\n// Content Safety Provider (#2292)\n// --------\n// Text → a classifier's verdict about it. Serves the content guardrails an agent declares\n// (`FlowsActors_Agent.contentGuardrails`): first PROMPT-INJECTION SCREENING of the third-party\n// content an agent reads (what its tools return, an inbound delivery that starts its turn), before its model reads it.\n//\n// ## What is screened, and why it is shaped this way\n//\n// Every vendor that publishes a prompt-attack API separates the same two inputs: the prompt the\n// person driving the conversation wrote, and DOCUMENTS — content somebody else wrote that reaches\n// the model as context (a record, a retrieved passage, a web page, an email). An instruction hidden\n// in a document is an INDIRECT injection: the person never wrote it and the model may still obey it.\n// Azure Prompt Shields takes `userPrompt` and `documents[]` and answers `attackDetected` per item;\n// Bedrock's ApplyGuardrail tags content and its `PROMPT_ATTACK` filter answers per assessment.\n// The engine screens DOCUMENTS: tool results and an inbound delivery's content are what an agent reads from other\n// people.\n//\n// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/quickstart-jailbreak —\n// request `userPrompt` / `documents`, response `documentsAnalysis[].attackDetected` (fetched 2026-10-12).\n// spec-cite: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use-independent-api.html —\n// `contentPolicy.filters[].type` includes `PROMPT_ATTACK` (fetched 2026-10-12).\n//\n// ## Deliberately its own protocol kind and its own engine slot\n//\n// The DOCUMENT_EXTRACTION_PROVIDER argument, unchanged: a new `runtimeContract.kind` fails\n// COMPILATION at every switch over the union, where a new operation on an existing kind fails\n// silently; and `EngineCapability.AI_CONTENT_SAFETY` lets an application choose its classifier\n// independently of its chat model — the vendor that screens a model's input should not be decided\n// by which vendor answers it.\n//\n// ## The provider never receives a personal value in clear\n//\n// The engine screens the MODEL-SIDE text: what the model is about to read, after the agent's\n// personal-data treatment has replaced every personal field with a placeholder. So a classifier\n// vendor is a recipient of exactly what the model vendor receives, and no more.\n//===============================================================\n\n/**\n * The content-safety operation vocabulary — disjoint from every other protocol's operation keys, so a key's membership\n * decides its protocol without inspection.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum ContentSafetyProvider_OperationKey {\n  /** Documents (third-party text entering a prompt) → whether each carries an injection attack. */\n  SCREEN_PROMPT_INJECTION = \"contentSafety.screenPromptInjection\",\n  /** Text a model wrote → how severe it is in each harm category the caller asks about. */\n  MODERATE_OUTPUT = \"contentSafety.moderateOutput\",\n}\n\n//===============================================================\n// Output moderation (#2292 Phase 3)\n// --------\n// What a model WROTE, judged per harm category before anyone reads it, stores it or sends it.\n//\n// The engine's vocabulary is the set of harm categories the vendors publish in common, with the severity scale they\n// share. Azure AI Content Safety `text:analyze` answers `categoriesAnalysis[].severity` for `Hate`, `Sexual`,\n// `SelfHarm` and `Violence`, on the scale 0 / 2 / 4 / 6 (`outputType: \"FourSeverityLevels\"`) that its guardrails\n// name Safe / Low / Medium / High. Bedrock ApplyGuardrail, called with `source: \"OUTPUT\"`, answers each content\n// filter (`HATE`, `SEXUAL`, `VIOLENCE`, …) with a `confidence` of NONE / LOW / MEDIUM / HIGH. A provider maps its\n// vendor's answer onto these two vocabularies and declares which categories it can assess.\n//\n// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/quickstart-text — request `text`,\n// `categories`, `outputType`; response `categoriesAnalysis[].category` / `.severity` (fetched 2026-10-12).\n// spec-cite: https://learn.microsoft.com/en-us/azure/ai-services/content-safety/region-availability — \"Analyze text\n// API: Default maximum length: 10K characters\" (fetched 2026-10-12).\n// spec-cite: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use-independent-api.html — `source`\n// INPUT / OUTPUT, `contentPolicy.filters[].confidence` NONE / LOW / MEDIUM / HIGH (fetched 2026-10-12).\n//===============================================================\n\n/**\n * A harm category output moderation judges. The categories every major moderation vendor assesses; a vendor that\n * assesses fewer declares which (`assessedCategories`), and an agent asking for one its provider cannot assess is\n * refused at configuration rather than silently unjudged.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum ContentSafety_HarmCategory {\n  /** Attacks on, or discriminatory language about, a person or a group for who they are. */\n  HATE = \"hate\",\n  /** Sexual content. */\n  SEXUAL = \"sexual\",\n  /** Violence: threats, its glorification, instructions for it. */\n  VIOLENCE = \"violence\",\n  /** Self-harm and suicide: its encouragement, instructions for it. */\n  SELF_HARM = \"self_harm\",\n}\n\n/**\n * How severe a text is in one harm category, from SAFE to HIGH. ORDERED: {@link contentSafetyHarmSeverityRank} gives\n * each its rank, and an agent's policy blocks at a severity \"or above\".\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum ContentSafety_HarmSeverity {\n  /** Nothing harmful in this category (it may still name the subject, in a neutral context). */\n  SAFE = \"safe\",\n  LOW = \"low\",\n  MEDIUM = \"medium\",\n  HIGH = \"high\",\n}\n\n/** The rank of each severity, SAFE lowest. The one place the order is written down. */\nconst HARM_SEVERITY_RANK: Readonly<Record<ContentSafety_HarmSeverity, number>> = {\n  [ContentSafety_HarmSeverity.SAFE]: 0,\n  [ContentSafety_HarmSeverity.LOW]: 1,\n  [ContentSafety_HarmSeverity.MEDIUM]: 2,\n  [ContentSafety_HarmSeverity.HIGH]: 3,\n}\n\n/**\n * The rank of a severity, SAFE = 0 to HIGH = 3, for comparing two severities.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport function contentSafetyHarmSeverityRank(severity: ContentSafety_HarmSeverity): number {\n  return HARM_SEVERITY_RANK[severity]\n}\n\n/** One category's verdict, as a provider's parser returns it and the audit trail records it. */\nexport const ContentSafety_HarmCategoryVerdictSchema = z.object({\n  category: z.enum(ContentSafety_HarmCategory),\n  severity: z.enum(ContentSafety_HarmSeverity),\n})\nexport type ContentSafety_HarmCategoryVerdict = z.infer<typeof ContentSafety_HarmCategoryVerdictSchema>\n\n/**\n * What a provider's `parseModerationResponse` returns: a severity for each category it was asked about, or a refusal.\n * A category asked about and missing from the answer is read by the engine as \"not moderated\", never as SAFE. A\n * refusal's `message` is operator-facing and MUST NOT contain the response body or the text: it reaches logs.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport type ContentSafety_ProviderModeration =\n  | {\n      moderated: true;\n      categories: readonly ContentSafety_HarmCategoryVerdict[];\n    }\n  | {\n      moderated: false;\n      /** Operator-facing; MUST NOT contain the response body or the text. */\n      message: string;\n    };\n\n/**\n * How much text one moderation request may carry, as the vendor documents it. The engine splits a longer text and\n * judges every part, so a provider never receives a request its vendor would refuse for size. Measured in UTF-16 code\n * units, as {@link ContentSafety_PromptInjectionLimitsSchema} is.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport const ContentSafety_OutputModerationLimitsSchema = z.object({\n  /** Most characters one request may carry. */\n  maxCharactersPerRequest: z.number().int().positive(),\n})\nexport type ContentSafety_OutputModerationLimits = z.infer<typeof ContentSafety_OutputModerationLimitsSchema>\n\n/**\n * What a SCREENING concluded, as the engine reads a provider's verdicts (#2292): three outcomes, and only CLEAN releases\n * the text. The content-safety protocol's own outcome vocabulary — the decision the agent runtime, the autonomous turn\n * and the audit and evidence layers all name — so it lives with the verdict shapes it summarises.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum ContentSafetyScreeningOutcome {\n  /** Every document was screened and none was flagged. */\n  CLEAN = \"clean\",\n  /** A document was flagged as carrying a prompt-injection attack. */\n  ATTACK_DETECTED = \"attack_detected\",\n  /** The text was not (fully) screened: no answer, a refusal, a defect in the provider's functions, or too large. */\n  NOT_SCREENED = \"not_screened\",\n}\n\n/**\n * What a MODERATION concluded (#2292 Phase 3). A caller withholds what was NOT_MODERATED, and applies its own policy to the\n * severities of what was MODERATED.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum ContentSafetyModerationOutcome {\n  /** Every part of the text was judged in every category asked about. */\n  MODERATED = \"moderated\",\n  /** The text was not (fully) judged: no answer, a refusal, a category missing from an answer, a defect, or too large. */\n  NOT_MODERATED = \"not_moderated\",\n}\n\n/**\n * What a provider's `parseScreenResponse` returns: one verdict per document sent, in the order sent, or a refusal.\n *\n * There is ONE failure class and so no failure vocabulary. Extraction needs two because one of them (an unreadable\n * document) changes what the caller does with the input; here every failure means the same thing to the caller — the\n * text was not screened — and the engine withholds it whatever the reason (fail closed). A refusal's `message` is\n * operator-facing and MUST NOT contain the response body or any document: it reaches logs, and a vendor error body can\n * echo request content.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport type ContentSafety_ProviderScreening =\n  | {\n      screened: true;\n      /** One per document sent, in the order sent. A count that differs from the documents sent is refused by the engine. */\n      documents: readonly { readonly attackDetected: boolean }[];\n    }\n  | {\n      screened: false;\n      /** Operator-facing; MUST NOT contain the response body or a document. */\n      message: string;\n    };\n\n/**\n * How much one screening request may carry, as the vendor documents it. The engine splits a long text into documents no\n * longer than `maxCharactersPerRequest` and batches them under both limits, so a provider never receives a request its\n * vendor would refuse for size — a refusal the engine would have to read as \"not screened\" and withhold. Lengths are\n * measured in UTF-16 code units, never fewer than code points, so a limit stated in characters holds either way.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport const ContentSafety_PromptInjectionLimitsSchema = z.object({\n  /** Most documents one request may carry. */\n  maxDocumentsPerRequest: z.number().int().positive(),\n  /** Most characters the documents of one request may carry together. */\n  maxCharactersPerRequest: z.number().int().positive(),\n});\nexport type ContentSafety_PromptInjectionLimits = z.infer<typeof ContentSafety_PromptInjectionLimitsSchema>;\n\nexport const ContentSafetyProvider_ExecutionTransportMetadataSchema = z.object({\n  protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.CONTENT_SAFETY_PROVIDER),\n  providerRef: z.string(),\n});\nexport type ContentSafetyProvider_ExecutionTransportMetadata = z.infer<typeof ContentSafetyProvider_ExecutionTransportMetadataSchema>;\n"]}