@wildo-ai/external-connectors-models 1.1.3 → 1.1.5

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

@@ -69,6 +69,47 @@ export var ProrationBehavior;
     /** Prorate and invoice the difference IMMEDIATELY rather than at the next cycle. */
     ProrationBehavior["ALWAYS_INVOICE"] = "always_invoice";
 })(ProrationBehavior || (ProrationBehavior = {}));
+/**
+ * How the provider treats a subscription change whose resulting payment does not succeed (#535, decision D6).
+ *
+ * Wildo applies a confirmed plan change IMMEDIATELY: entitlements move at local completion, and a failed proration
+ * payment moves the subscription to `past_due` through the webhook projection, where dunning owns what happens next.
+ * The value is DECLARED on every engine-issued change rather than left to the provider's default, so a change of that
+ * default can never silently change the semantics.
+ *
+ * Deliberately a one-member vocabulary. `pending_if_incomplete` (apply only after payment, expire after 23 h) was
+ * weighed and rejected in #535; add a member only with a decision that changes D6.
+ *
+ * spec-cite: https://docs.stripe.com/api/subscriptions/update — `payment_behavior`; the value equals Stripe's wire value,
+ * so the Stripe adapter passes it untranslated, as it does `ProrationBehavior`.
+ */
+export var StandardBilling_SubscriptionPaymentBehavior;
+(function (StandardBilling_SubscriptionPaymentBehavior) {
+    /** Apply the change now; an unpaid resulting invoice leaves the subscription `past_due`. */
+    StandardBilling_SubscriptionPaymentBehavior["ALLOW_INCOMPLETE"] = "allow_incomplete";
+})(StandardBilling_SubscriptionPaymentBehavior || (StandardBilling_SubscriptionPaymentBehavior = {}));
+/**
+ * What a FAILED provider mutation tells the caller about whether the change took effect (#535, decision D3).
+ *
+ * The distinction that matters is not the HTTP status but what may be recorded next: a conclusive refusal and a request
+ * that never executed may both be recorded as "no effect", while an indeterminate outcome must NEVER be — the provider
+ * may have applied it, or may still apply it. Only the adapter can read its vendor's error shape, so each adapter
+ * classifies (`StandardBilling_Interface.classifyMutationError`) and the engine decides on the class alone.
+ *
+ * spec-cite: https://docs.stripe.com/error-low-level — "Network errors", "Server errors", "Content errors" (the
+ * source of the classes for the Stripe adapter; other adapters map their own vendor's equivalents).
+ */
+export var StandardBilling_MutationErrorClass;
+(function (StandardBilling_MutationErrorClass) {
+    /** The provider evaluated the request and refused it (e.g. a declined card, a missing object). No effect. */
+    StandardBilling_MutationErrorClass["CONCLUSIVE_REJECTION"] = "conclusive_rejection";
+    /** Refused before execution (rate limit, authentication). No effect; a later attempt must use a NEW idempotency key. */
+    StandardBilling_MutationErrorClass["NOT_EXECUTED"] = "not_executed";
+    /** Another request with the same idempotency key is still being processed. The outcome is not known yet. */
+    StandardBilling_MutationErrorClass["IN_FLIGHT_CONFLICT"] = "in_flight_conflict";
+    /** Timeout, connection loss, server error, or a failure after the provider answered. The change may have applied. */
+    StandardBilling_MutationErrorClass["INDETERMINATE"] = "indeterminate";
+})(StandardBilling_MutationErrorClass || (StandardBilling_MutationErrorClass = {}));
 /**
  * Subscription status values (maps to Stripe subscription statuses).
  */
@@ -150,4 +191,4 @@ export var StandardBilling_EventType;
     StandardBilling_EventType["PAYMENT_METHOD_ATTACHED"] = "payment_method.attached";
     StandardBilling_EventType["PAYMENT_METHOD_DETACHED"] = "payment_method.detached";
 })(StandardBilling_EventType || (StandardBilling_EventType = {}));
-//# sourceMappingURL=billing.standard-interface.schemas.js.map
+//# sourceMappingURL=billing.standard-interface.schemas.js.map

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":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kEAAkE;AAClE,yEAAyE;AACzE,kEAAkE;AAElE;;GAEG;AACH,MAAM,CAAN,IAAY,YASX;AATD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,qCAAqB,CAAA;IACrB,+CAA+C;IAC/C,iCAAiB,CAAA;IACjB,mDAAmD;IACnD,uCAAuB,CAAA;IACvB,mCAAmC;IACnC,mCAAmB,CAAA;AACrB,CAAC,EATW,YAAY,KAAZ,YAAY,QASvB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,eAGX;AAHD,WAAY,eAAe;IACzB,kCAAe,CAAA;IACf,gCAAa,CAAA;AACf,CAAC,EAHW,eAAe,KAAf,eAAe,QAG1B;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,mDAAmD;IACnD,yCAAuB,CAAA;IACvB,2CAA2C;IAC3C,yCAAuB,CAAA;AACzB,CAAC,EALW,cAAc,KAAd,cAAc,QAKzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,iBAOX;AAPD,WAAY,iBAAiB;IAC3B,6FAA6F;IAC7F,4DAAuC,CAAA;IACvC,2FAA2F;IAC3F,kCAAa,CAAA;IACb,oFAAoF;IACpF,sDAAiC,CAAA;AACnC,CAAC,EAPW,iBAAiB,KAAjB,iBAAiB,QAO5B;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,kBAUX;AAVD,WAAY,kBAAkB;IAC5B,uCAAiB,CAAA;IACjB,2CAAqB,CAAA;IACrB,uCAAiB,CAAA;IACjB,6CAAuB,CAAA;IACvB,8DAA8D;IAC9D,+CAAyB,CAAA;IACzB,+DAAyC,CAAA;IACzC,2CAAqB,CAAA;IACrB,uCAAiB,CAAA;AACnB,CAAC,EAVW,kBAAkB,KAAlB,kBAAkB,QAU7B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACvB,4FAA4F;IAC5F,gCAAe,CAAA;IACf,sCAAsC;IACtC,8BAAa,CAAA;IACb,eAAe;IACf,8BAAa,CAAA;IACb,oEAAoE;IACpE,8BAAa,CAAA;IACb,yDAAyD;IACzD,gDAA+B,CAAA;AACjC,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AAED,kEAAkE;AAClE,+BAA+B;AAC/B,kEAAkE;AAElE;;;;GAIG;AACH,MAAM,CAAN,IAAY,yBAkCX;AAlCD,WAAY,yBAAyB;IACnC,0CAA0C;IAC1C,0EAA6C,CAAA;IAC7C,0EAA6C,CAAA;IAC7C,0EAA6C,CAAA;IAC7C,wFAA2D,CAAA;IAE3D,iEAAiE;IACjE,0DAA6B,CAAA;IAC7B,8EAAiD,CAAA;IACjD,oEAAuC,CAAA;IAEvC,oFAAoF;IACpF,sFAAyD,CAAA;IAEzD,oCAAoC;IACpC,kEAAqC,CAAA;IACrC,kEAAqC,CAAA;IAErC,mFAAmF;IACnF,qFAAqF;IACrF,8DAAiC,CAAA;IACjC,8DAAiC,CAAA;IACjC,8DAAiC,CAAA;IAEjC,yEAAyE;IACzE,oFAAuD,CAAA;IACvD,oFAAuD,CAAA;IACvD,oFAAuD,CAAA;IAEvD,kFAAkF;IAClF,qFAAqF;IACrF,gFAAmD,CAAA;IACnD,gFAAmD,CAAA;AACrD,CAAC,EAlCW,yBAAyB,KAAzB,yBAAyB,QAkCpC","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 * 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  /** Descriptive name (e.g., organization name or user display name) */\n  name: string;\n  /** Contact email for invoices and receipts */\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  /** 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\nexport interface StandardBilling_UpdateSubscriptionRequest {\n  items?: Array<{\n    /** Provider-side subscription item ID (used to target the correct item on the provider).\n     * If omitted, the provider transformer falls back to index-based matching. */\n    providerSubscriptionItemId?: string;\n    providerPriceId: string;\n    quantity?: number;\n  }>;\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  metadata?: Record<string, string>;\n}\n\nexport interface StandardBilling_CancelSubscriptionOptions {\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  trialEnd?: Date;\n  items: Array<{\n    providerSubscriptionItemId: string;\n    providerProductId: string;\n    providerPriceId: string;\n    quantity: number;\n  }>;\n  /** Active discount on this subscription (from coupon/promotion code) */\n  discount?: {\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  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// 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  // ── Product/Price sync (Wildo → Provider) ──\n  syncProduct(request: StandardBilling_SyncProductRequest): Promise<StandardBilling_SyncProductResponse>;\n  syncPrice(request: StandardBilling_SyncPriceRequest): Promise<StandardBilling_SyncPriceResponse>;\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<void>;\n  cancelSubscription(providerSubscriptionId: string, options?: StandardBilling_CancelSubscriptionOptions): Promise<void>;\n  pauseSubscription(providerSubscriptionId: string): Promise<void>;\n  resumeSubscription(providerSubscriptionId: string): Promise<void>;\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 prorated cost of a plan change before user commits */\n  retrieveUpcomingInvoice(providerSubscriptionId: string, newPriceId?: string): 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"]}
+{"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\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  trialEnd?: Date;\n  items: Array<{\n    providerSubscriptionItemId: string;\n    providerProductId: string;\n    providerPriceId: string;\n    quantity: number;\n  }>;\n  /** Active discount on this subscription (from coupon/promotion code) */\n  discount?: {\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// 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  // ── Product/Price sync (Wildo → Provider) ──\n  syncProduct(request: StandardBilling_SyncProductRequest): Promise<StandardBilling_SyncProductResponse>;\n  syncPrice(request: StandardBilling_SyncPriceRequest): Promise<StandardBilling_SyncPriceResponse>;\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   * Classify an error thrown by `updateSubscription`, `cancelSubscription` or `removeScheduledCancellation` (#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"]}

package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ExternalProvider_ExchangeProtocol_Configuration_Base, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Profile_Base } from "../core/commons.external-connectors-models.schemas";
+import { ExternalProvider_ExchangeProtocol_Kind } from "../core/commons.external-connectors-models.schemas";
 /**
  * Concrete document-extraction model ids the framework knows.
  *
@@ -103,14 +103,6 @@ export declare const resolveDocumentExtractionModelForApplicability: (input: {
     applicability: DocumentExtraction_Applicability;
     providerRef: string;
 }, catalog?: Record<DocumentExtractionProvider_Model, DocumentExtraction_ModelCatalogEntry>) => DocumentExtraction_ModelResolution;
-export type DocumentExtractionProvider_Profile = ExternalProvider_ExchangeProtocol_Profile_Base & {
-    baseURL?: string;
-    /** Model ids this provider serves (advertised for validation/UX). */
-    supportedModels?: string[];
-};
-export type DocumentExtractionProvider_Configuration = ExternalProvider_ExchangeProtocol_Configuration_Base & {
-    customLocation?: string;
-};
 /**
  * Usage of one extraction call.
  *
@@ -169,11 +161,76 @@ export declare const DocumentExtractionProvider_ExtractDocumentTextOutputSchema:
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type DocumentExtractionProvider_ExtractDocumentTextOutput = z.infer<typeof DocumentExtractionProvider_ExtractDocumentTextOutputSchema>;
-export declare const DocumentExtractionProvider_StatusSchema: z.ZodObject<{
-    status: z.ZodEnum<typeof import("..").ExternalProvider_Status>;
-    lastCheckedAt: z.ZodString;
-    errorReason: z.ZodOptional<z.ZodString>;
-    protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER>;
-}, z.core.$strip>;
-export type DocumentExtractionProvider_Status = z.infer<typeof DocumentExtractionProvider_StatusSchema>;
+/**
+ * WHY an extraction failed, in the only two senses a caller can act on differently.
+ *
+ * This is the arm's most load-bearing output after the text itself, and the consequence of
+ * confusing the two is CORPUS DELETION rather than a misleading log line:
+ * `RagIngestionBackendService` deletes a field's entire chunk set when an ingestion pass yields no
+ * text, so reporting a provider OUTAGE as an unreadable document silently destroys a live,
+ * already-embedded corpus and reports success.
+ *
+ * It lived in `saas-backend-lib`'s execution seam until 2026-09-09, which is exactly why the wire
+ * shape lived there too: a vocabulary a provider cannot reach is one a provider cannot answer in,
+ * so classification had to be done by whoever could. Moving it here is what makes
+ * {@link DocumentExtraction_ProviderExtraction} expressible at all.
+ */
+export declare enum DocumentExtraction_FailureClass {
+    /**
+     * The provider read the request and judged the DOCUMENT unprocessable — corrupt bytes, an
+     * unsupported format, a password-protected file. PERMANENT: re-sending the same bytes cannot
+     * succeed, so a sweep may safely stop retrying and skip the document.
+     */
+    UNREADABLE_DOCUMENT = "unreadable_document",
+    /**
+     * The provider could not be reached, refused the credential, throttled, or failed internally —
+     * a network error, a 401/403, a 429, any 5xx, or a timeout. TRANSIENT and, decisively, says
+     * NOTHING about the document. A caller must not conclude anything about the bytes from this.
+     */
+    PROVIDER_UNAVAILABLE = "provider_unavailable"
+}
+/**
+ * What a provider's `parseExtractResponse` returns: the extraction, or a CLASSIFIED refusal.
+ *
+ * A discriminated union rather than "return the output or throw", for the reason the failure class
+ * exists: a thrown `Error` carries no class, and the engine would have to guess one — which is the
+ * guess that deletes a corpus. A provider that cannot classify a response must still say which of
+ * the two it is, and the arm's JSDoc tells it to prefer `PROVIDER_UNAVAILABLE` when unsure,
+ * because that is the answer with no destructive consequence.
+ */
+export type DocumentExtraction_ProviderExtraction = {
+    extracted: true;
+    /** Per-page text joined in document order. Markdown is kept as-is; see the output schema. */
+    text: string;
+    /** Pages the provider actually returned — the authoritative count, not the request estimate. */
+    pageCount: number;
+    /** The model the provider says produced the text. Absent means "the resolved model". */
+    model?: string;
+    usage?: DocumentExtractionProvider_Usage;
+} | {
+    extracted: false;
+    failureClass: DocumentExtraction_FailureClass;
+    /**
+     * Operator-facing reason. MUST NOT contain the provider's response body or any part of the
+     * document: this message reaches logs, and a provider error body can echo request content.
+     */
+    message: string;
+};
+/**
+ * The framework's DEFAULT reading of an extraction response's HTTP status.
+ *
+ * Offered to every provider's `parseExtractResponse` rather than applied by the engine, because
+ * only the provider knows whether its vendor also signals a per-document verdict inside a 2xx
+ * body (Twilio does exactly that on the SMS arm). What it prevents is each provider re-deriving a
+ * classification whose worst case is corpus deletion.
+ *
+ * Every boundary is deliberate:
+ *   - 4xx generally means the provider READ the request and refused THIS DOCUMENT → permanent.
+ *   - 401/403 is a CREDENTIAL fault, not a document fault. Classifying it as unreadable would make
+ *     a rotated key look like a corpus of corrupt files and delete chunk sets across every
+ *     document for as long as the key was wrong.
+ *   - 408/429 are explicitly retryable by their own definition.
+ *   - 5xx is the provider's fault, never the document's.
+ */
+export declare const classifyDocumentExtractionHttpStatus: (status: number) => DocumentExtraction_FailureClass;
 //# sourceMappingURL=document-extraction.external-connectors-models.schemas.d.ts.map

package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-extraction.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/document-extraction.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACL,oDAAoD,EACpD,sCAAsC,EACtC,8CAA8C,EAE/C,MAAM,oDAAoD,CAAA;AAmC3D;;;;GAIG;AACH,oBAAY,gCAAgC;IAC1C;;;;;;OAMG;IACH,kBAAkB,uBAAuB;CAC1C;AAED;;;;;;;GAOG;AACH,oBAAY,uCAAuC;IACjD,qDAAqD;IACrD,qBAAqB,2CAA2C;CACjE;AAED;;;;;;;;;;;GAWG;AACH,oBAAY,gCAAgC;IAC1C,+FAA+F;IAC/F,qBAAqB,0BAA0B;CAChD;AACD,uFAAuF;AAEvF;;;GAGG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sFAAsF;IACtF,eAAe,EAAE,SAAS,gCAAgC,EAAE,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CACpD,gCAAgC,EAChC,oCAAoC,CAmBrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kDAAkD,EAAE,MAAM,CACrE,gCAAgC,EAChC,SAAS,gCAAgC,EAAE,CAK5C,CAAC;AAEF,8HAA8H;AAC9H,oBAAY,yCAAyC;IACnD,mEAAmE;IACnE,yBAAyB,8BAA8B;CACxD;AAED,MAAM,MAAM,kCAAkC,GAC1C;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,gCAAgC,CAAC;IAAC,KAAK,EAAE,oCAAoC,CAAA;CAAE,GACxG;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB,OAAO,EAAE,yCAAyC,CAAC;IACnD,gBAAgB,EAAE,SAAS,gCAAgC,EAAE,CAAC;CAC/D,CAAC;AAEN;;;;;GAKG;AACH,eAAO,MAAM,8CAA8C,GACzD,OAAO;IAAE,aAAa,EAAE,gCAAgC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC/E,UAAS,MAAM,CAAC,gCAAgC,EAAE,oCAAoC,CAAqC,KAC1H,kCAeF,CAAC;AAOF,MAAM,MAAM,kCAAkC,GAAG,8CAA8C,GAAG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAA;AAED,MAAM,MAAM,wCAAwC,GAAG,oDAAoD,GAAG;IAC5G,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAA;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC;;;iBAKjD,CAAC;AACH,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAEtG,eAAO,MAAM,2DAA2D;;;;iBAItE,CAAC;AACH,MAAM,MAAM,qDAAqD,GAAG,CAAC,CAAC,KAAK,CACzE,OAAO,2DAA2D,CACnE,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yDAAyD;;;iBAKpE,CAAC;AACH,MAAM,MAAM,mDAAmD,GAAG,CAAC,CAAC,KAAK,CACvE,OAAO,yDAAyD,CACjE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0DAA0D;;;;;;;;iBAOrE,CAAC;AACH,MAAM,MAAM,oDAAoD,GAAG,CAAC,CAAC,KAAK,CACxE,OAAO,0DAA0D,CAClE,CAAC;AAMF,eAAO,MAAM,uCAAuC;;;;;iBAElD,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC"}
+{"version":3,"file":"document-extraction.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/document-extraction.external-connectors-models.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Status_BaseSchema, } from "../core/commons.external-connectors-models.schemas.js";
+import { ExternalProvider_ExchangeProtocol_Kind, } from "../core/commons.external-connectors-models.schemas.js";
 //===============================================================
 // Document Extraction Provider
 // --------
@@ -157,9 +157,15 @@ export const resolveDocumentExtractionModelForApplicability = (input, catalog =
  * embeddings arm records for its own missing completion-token dimension.
  */
 export const DocumentExtractionProvider_UsageSchema = z.object({
-    /** Pages the provider reports having processed (Mistral: `usage_info.pages_processed`). */
+    /**
+     * Pages the provider reports having processed.
+     *
+     * The FRAMEWORK's name for the dimension. Which vendor field it is projected from is the
+     * provider's `parseExtractResponse` to know — the wired one reads Mistral's
+     * `usage_info.pages_processed`, and a second provider will read something else.
+     */
     pagesProcessed: z.number().optional(),
-    /** Document size the provider reports having received (Mistral: `usage_info.doc_size_bytes`). */
+    /** Document size the provider reports having received. Same ownership as `pagesProcessed`. */
     documentSizeBytes: z.number().optional(),
 });
 export const DocumentExtractionProvider_ExecutionTransportMetadataSchema = z.object({
@@ -209,9 +215,72 @@ export const DocumentExtractionProvider_ExtractDocumentTextOutputSchema = z.obje
     usage: DocumentExtractionProvider_UsageSchema,
 });
 // ===============================================================
-// STATUS
+// The PROVIDER-OWNED WIRE SEAM
+// --------
+// Until 2026-09-09 this arm declared `baseUrl`, `endpointPath`, `apiKey` and `models` — where the
+// call goes and how it authenticates — and NOTHING about the body or the response. So the engine's
+// execution seam composed Mistral's `/v1/ocr` request (`document: { type: 'document_url',
+// document_url }`, `include_image_base64`) and read Mistral's response (`pages[].markdown`,
+// `usage_info.pages_processed`) with the vendor named nowhere, and a second provider declaring
+// DOCUMENT_EXTRACTION_PROVIDER would have been sent through Mistral's API carrying its own key.
+//
+// The remedy is the one the EMAIL and SMS arms already converged on: the provider declares PURE
+// FUNCTIONS and the engine owns transport and credentials. The types those functions are written
+// against live HERE rather than beside the contract, because the failure vocabulary is read by
+// BOTH sides — the provider produces it, the engine's caller branches on it — and a vocabulary
+// with two homes is a vocabulary that drifts.
 // ===============================================================
-export const DocumentExtractionProvider_StatusSchema = ExternalProvider_ExchangeProtocol_Status_BaseSchema.extend({
-    protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER),
-});
+/**
+ * WHY an extraction failed, in the only two senses a caller can act on differently.
+ *
+ * This is the arm's most load-bearing output after the text itself, and the consequence of
+ * confusing the two is CORPUS DELETION rather than a misleading log line:
+ * `RagIngestionBackendService` deletes a field's entire chunk set when an ingestion pass yields no
+ * text, so reporting a provider OUTAGE as an unreadable document silently destroys a live,
+ * already-embedded corpus and reports success.
+ *
+ * It lived in `saas-backend-lib`'s execution seam until 2026-09-09, which is exactly why the wire
+ * shape lived there too: a vocabulary a provider cannot reach is one a provider cannot answer in,
+ * so classification had to be done by whoever could. Moving it here is what makes
+ * {@link DocumentExtraction_ProviderExtraction} expressible at all.
+ */
+export var DocumentExtraction_FailureClass;
+(function (DocumentExtraction_FailureClass) {
+    /**
+     * The provider read the request and judged the DOCUMENT unprocessable — corrupt bytes, an
+     * unsupported format, a password-protected file. PERMANENT: re-sending the same bytes cannot
+     * succeed, so a sweep may safely stop retrying and skip the document.
+     */
+    DocumentExtraction_FailureClass["UNREADABLE_DOCUMENT"] = "unreadable_document";
+    /**
+     * The provider could not be reached, refused the credential, throttled, or failed internally —
+     * a network error, a 401/403, a 429, any 5xx, or a timeout. TRANSIENT and, decisively, says
+     * NOTHING about the document. A caller must not conclude anything about the bytes from this.
+     */
+    DocumentExtraction_FailureClass["PROVIDER_UNAVAILABLE"] = "provider_unavailable";
+})(DocumentExtraction_FailureClass || (DocumentExtraction_FailureClass = {}));
+/**
+ * The framework's DEFAULT reading of an extraction response's HTTP status.
+ *
+ * Offered to every provider's `parseExtractResponse` rather than applied by the engine, because
+ * only the provider knows whether its vendor also signals a per-document verdict inside a 2xx
+ * body (Twilio does exactly that on the SMS arm). What it prevents is each provider re-deriving a
+ * classification whose worst case is corpus deletion.
+ *
+ * Every boundary is deliberate:
+ *   - 4xx generally means the provider READ the request and refused THIS DOCUMENT → permanent.
+ *   - 401/403 is a CREDENTIAL fault, not a document fault. Classifying it as unreadable would make
+ *     a rotated key look like a corpus of corrupt files and delete chunk sets across every
+ *     document for as long as the key was wrong.
+ *   - 408/429 are explicitly retryable by their own definition.
+ *   - 5xx is the provider's fault, never the document's.
+ */
+export const classifyDocumentExtractionHttpStatus = (status) => {
+    const isCredentialFault = status === 401 || status === 403;
+    const isThrottleOrTimeout = status === 408 || status === 429;
+    const isServerFault = status >= 500;
+    return isCredentialFault || isThrottleOrTimeout || isServerFault
+        ? DocumentExtraction_FailureClass.PROVIDER_UNAVAILABLE
+        : DocumentExtraction_FailureClass.UNREADABLE_DOCUMENT;
+};
 //# sourceMappingURL=document-extraction.external-connectors-models.schemas.js.map

package/dist/esm/protocols/document-extraction.external-connectors-models.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-extraction.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/document-extraction.external-connectors-models.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\"\nimport {\n  ExternalProvider_ExchangeProtocol_Configuration_Base,\n  ExternalProvider_ExchangeProtocol_Kind,\n  ExternalProvider_ExchangeProtocol_Profile_Base,\n  ExternalProvider_ExchangeProtocol_Status_BaseSchema,\n} from \"../core/commons.external-connectors-models.schemas\"\n\n//===============================================================\n// Document Extraction Provider\n// --------\n// Document bytes → text. Serves the file-side TEXT PROVIDER that\n// `FileTextExtractionBackendService` owns, whose largest consumer is the RAG\n// ingestion path (`.ragSource()` corpus building).\n//\n// ## Why this is a provider at all, and not just a better library\n//\n// The local `pdfjs-dist` path reads a PDF's TEXT LAYER. A scanned document — the\n// common case for uploaded contracts, invoices and forms — is an IMAGE of a page\n// and carries no text layer, so it extracts to the empty string, contributes no\n// chunks, and becomes silently unanswerable. That is not a defect in the local\n// library; it is its nature, and it is the entire reason a provider exists here.\n//\n// ## Deliberately a SEPARATE protocol kind from `LLM_PROVIDER`\n//\n// Same reasoning as `EMBEDDINGS_PROVIDER` (RAG plan DL2) and the `IMAGE_PROVIDER`\n// precedent before it: an unmapped LLM operation key fails SILENTLY across every\n// consumer surface (the registry's semantic-operation map filters it out, the\n// executor never dispatches it, the capability slot never fills), whereas a new\n// `runtimeContract.kind` fails COMPILATION at every switch over the union. That\n// compile-enforcement is the whole argument, and it is verified rather than\n// asserted — deleting an arm from `secretRefForRuntimeContract` reddens the\n// `never` check with the offending contract named in the diagnostic.\n//\n// It also fills its own `EngineCapability.AI_DOCUMENT_EXTRACTION` slot, so an\n// application selects its OCR provider INDEPENDENTLY of its chat and embeddings\n// providers. Those are three unrelated procurement decisions — a deployment may\n// well want Anthropic for chat, OpenAI for embeddings, and Mistral for OCR — and\n// fusing any two of them into one `selection` entry makes that unexpressible.\n//===============================================================\n\n/**\n * Concrete document-extraction model ids the framework knows.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum DocumentExtractionProvider_Model {\n  /**\n   * Mistral's OCR model alias. An ALIAS deliberately, not a dated snapshot: unlike an embedding\n   * model — where the concrete id is persisted as a stamp on every chunk and a silent change\n   * would fracture the vector space — extraction output is consumed immediately and re-derived\n   * on every ingestion pass, so tracking the vendor's current model is a benefit rather than a\n   * hazard.\n   */\n  MISTRAL_OCR_LATEST = \"mistral-ocr-latest\",\n}\n\n/**\n * The document-extraction operation vocabulary — deliberately DISJOINT from\n * `LLMProvider_OperationKey`, `ImageProvider_OperationKey` and\n * `EmbeddingsProvider_OperationKey` (each protocol kind owns its own operation enum, so a key's\n * membership decides its protocol without inspection).\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum DocumentExtractionProvider_OperationKey {\n  /** One document's bytes → its text, page by page. */\n  EXTRACT_DOCUMENT_TEXT = \"documentExtraction.extractDocumentText\",\n}\n\n/**\n * @wildo_source:part:start saas.external-providers.document-extraction.applicability facet:kind:api facet:audience:app-developer\n *\n * WHAT a document is being extracted FOR — the durable axis of extraction-model selection\n * (model-selection-by-applicability rule: an author names a CLASS, never a concrete model id;\n * the framework resolves the id from the catalog + preference below).\n *\n * One class today, and that is a statement rather than a placeholder: every extraction in the\n * engine feeds `FileTextExtractionBackendService`, and a second class would only be earned by a\n * surface with genuinely different requirements (a layout-preserving export, say, or a\n * cheap-and-approximate preview tier).\n */\nexport enum DocumentExtraction_Applicability {\n  /** The default document-text surface: file text extraction, and the RAG corpus built on it. */\n  DOCUMENT_TEXT_DEFAULT = \"document-text-default\",\n}\n/** @wildo_source:part:end saas.external-providers.document-extraction.applicability */\n\n/**\n * One row per document-extraction model: everything the framework knows about a concrete id.\n * Mirrors `Embeddings_ModelCatalogEntry`'s shape at the size this axis needs today.\n */\nexport type DocumentExtraction_ModelCatalogEntry = {\n  /** The `ref` of the provider module that serves this id. */\n  providerRef: string;\n  /**\n   * MIME types this model can process, as declared by the provider's documentation.\n   *\n   * Consulted BEFORE bytes leave the deployment: sending a document the model cannot read wastes\n   * an egress of application content, which the data-minimization posture on the execution seam\n   * exists to avoid.\n   */\n  supportedMimeTypes: readonly string[];\n  /** FRAMEWORK OPINION — which applicability classes this model may be resolved for. */\n  applicabilities: readonly DocumentExtraction_Applicability[];\n};\n\n/**\n * THE document-extraction model catalog — the single per-model fact table (the\n * `EMBEDDINGS_MODEL_CATALOG` discipline: an EXHAUSTIVE `Record`, so a new\n * `DocumentExtractionProvider_Model` member without a row is a compile error).\n */\nexport const DOCUMENT_EXTRACTION_MODEL_CATALOG: Record<\n  DocumentExtractionProvider_Model,\n  DocumentExtraction_ModelCatalogEntry\n> = {\n  [DocumentExtractionProvider_Model.MISTRAL_OCR_LATEST]: {\n    providerRef: \"mistral\",\n    /**\n     * Mistral's published OCR format list (docs.mistral.ai \"Known limitations\": \"Supported\n     * formats for OCR: PDF, PNG, JPG, JPEG, TIFF, BMP, GIF, WEBP\"), narrowed to the MIME types\n     * the engine's own extraction gate admits today.\n     *\n     * `application/pdf` is the only entry that is currently REACHABLE: image MIME types are\n     * refused by `FileTextExtractionBackendService.isExtractionSupported`, which is a separate,\n     * deliberate decision (an uploaded photo is not a document). The image types are declared\n     * here anyway because this row states what the MODEL can do, not what the engine currently\n     * asks it to do — and admitting images to extraction later must be an engine decision, not\n     * an accidental consequence of a catalog edit.\n     */\n    supportedMimeTypes: [\"application/pdf\", \"image/png\", \"image/jpeg\", \"image/tiff\", \"image/webp\"],\n    applicabilities: [DocumentExtraction_Applicability.DOCUMENT_TEXT_DEFAULT],\n  },\n};\n\n/**\n * The framework's DEFAULT answer to \"which extraction model serves this class\", ordered by\n * preference, highest first.\n *\n * Unlike the embeddings preference — which is a MIGRATION KEY, because editing it re-binds a\n * class and forces every stamped chunk to be re-embedded — this one carries no durable\n * consequence: extraction output is re-derived on the next ingestion pass and nothing persists\n * the model that produced it. Editing this list changes what the next extraction uses and\n * nothing else.\n */\nexport const DOCUMENT_EXTRACTION_MODEL_APPLICABILITY_PREFERENCE: Record<\n  DocumentExtraction_Applicability,\n  readonly DocumentExtractionProvider_Model[]\n> = {\n  [DocumentExtraction_Applicability.DOCUMENT_TEXT_DEFAULT]: [\n    DocumentExtractionProvider_Model.MISTRAL_OCR_LATEST,\n  ],\n};\n\n/** Why {@link resolveDocumentExtractionModelForApplicability} could not answer — carried into a named CONFIGURATION error. */\nexport enum DocumentExtraction_ModelResolutionFailure {\n  /** The applicability has no candidate at all for this provider. */\n  NO_CANDIDATE_FOR_PROVIDER = \"no_candidate_for_provider\",\n}\n\nexport type DocumentExtraction_ModelResolution =\n  | { resolved: true; model: DocumentExtractionProvider_Model; entry: DocumentExtraction_ModelCatalogEntry }\n  | {\n      resolved: false;\n      failure: DocumentExtraction_ModelResolutionFailure;\n      consideredModels: readonly DocumentExtractionProvider_Model[];\n    };\n\n/**\n * Resolve an applicability class to ONE concrete extraction model for a given provider.\n *\n * Fails CLOSED and explains itself (the `resolveModelForApplicability` contract): a silent\n * fallback to some other model would send application documents to a model nobody chose.\n */\nexport const resolveDocumentExtractionModelForApplicability = (\n  input: { applicability: DocumentExtraction_Applicability; providerRef: string },\n  catalog: Record<DocumentExtractionProvider_Model, DocumentExtraction_ModelCatalogEntry> = DOCUMENT_EXTRACTION_MODEL_CATALOG,\n): DocumentExtraction_ModelResolution => {\n  const candidates = DOCUMENT_EXTRACTION_MODEL_APPLICABILITY_PREFERENCE[input.applicability];\n  const forProvider = candidates.filter((model) => {\n    const entry = catalog[model];\n    return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);\n  });\n  if (forProvider.length === 0) {\n    return {\n      resolved: false,\n      failure: DocumentExtraction_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER,\n      consideredModels: candidates,\n    };\n  }\n  const model = forProvider[0]!;\n  return { resolved: true, model, entry: catalog[model] };\n};\n\n// ===============================================================\n// Document Extraction Provider Profiles and Configurations (the config arm —\n// disjoint from LLM/image/embeddings config by construction)\n// ===============================================================\n\nexport type DocumentExtractionProvider_Profile = ExternalProvider_ExchangeProtocol_Profile_Base & {\n  baseURL?: string,\n  /** Model ids this provider serves (advertised for validation/UX). */\n  supportedModels?: string[],\n}\n\nexport type DocumentExtractionProvider_Configuration = ExternalProvider_ExchangeProtocol_Configuration_Base & {\n  customLocation?: string,\n}\n\n// ===============================================================\n// Document Extraction Operations Context\n// ===============================================================\n\n/**\n * Usage of one extraction call.\n *\n * There is NO token dimension, and its absence is structural rather than an omission: an OCR\n * call is billed and reported per PAGE, not per token. Any consumer judging usage completeness\n * for an extraction must do so on `pagesProcessed` alone — the operation-aware discipline the\n * embeddings arm records for its own missing completion-token dimension.\n */\nexport const DocumentExtractionProvider_UsageSchema = z.object({\n  /** Pages the provider reports having processed (Mistral: `usage_info.pages_processed`). */\n  pagesProcessed: z.number().optional(),\n  /** Document size the provider reports having received (Mistral: `usage_info.doc_size_bytes`). */\n  documentSizeBytes: z.number().optional(),\n});\nexport type DocumentExtractionProvider_Usage = z.infer<typeof DocumentExtractionProvider_UsageSchema>;\n\nexport const DocumentExtractionProvider_ExecutionTransportMetadataSchema = z.object({\n  protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER),\n  providerRef: z.string(),\n  model: z.string().optional(),\n});\nexport type DocumentExtractionProvider_ExecutionTransportMetadata = z.infer<\n  typeof DocumentExtractionProvider_ExecutionTransportMetadataSchema\n>;\n\n// ===============================================================\n// Document Extraction I/O Schemas\n// ===============================================================\n\n/**\n * Input DESCRIPTOR of the {@link DocumentExtractionProvider_OperationKey.EXTRACT_DOCUMENT_TEXT}\n * operation — the metadata about the document, deliberately NOT the document.\n *\n * ⚠️ THE BYTES ARE ABSENT ON PURPOSE, and this is the design decision most likely to be\n * \"corrected\" by a later reader. A `documentBase64: z.string()` field here would be structurally\n * correct and operationally dangerous: a Zod-shaped input object is the thing every diagnostic\n * path in this codebase reaches for when something goes wrong — error `context`, debug logs,\n * agent-call traces — and a multi-megabyte base64 blob of an application's private contract is\n * the single worst payload to make casually loggable. The embeddings arm reached the same\n * conclusion from the other direction (its header forbids raw texts and vectors from ever\n * entering a trace); here the prohibition is enforced by the SHAPE rather than by discipline.\n *\n * The bytes travel as a `Buffer` on the execution service's own request type, which no\n * serializer walks.\n */\nexport const DocumentExtractionProvider_ExtractDocumentTextInputSchema = z.object({\n  /** The document's MIME type — checked against the model's catalog row before any egress. */\n  mimeType: z.string(),\n  /** Byte length of the document being sent. Diagnostic and ceiling-checking only. */\n  documentByteLength: z.number().int().nonnegative(),\n});\nexport type DocumentExtractionProvider_ExtractDocumentTextInput = z.infer<\n  typeof DocumentExtractionProvider_ExtractDocumentTextInputSchema\n>;\n\n/**\n * Output of {@link DocumentExtractionProvider_OperationKey.EXTRACT_DOCUMENT_TEXT}.\n *\n * `text` is the concatenation of the provider's per-page output in document order. Providers in\n * this family return MARKDOWN per page (Mistral's `pages[].markdown`), which is kept as-is:\n * headings and table structure are signal for a retrieval corpus, and stripping them to \"plain\"\n * text would discard information the provider was paid to recover.\n */\nexport const DocumentExtractionProvider_ExtractDocumentTextOutputSchema = z.object({\n  text: z.string(),\n  /** Pages the provider actually returned — the authoritative count, not the request's estimate. */\n  pageCount: z.number().int().nonnegative(),\n  /** The concrete model that produced the text. */\n  model: z.string(),\n  usage: DocumentExtractionProvider_UsageSchema,\n});\nexport type DocumentExtractionProvider_ExtractDocumentTextOutput = z.infer<\n  typeof DocumentExtractionProvider_ExtractDocumentTextOutputSchema\n>;\n\n// ===============================================================\n// STATUS\n// ===============================================================\n\nexport const DocumentExtractionProvider_StatusSchema = ExternalProvider_ExchangeProtocol_Status_BaseSchema.extend({\n  protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER),\n});\nexport type DocumentExtractionProvider_Status = z.infer<typeof DocumentExtractionProvider_StatusSchema>;\n"]}
+{"version":3,"file":"document-extraction.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/document-extraction.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// Document Extraction Provider\n// --------\n// Document bytes → text. Serves the file-side TEXT PROVIDER that\n// `FileTextExtractionBackendService` owns, whose largest consumer is the RAG\n// ingestion path (`.ragSource()` corpus building).\n//\n// ## Why this is a provider at all, and not just a better library\n//\n// The local `pdfjs-dist` path reads a PDF's TEXT LAYER. A scanned document — the\n// common case for uploaded contracts, invoices and forms — is an IMAGE of a page\n// and carries no text layer, so it extracts to the empty string, contributes no\n// chunks, and becomes silently unanswerable. That is not a defect in the local\n// library; it is its nature, and it is the entire reason a provider exists here.\n//\n// ## Deliberately a SEPARATE protocol kind from `LLM_PROVIDER`\n//\n// Same reasoning as `EMBEDDINGS_PROVIDER` (RAG plan DL2) and the `IMAGE_PROVIDER`\n// precedent before it: an unmapped LLM operation key fails SILENTLY across every\n// consumer surface (the registry's semantic-operation map filters it out, the\n// executor never dispatches it, the capability slot never fills), whereas a new\n// `runtimeContract.kind` fails COMPILATION at every switch over the union. That\n// compile-enforcement is the whole argument, and it is verified rather than\n// asserted — deleting an arm from `secretRefForRuntimeContract` reddens the\n// `never` check with the offending contract named in the diagnostic.\n//\n// It also fills its own `EngineCapability.AI_DOCUMENT_EXTRACTION` slot, so an\n// application selects its OCR provider INDEPENDENTLY of its chat and embeddings\n// providers. Those are three unrelated procurement decisions — a deployment may\n// well want Anthropic for chat, OpenAI for embeddings, and Mistral for OCR — and\n// fusing any two of them into one `selection` entry makes that unexpressible.\n//===============================================================\n\n/**\n * Concrete document-extraction model ids the framework knows.\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum DocumentExtractionProvider_Model {\n  /**\n   * Mistral's OCR model alias. An ALIAS deliberately, not a dated snapshot: unlike an embedding\n   * model — where the concrete id is persisted as a stamp on every chunk and a silent change\n   * would fracture the vector space — extraction output is consumed immediately and re-derived\n   * on every ingestion pass, so tracking the vendor's current model is a benefit rather than a\n   * hazard.\n   */\n  MISTRAL_OCR_LATEST = \"mistral-ocr-latest\",\n}\n\n/**\n * The document-extraction operation vocabulary — deliberately DISJOINT from\n * `LLMProvider_OperationKey`, `ImageProvider_OperationKey` and\n * `EmbeddingsProvider_OperationKey` (each protocol kind owns its own operation enum, so a key's\n * membership decides its protocol without inspection).\n *\n * Import path: `@wildo-ai/external-connectors-models`.\n */\nexport enum DocumentExtractionProvider_OperationKey {\n  /** One document's bytes → its text, page by page. */\n  EXTRACT_DOCUMENT_TEXT = \"documentExtraction.extractDocumentText\",\n}\n\n/**\n * @wildo_source:part:start saas.external-providers.document-extraction.applicability facet:kind:api facet:audience:app-developer\n *\n * WHAT a document is being extracted FOR — the durable axis of extraction-model selection\n * (model-selection-by-applicability rule: an author names a CLASS, never a concrete model id;\n * the framework resolves the id from the catalog + preference below).\n *\n * One class today, and that is a statement rather than a placeholder: every extraction in the\n * engine feeds `FileTextExtractionBackendService`, and a second class would only be earned by a\n * surface with genuinely different requirements (a layout-preserving export, say, or a\n * cheap-and-approximate preview tier).\n */\nexport enum DocumentExtraction_Applicability {\n  /** The default document-text surface: file text extraction, and the RAG corpus built on it. */\n  DOCUMENT_TEXT_DEFAULT = \"document-text-default\",\n}\n/** @wildo_source:part:end saas.external-providers.document-extraction.applicability */\n\n/**\n * One row per document-extraction model: everything the framework knows about a concrete id.\n * Mirrors `Embeddings_ModelCatalogEntry`'s shape at the size this axis needs today.\n */\nexport type DocumentExtraction_ModelCatalogEntry = {\n  /** The `ref` of the provider module that serves this id. */\n  providerRef: string;\n  /**\n   * MIME types this model can process, as declared by the provider's documentation.\n   *\n   * Consulted BEFORE bytes leave the deployment: sending a document the model cannot read wastes\n   * an egress of application content, which the data-minimization posture on the execution seam\n   * exists to avoid.\n   */\n  supportedMimeTypes: readonly string[];\n  /** FRAMEWORK OPINION — which applicability classes this model may be resolved for. */\n  applicabilities: readonly DocumentExtraction_Applicability[];\n};\n\n/**\n * THE document-extraction model catalog — the single per-model fact table (the\n * `EMBEDDINGS_MODEL_CATALOG` discipline: an EXHAUSTIVE `Record`, so a new\n * `DocumentExtractionProvider_Model` member without a row is a compile error).\n */\nexport const DOCUMENT_EXTRACTION_MODEL_CATALOG: Record<\n  DocumentExtractionProvider_Model,\n  DocumentExtraction_ModelCatalogEntry\n> = {\n  [DocumentExtractionProvider_Model.MISTRAL_OCR_LATEST]: {\n    providerRef: \"mistral\",\n    /**\n     * Mistral's published OCR format list (docs.mistral.ai \"Known limitations\": \"Supported\n     * formats for OCR: PDF, PNG, JPG, JPEG, TIFF, BMP, GIF, WEBP\"), narrowed to the MIME types\n     * the engine's own extraction gate admits today.\n     *\n     * `application/pdf` is the only entry that is currently REACHABLE: image MIME types are\n     * refused by `FileTextExtractionBackendService.isExtractionSupported`, which is a separate,\n     * deliberate decision (an uploaded photo is not a document). The image types are declared\n     * here anyway because this row states what the MODEL can do, not what the engine currently\n     * asks it to do — and admitting images to extraction later must be an engine decision, not\n     * an accidental consequence of a catalog edit.\n     */\n    supportedMimeTypes: [\"application/pdf\", \"image/png\", \"image/jpeg\", \"image/tiff\", \"image/webp\"],\n    applicabilities: [DocumentExtraction_Applicability.DOCUMENT_TEXT_DEFAULT],\n  },\n};\n\n/**\n * The framework's DEFAULT answer to \"which extraction model serves this class\", ordered by\n * preference, highest first.\n *\n * Unlike the embeddings preference — which is a MIGRATION KEY, because editing it re-binds a\n * class and forces every stamped chunk to be re-embedded — this one carries no durable\n * consequence: extraction output is re-derived on the next ingestion pass and nothing persists\n * the model that produced it. Editing this list changes what the next extraction uses and\n * nothing else.\n */\nexport const DOCUMENT_EXTRACTION_MODEL_APPLICABILITY_PREFERENCE: Record<\n  DocumentExtraction_Applicability,\n  readonly DocumentExtractionProvider_Model[]\n> = {\n  [DocumentExtraction_Applicability.DOCUMENT_TEXT_DEFAULT]: [\n    DocumentExtractionProvider_Model.MISTRAL_OCR_LATEST,\n  ],\n};\n\n/** Why {@link resolveDocumentExtractionModelForApplicability} could not answer — carried into a named CONFIGURATION error. */\nexport enum DocumentExtraction_ModelResolutionFailure {\n  /** The applicability has no candidate at all for this provider. */\n  NO_CANDIDATE_FOR_PROVIDER = \"no_candidate_for_provider\",\n}\n\nexport type DocumentExtraction_ModelResolution =\n  | { resolved: true; model: DocumentExtractionProvider_Model; entry: DocumentExtraction_ModelCatalogEntry }\n  | {\n      resolved: false;\n      failure: DocumentExtraction_ModelResolutionFailure;\n      consideredModels: readonly DocumentExtractionProvider_Model[];\n    };\n\n/**\n * Resolve an applicability class to ONE concrete extraction model for a given provider.\n *\n * Fails CLOSED and explains itself (the `resolveModelForApplicability` contract): a silent\n * fallback to some other model would send application documents to a model nobody chose.\n */\nexport const resolveDocumentExtractionModelForApplicability = (\n  input: { applicability: DocumentExtraction_Applicability; providerRef: string },\n  catalog: Record<DocumentExtractionProvider_Model, DocumentExtraction_ModelCatalogEntry> = DOCUMENT_EXTRACTION_MODEL_CATALOG,\n): DocumentExtraction_ModelResolution => {\n  const candidates = DOCUMENT_EXTRACTION_MODEL_APPLICABILITY_PREFERENCE[input.applicability];\n  const forProvider = candidates.filter((model) => {\n    const entry = catalog[model];\n    return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);\n  });\n  if (forProvider.length === 0) {\n    return {\n      resolved: false,\n      failure: DocumentExtraction_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER,\n      consideredModels: candidates,\n    };\n  }\n  const model = forProvider[0]!;\n  return { resolved: true, model, entry: catalog[model] };\n};\n\n// ===============================================================\n// Document Extraction Operations Context\n// ===============================================================\n\n/**\n * Usage of one extraction call.\n *\n * There is NO token dimension, and its absence is structural rather than an omission: an OCR\n * call is billed and reported per PAGE, not per token. Any consumer judging usage completeness\n * for an extraction must do so on `pagesProcessed` alone — the operation-aware discipline the\n * embeddings arm records for its own missing completion-token dimension.\n */\nexport const DocumentExtractionProvider_UsageSchema = z.object({\n  /**\n   * Pages the provider reports having processed.\n   *\n   * The FRAMEWORK's name for the dimension. Which vendor field it is projected from is the\n   * provider's `parseExtractResponse` to know — the wired one reads Mistral's\n   * `usage_info.pages_processed`, and a second provider will read something else.\n   */\n  pagesProcessed: z.number().optional(),\n  /** Document size the provider reports having received. Same ownership as `pagesProcessed`. */\n  documentSizeBytes: z.number().optional(),\n});\nexport type DocumentExtractionProvider_Usage = z.infer<typeof DocumentExtractionProvider_UsageSchema>;\n\nexport const DocumentExtractionProvider_ExecutionTransportMetadataSchema = z.object({\n  protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER),\n  providerRef: z.string(),\n  model: z.string().optional(),\n});\nexport type DocumentExtractionProvider_ExecutionTransportMetadata = z.infer<\n  typeof DocumentExtractionProvider_ExecutionTransportMetadataSchema\n>;\n\n// ===============================================================\n// Document Extraction I/O Schemas\n// ===============================================================\n\n/**\n * Input DESCRIPTOR of the {@link DocumentExtractionProvider_OperationKey.EXTRACT_DOCUMENT_TEXT}\n * operation — the metadata about the document, deliberately NOT the document.\n *\n * ⚠️ THE BYTES ARE ABSENT ON PURPOSE, and this is the design decision most likely to be\n * \"corrected\" by a later reader. A `documentBase64: z.string()` field here would be structurally\n * correct and operationally dangerous: a Zod-shaped input object is the thing every diagnostic\n * path in this codebase reaches for when something goes wrong — error `context`, debug logs,\n * agent-call traces — and a multi-megabyte base64 blob of an application's private contract is\n * the single worst payload to make casually loggable. The embeddings arm reached the same\n * conclusion from the other direction (its header forbids raw texts and vectors from ever\n * entering a trace); here the prohibition is enforced by the SHAPE rather than by discipline.\n *\n * The bytes travel as a `Buffer` on the execution service's own request type, which no\n * serializer walks.\n */\nexport const DocumentExtractionProvider_ExtractDocumentTextInputSchema = z.object({\n  /** The document's MIME type — checked against the model's catalog row before any egress. */\n  mimeType: z.string(),\n  /** Byte length of the document being sent. Diagnostic and ceiling-checking only. */\n  documentByteLength: z.number().int().nonnegative(),\n});\nexport type DocumentExtractionProvider_ExtractDocumentTextInput = z.infer<\n  typeof DocumentExtractionProvider_ExtractDocumentTextInputSchema\n>;\n\n/**\n * Output of {@link DocumentExtractionProvider_OperationKey.EXTRACT_DOCUMENT_TEXT}.\n *\n * `text` is the concatenation of the provider's per-page output in document order. Providers in\n * this family return MARKDOWN per page (Mistral's `pages[].markdown`), which is kept as-is:\n * headings and table structure are signal for a retrieval corpus, and stripping them to \"plain\"\n * text would discard information the provider was paid to recover.\n */\nexport const DocumentExtractionProvider_ExtractDocumentTextOutputSchema = z.object({\n  text: z.string(),\n  /** Pages the provider actually returned — the authoritative count, not the request's estimate. */\n  pageCount: z.number().int().nonnegative(),\n  /** The concrete model that produced the text. */\n  model: z.string(),\n  usage: DocumentExtractionProvider_UsageSchema,\n});\nexport type DocumentExtractionProvider_ExtractDocumentTextOutput = z.infer<\n  typeof DocumentExtractionProvider_ExtractDocumentTextOutputSchema\n>;\n\n// ===============================================================\n// The PROVIDER-OWNED WIRE SEAM\n// --------\n// Until 2026-09-09 this arm declared `baseUrl`, `endpointPath`, `apiKey` and `models` — where the\n// call goes and how it authenticates — and NOTHING about the body or the response. So the engine's\n// execution seam composed Mistral's `/v1/ocr` request (`document: { type: 'document_url',\n// document_url }`, `include_image_base64`) and read Mistral's response (`pages[].markdown`,\n// `usage_info.pages_processed`) with the vendor named nowhere, and a second provider declaring\n// DOCUMENT_EXTRACTION_PROVIDER would have been sent through Mistral's API carrying its own key.\n//\n// The remedy is the one the EMAIL and SMS arms already converged on: the provider declares PURE\n// FUNCTIONS and the engine owns transport and credentials. The types those functions are written\n// against live HERE rather than beside the contract, because the failure vocabulary is read by\n// BOTH sides — the provider produces it, the engine's caller branches on it — and a vocabulary\n// with two homes is a vocabulary that drifts.\n// ===============================================================\n\n/**\n * WHY an extraction failed, in the only two senses a caller can act on differently.\n *\n * This is the arm's most load-bearing output after the text itself, and the consequence of\n * confusing the two is CORPUS DELETION rather than a misleading log line:\n * `RagIngestionBackendService` deletes a field's entire chunk set when an ingestion pass yields no\n * text, so reporting a provider OUTAGE as an unreadable document silently destroys a live,\n * already-embedded corpus and reports success.\n *\n * It lived in `saas-backend-lib`'s execution seam until 2026-09-09, which is exactly why the wire\n * shape lived there too: a vocabulary a provider cannot reach is one a provider cannot answer in,\n * so classification had to be done by whoever could. Moving it here is what makes\n * {@link DocumentExtraction_ProviderExtraction} expressible at all.\n */\nexport enum DocumentExtraction_FailureClass {\n  /**\n   * The provider read the request and judged the DOCUMENT unprocessable — corrupt bytes, an\n   * unsupported format, a password-protected file. PERMANENT: re-sending the same bytes cannot\n   * succeed, so a sweep may safely stop retrying and skip the document.\n   */\n  UNREADABLE_DOCUMENT = \"unreadable_document\",\n  /**\n   * The provider could not be reached, refused the credential, throttled, or failed internally —\n   * a network error, a 401/403, a 429, any 5xx, or a timeout. TRANSIENT and, decisively, says\n   * NOTHING about the document. A caller must not conclude anything about the bytes from this.\n   */\n  PROVIDER_UNAVAILABLE = \"provider_unavailable\",\n}\n\n/**\n * What a provider's `parseExtractResponse` returns: the extraction, or a CLASSIFIED refusal.\n *\n * A discriminated union rather than \"return the output or throw\", for the reason the failure class\n * exists: a thrown `Error` carries no class, and the engine would have to guess one — which is the\n * guess that deletes a corpus. A provider that cannot classify a response must still say which of\n * the two it is, and the arm's JSDoc tells it to prefer `PROVIDER_UNAVAILABLE` when unsure,\n * because that is the answer with no destructive consequence.\n */\nexport type DocumentExtraction_ProviderExtraction =\n  | {\n      extracted: true;\n      /** Per-page text joined in document order. Markdown is kept as-is; see the output schema. */\n      text: string;\n      /** Pages the provider actually returned — the authoritative count, not the request estimate. */\n      pageCount: number;\n      /** The model the provider says produced the text. Absent means \"the resolved model\". */\n      model?: string;\n      usage?: DocumentExtractionProvider_Usage;\n    }\n  | {\n      extracted: false;\n      failureClass: DocumentExtraction_FailureClass;\n      /**\n       * Operator-facing reason. MUST NOT contain the provider's response body or any part of the\n       * document: this message reaches logs, and a provider error body can echo request content.\n       */\n      message: string;\n    };\n\n/**\n * The framework's DEFAULT reading of an extraction response's HTTP status.\n *\n * Offered to every provider's `parseExtractResponse` rather than applied by the engine, because\n * only the provider knows whether its vendor also signals a per-document verdict inside a 2xx\n * body (Twilio does exactly that on the SMS arm). What it prevents is each provider re-deriving a\n * classification whose worst case is corpus deletion.\n *\n * Every boundary is deliberate:\n *   - 4xx generally means the provider READ the request and refused THIS DOCUMENT → permanent.\n *   - 401/403 is a CREDENTIAL fault, not a document fault. Classifying it as unreadable would make\n *     a rotated key look like a corpus of corrupt files and delete chunk sets across every\n *     document for as long as the key was wrong.\n *   - 408/429 are explicitly retryable by their own definition.\n *   - 5xx is the provider's fault, never the document's.\n */\nexport const classifyDocumentExtractionHttpStatus = (status: number): DocumentExtraction_FailureClass => {\n  const isCredentialFault = status === 401 || status === 403;\n  const isThrottleOrTimeout = status === 408 || status === 429;\n  const isServerFault = status >= 500;\n  return isCredentialFault || isThrottleOrTimeout || isServerFault\n    ? DocumentExtraction_FailureClass.PROVIDER_UNAVAILABLE\n    : DocumentExtraction_FailureClass.UNREADABLE_DOCUMENT;\n};\n\n"]}