@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/external-providers/model-cost-accounting-config.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cost-accounting-config.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/model-cost-accounting-config.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,mCAAmC,EAAE,MAAM,yCAAyC,CAAC;AAC9F,OAAO,EAAE,2CAA2C,EAAE,MAAM,8BAA8B,CAAC;AAE3F,8EAA8E;AAC9E,MAAM,CAAC,MAAM,0CAA0C,GAAG,CAAC,CAAC;AAC5D,sHAAsH;AACtH,MAAM,CAAC,MAAM,oCAAoC,GAAG,YAAY,CAAC;AAEjE,4IAA4I;AAC5I,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,mGAAmG;IACnG,+BAA+B,EAAE,CAAC,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzF,2FAA2F;IAC3F,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,0CAA0C,CAAC;IACzG,+CAA+C;IAC/C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,oCAAoC,CAAC;CACzF,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;IACjC,IAAI,CAAC;QACH,2CAA2C,CAAC,MAAM,CAAC,+BAA+B,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,iCAAiC,CAAC,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnJ,CAAC;AACH,CAAC,CAAC,CAAC;AAGH,sEAAsE","sourcesContent":["/**\n * # `modelCostAccounting`: how an application prices its model calls and closes its cost periods (#1598)\n *\n * A backend-authored configuration section. It is NOT on the shared (frontend-visible) configuration: the\n * rates an application registers are its negotiated acquisition costs, which is the firm's internal margin\n * data.\n *\n * - `providerUsagePricingAuthorities` — the application's price list. Registered by the application because\n *   rates are negotiated; the engine ships no catalogue (it would be wrong for every contract and go stale).\n *   A duplicate `pricingAuthorityRef@pricingAuthorityVersion` is refused when the configuration is parsed,\n *   which is at startup.\n * - `periodCloseGraceDays` — how long after a calendar month ends the period-close batch waits before\n *   writing that month's aggregates, so late rows (retries, a drain backlog) land first. Startup refuses a\n *   declared `OPERATIONAL_LOGS` period shorter than one month plus this grace: the close reads detail rows,\n *   and would otherwise read rows the retention sweep had already deleted.\n */\nimport { z } from 'zod';\n\nimport { ProviderUsagePricingAuthoritySchema } from './provider-usage-pricing.shared.schemas';\nimport { assertUniqueProviderUsagePricingAuthorities } from './provider-usage-cost.shared';\n\n/** Default grace after a month ends before its cost aggregates are closed. */\nexport const MODEL_COST_PERIOD_CLOSE_DEFAULT_GRACE_DAYS = 3;\n/** Default schedule of the period-close batch: daily at 02:17 UTC (it closes every period whose grace has passed). */\nexport const MODEL_COST_PERIOD_CLOSE_DEFAULT_CRON = '17 2 * * *';\n\n/** @wildo_source:part:start saas.models.model-cost-accounting-config facet:layer:shared facet:family:config facet:audience:app-developer */\nexport const ModelCostAccountingConfigSchema = z.object({\n  /** The application's registered model prices. Absent or empty: every call is recorded UNPRICED. */\n  providerUsagePricingAuthorities: z.array(ProviderUsagePricingAuthoritySchema).default([]),\n  /** Days after a calendar month (UTC) ends before its cost aggregates are written. 0–27. */\n  periodCloseGraceDays: z.number().int().min(0).max(27).default(MODEL_COST_PERIOD_CLOSE_DEFAULT_GRACE_DAYS),\n  /** Cron schedule of the period-close batch. */\n  periodCloseCronSchedule: z.string().min(1).default(MODEL_COST_PERIOD_CLOSE_DEFAULT_CRON),\n}).superRefine((config, context) => {\n  try {\n    assertUniqueProviderUsagePricingAuthorities(config.providerUsagePricingAuthorities);\n  } catch (error) {\n    context.addIssue({ code: 'custom', path: ['providerUsagePricingAuthorities'], message: error instanceof Error ? error.message : String(error) });\n  }\n});\nexport type ModelCostAccountingConfig = z.infer<typeof ModelCostAccountingConfigSchema>;\nexport type ModelCostAccountingConfigInput = z.input<typeof ModelCostAccountingConfigSchema>;\n/** @wildo_source:part:end saas.models.model-cost-accounting-config */\n"]}

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it
+ * (#1702, consumed by #561).
+ *
+ * ## Why it lives here, and why NOT on `public-runtime`
+ *
+ * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for
+ * the reason that file gives: a component ships in its own React-bearing package, which must be able to
+ * type itself without importing the connectors package that resolves it.
+ *
+ * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's
+ * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not
+ * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).
+ * Restating the address shape here to stay inside that closure was the rejected alternative: it would be
+ * a second source for the one address vocabulary #1730 exists to make single. A type-only import is
+ * erased from every bundle, so a component package importing these types from the root pays nothing.
+ *
+ * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is
+ * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.
+ */
+import type { AddressValue } from '@wildo-ai/zod-decorators';
+/** @wildo_source:part:start saas.models.provider-address-lookup-contract facet:kind:api facet:audience:app-developer */
+/**
+ * What an address lookup hands back for ONE chosen place.
+ *
+ * `address` is the application's own value: the person chose it, and it is stored exactly as a typed
+ * address would be. `placeId` is the VENDOR's key for the place, present only when the component's
+ * declared `placeIdRetention` allows one; the framework refuses a selection that carries a place id its
+ * component declared it never returns, and never stores one (#561 D3).
+ */
+export interface ProviderAddressLookupSelection {
+    readonly address: AddressValue;
+    /** The vendor's identifier for the matched place. Opaque, usable for this interaction only, and never stored. */
+    readonly placeId?: string;
+}
+/**
+ * The props every `FRONTEND_ADDRESS_LOOKUP` component receives.
+ *
+ * Deliberately narrow. The component suggests and resolves; the FIELD owns the value, its validation
+ * (`z_address()` with its `countriesAllowed`) and its persistence. That split is what lets an address
+ * field work with no lookup at all, which is why the capability fills no engine slot.
+ *
+ * ## The vendor is reached through `suggest` and `retrieve`, never directly (#561 D2)
+ *
+ * The framework's host binds both to the operations the component's descriptor declares
+ * (`addressLookup.suggestOperationId` / `retrieveOperationId`) and runs them through the application
+ * backend's provider-operation door. The host also writes the vendor session token into each input when the
+ * descriptor names `sessionTokenInput` (#561 D4) — a component never generates, holds or rotates one. Each
+ * resolves to the operation's parsed output, and rejects with the door's error (a refusal, a throttle, a
+ * vendor timeout); a component reports that through `onError` and the field stays usable by hand.
+ */
+export interface ProviderAddressLookupProps {
+    /** The provider's own `ref`. */
+    readonly providerRef: string;
+    /** The provider's public configuration, already validated against its `publicConfigSchema` when it declares one. */
+    readonly publicConfig: Readonly<Record<string, unknown>>;
+    /**
+     * ISO 3166-1 alpha-2 codes the field accepts (`z_address({ countriesAllowed })`). A component should
+     * restrict its suggestions to them; the field still validates whatever comes back.
+     */
+    readonly countriesAllowed?: readonly string[];
+    /** The field's default country, a hint for ranking suggestions. */
+    readonly defaultCountry?: string;
+    /** The person's language (BCP 47), so suggestions and the retrieved address are spelled in it where the vendor can. */
+    readonly languageCode: string;
+    /** True while the field is disabled or read-only: the component offers no search then. */
+    readonly disabled: boolean;
+    /**
+     * The search control's form NAME. The host renders the control's visible label (from the application's
+     * labels) for the element whose id is `field-<name>` — the id every engine form control takes — so the
+     * component puts that id on its focusable control and invents no label text of its own.
+     */
+    readonly name: string;
+    /**
+     * The vendor's required attribution (#561 D4), from the descriptor's `attributionMark`, or absent when the vendor
+     * requires none. `mark` is the vendor's text, verbatim; `accessibleLabel` is a sentence from the application's
+     * labels naming it, for assistive technology.
+     *
+     * The component shows it INSIDE the container that shows its suggestions, whenever suggestions are shown — the
+     * placement Google requires ("within the same visual container" as the content). Render it with
+     * `ProviderAddressLookupAttribution` (`@wildo-ai/saas-frontend-lib`), which applies the vendor's text rules
+     * (untranslated, on one line, in a permitted colour); the framework's own lookup combobox does.
+     * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — text attribution rules,
+     * fetched 2026-09-29.
+     */
+    readonly attribution?: ProviderAddressLookupAttributionText;
+    /** Run the declared SUGGEST operation with this input. */
+    suggest(input: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** Run the declared RETRIEVE operation with this input. Ends the vendor session, whatever it answers. */
+    retrieve(input: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** The person chose a place. Called at most once per interaction. */
+    onSelect(selection: ProviderAddressLookupSelection): void;
+    /** The person dismissed the lookup without choosing. Ends the vendor session. */
+    onCancel(): void;
+    /**
+     * The lookup could not run — the door refused it, the vendor timed out or answered a shape the adapter
+     * cannot read. Reported rather than thrown, for the reason the file-picker contract gives: a throw inside
+     * a component's own event handler reaches no React error boundary.
+     */
+    onError(error: Error): void;
+}
+/** A vendor's required attribution, as the host hands it to a lookup component. */
+export interface ProviderAddressLookupAttributionText {
+    /** The vendor's own attribution text, never translated or restyled ("Google Maps"). */
+    readonly mark: string;
+    /** A sentence from the application's labels that names the mark, for assistive technology. */
+    readonly accessibleLabel: string;
+}
+/** One suggestion, as a person reads it. Vendor text, never derived by the framework. */
+export interface ProviderAddressLookupSuggestion {
+    /** The vendor's handle for the suggestion, passed back to `buildRetrieveInput`. Opaque; never stored. */
+    readonly id: string;
+    /** The line a person recognises the place by (the street address). */
+    readonly primaryText: string;
+    /** The line that disambiguates it (town, region, country), when the vendor gives one. */
+    readonly secondaryText?: string;
+}
+/**
+ * Everything VENDOR-SPECIFIC about an address lookup, as four pure functions: how a query becomes the
+ * suggest operation's input, how its answer becomes suggestions, how a chosen suggestion becomes the retrieve
+ * operation's input, and how that answer becomes the framework's `AddressValue`.
+ *
+ * With it, the framework's own combobox (`ProviderAddressLookupCombobox` in `@wildo-ai/saas-frontend-lib`)
+ * is a complete lookup component: the keyboard pattern, the debounce, the minimum query length, stale-answer
+ * handling and the manual-entry fallback are written once rather than once per vendor. A provider whose
+ * lookup needs its own UI implements `ProviderAddressLookupProps` directly instead.
+ *
+ * `readAddress` returns TEXT parts only: a vendor geocode is never taken (#561 D3). A stored coordinate has no
+ * expiry, while a lookup's geocode is at best storable for a limited time (Google: 30 days) or not at all (Mapbox
+ * Search Box) — #561's 2026-09-14 reading of both vendors' terms — and nothing runs the vendor's clock. The
+ * field drops coordinates anyway.
+ */
+export interface ProviderAddressLookupAdapter {
+    buildSuggestInput(request: {
+        readonly query: string;
+        readonly countriesAllowed?: readonly string[];
+        readonly defaultCountry?: string;
+        readonly languageCode: string;
+    }): Record<string, unknown>;
+    /** Never throws on a well-formed but empty answer; returns `[]`. Throws only on an answer it cannot read. */
+    readSuggestions(output: unknown): readonly ProviderAddressLookupSuggestion[];
+    buildRetrieveInput(request: {
+        readonly suggestion: ProviderAddressLookupSuggestion;
+        readonly languageCode: string;
+    }): Record<string, unknown>;
+    /** `undefined` when the vendor answered with no postal address for the place (a place with no street address). */
+    readAddress(output: unknown): AddressValue | undefined;
+}
+/** @wildo_source:part:end saas.models.provider-address-lookup-contract */
+//# sourceMappingURL=provider-address-lookup-contract.shared.types.d.ts.map

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-address-lookup-contract.shared.types.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-address-lookup-contract.shared.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,wHAAwH;AAExH;;;;;;;GAOG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,iHAAiH;IACjH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,0BAA0B;IACzC,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oHAAoH;IACpH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,uHAAuH;IACvH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,oCAAoC,CAAC;IAC5D,0DAA0D;IAC1D,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,yGAAyG;IACzG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC1D,iFAAiF;IACjF,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC7B;AAED,mFAAmF;AACnF,MAAM,WAAW,oCAAoC;IACnD,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,yFAAyF;AACzF,MAAM,WAAW,+BAA+B;IAC9C,yGAAyG;IACzG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,4BAA4B;IAC3C,iBAAiB,CAAC,OAAO,EAAE;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC9C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,6GAA6G;IAC7G,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,+BAA+B,EAAE,CAAC;IAC7E,kBAAkB,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,+BAA+B,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9I,kHAAkH;IAClH,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;CACxD;AACD,0EAA0E"}

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.js

@@ -0,0 +1,22 @@
+/**
+ * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it
+ * (#1702, consumed by #561).
+ *
+ * ## Why it lives here, and why NOT on `public-runtime`
+ *
+ * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for
+ * the reason that file gives: a component ships in its own React-bearing package, which must be able to
+ * type itself without importing the connectors package that resolves it.
+ *
+ * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's
+ * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not
+ * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).
+ * Restating the address shape here to stay inside that closure was the rejected alternative: it would be
+ * a second source for the one address vocabulary #1730 exists to make single. A type-only import is
+ * erased from every bundle, so a component package importing these types from the root pays nothing.
+ *
+ * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is
+ * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.
+ */
+/** @wildo_source:part:end saas.models.provider-address-lookup-contract */
+//# sourceMappingURL=provider-address-lookup-contract.shared.types.js.map

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-address-lookup-contract.shared.types.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-address-lookup-contract.shared.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqIH,0EAA0E","sourcesContent":["/**\n * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it\n * (#1702, consumed by #561).\n *\n * ## Why it lives here, and why NOT on `public-runtime`\n *\n * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for\n * the reason that file gives: a component ships in its own React-bearing package, which must be able to\n * type itself without importing the connectors package that resolves it.\n *\n * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's\n * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not\n * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).\n * Restating the address shape here to stay inside that closure was the rejected alternative: it would be\n * a second source for the one address vocabulary #1730 exists to make single. A type-only import is\n * erased from every bundle, so a component package importing these types from the root pays nothing.\n *\n * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is\n * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.\n */\n\nimport type { AddressValue } from '@wildo-ai/zod-decorators';\n\n/** @wildo_source:part:start saas.models.provider-address-lookup-contract facet:kind:api facet:audience:app-developer */\n\n/**\n * What an address lookup hands back for ONE chosen place.\n *\n * `address` is the application's own value: the person chose it, and it is stored exactly as a typed\n * address would be. `placeId` is the VENDOR's key for the place, present only when the component's\n * declared `placeIdRetention` allows one; the framework refuses a selection that carries a place id its\n * component declared it never returns, and never stores one (#561 D3).\n */\nexport interface ProviderAddressLookupSelection {\n  readonly address: AddressValue;\n  /** The vendor's identifier for the matched place. Opaque, usable for this interaction only, and never stored. */\n  readonly placeId?: string;\n}\n\n/**\n * The props every `FRONTEND_ADDRESS_LOOKUP` component receives.\n *\n * Deliberately narrow. The component suggests and resolves; the FIELD owns the value, its validation\n * (`z_address()` with its `countriesAllowed`) and its persistence. That split is what lets an address\n * field work with no lookup at all, which is why the capability fills no engine slot.\n *\n * ## The vendor is reached through `suggest` and `retrieve`, never directly (#561 D2)\n *\n * The framework's host binds both to the operations the component's descriptor declares\n * (`addressLookup.suggestOperationId` / `retrieveOperationId`) and runs them through the application\n * backend's provider-operation door. The host also writes the vendor session token into each input when the\n * descriptor names `sessionTokenInput` (#561 D4) — a component never generates, holds or rotates one. Each\n * resolves to the operation's parsed output, and rejects with the door's error (a refusal, a throttle, a\n * vendor timeout); a component reports that through `onError` and the field stays usable by hand.\n */\nexport interface ProviderAddressLookupProps {\n  /** The provider's own `ref`. */\n  readonly providerRef: string;\n  /** The provider's public configuration, already validated against its `publicConfigSchema` when it declares one. */\n  readonly publicConfig: Readonly<Record<string, unknown>>;\n  /**\n   * ISO 3166-1 alpha-2 codes the field accepts (`z_address({ countriesAllowed })`). A component should\n   * restrict its suggestions to them; the field still validates whatever comes back.\n   */\n  readonly countriesAllowed?: readonly string[];\n  /** The field's default country, a hint for ranking suggestions. */\n  readonly defaultCountry?: string;\n  /** The person's language (BCP 47), so suggestions and the retrieved address are spelled in it where the vendor can. */\n  readonly languageCode: string;\n  /** True while the field is disabled or read-only: the component offers no search then. */\n  readonly disabled: boolean;\n  /**\n   * The search control's form NAME. The host renders the control's visible label (from the application's\n   * labels) for the element whose id is `field-<name>` — the id every engine form control takes — so the\n   * component puts that id on its focusable control and invents no label text of its own.\n   */\n  readonly name: string;\n  /**\n   * The vendor's required attribution (#561 D4), from the descriptor's `attributionMark`, or absent when the vendor\n   * requires none. `mark` is the vendor's text, verbatim; `accessibleLabel` is a sentence from the application's\n   * labels naming it, for assistive technology.\n   *\n   * The component shows it INSIDE the container that shows its suggestions, whenever suggestions are shown — the\n   * placement Google requires (\"within the same visual container\" as the content). Render it with\n   * `ProviderAddressLookupAttribution` (`@wildo-ai/saas-frontend-lib`), which applies the vendor's text rules\n   * (untranslated, on one line, in a permitted colour); the framework's own lookup combobox does.\n   * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — text attribution rules,\n   * fetched 2026-09-29.\n   */\n  readonly attribution?: ProviderAddressLookupAttributionText;\n  /** Run the declared SUGGEST operation with this input. */\n  suggest(input: Readonly<Record<string, unknown>>): Promise<unknown>;\n  /** Run the declared RETRIEVE operation with this input. Ends the vendor session, whatever it answers. */\n  retrieve(input: Readonly<Record<string, unknown>>): Promise<unknown>;\n  /** The person chose a place. Called at most once per interaction. */\n  onSelect(selection: ProviderAddressLookupSelection): void;\n  /** The person dismissed the lookup without choosing. Ends the vendor session. */\n  onCancel(): void;\n  /**\n   * The lookup could not run — the door refused it, the vendor timed out or answered a shape the adapter\n   * cannot read. Reported rather than thrown, for the reason the file-picker contract gives: a throw inside\n   * a component's own event handler reaches no React error boundary.\n   */\n  onError(error: Error): void;\n}\n\n/** A vendor's required attribution, as the host hands it to a lookup component. */\nexport interface ProviderAddressLookupAttributionText {\n  /** The vendor's own attribution text, never translated or restyled (\"Google Maps\"). */\n  readonly mark: string;\n  /** A sentence from the application's labels that names the mark, for assistive technology. */\n  readonly accessibleLabel: string;\n}\n\n/** One suggestion, as a person reads it. Vendor text, never derived by the framework. */\nexport interface ProviderAddressLookupSuggestion {\n  /** The vendor's handle for the suggestion, passed back to `buildRetrieveInput`. Opaque; never stored. */\n  readonly id: string;\n  /** The line a person recognises the place by (the street address). */\n  readonly primaryText: string;\n  /** The line that disambiguates it (town, region, country), when the vendor gives one. */\n  readonly secondaryText?: string;\n}\n\n/**\n * Everything VENDOR-SPECIFIC about an address lookup, as four pure functions: how a query becomes the\n * suggest operation's input, how its answer becomes suggestions, how a chosen suggestion becomes the retrieve\n * operation's input, and how that answer becomes the framework's `AddressValue`.\n *\n * With it, the framework's own combobox (`ProviderAddressLookupCombobox` in `@wildo-ai/saas-frontend-lib`)\n * is a complete lookup component: the keyboard pattern, the debounce, the minimum query length, stale-answer\n * handling and the manual-entry fallback are written once rather than once per vendor. A provider whose\n * lookup needs its own UI implements `ProviderAddressLookupProps` directly instead.\n *\n * `readAddress` returns TEXT parts only: a vendor geocode is never taken (#561 D3). A stored coordinate has no\n * expiry, while a lookup's geocode is at best storable for a limited time (Google: 30 days) or not at all (Mapbox\n * Search Box) — #561's 2026-09-14 reading of both vendors' terms — and nothing runs the vendor's clock. The\n * field drops coordinates anyway.\n */\nexport interface ProviderAddressLookupAdapter {\n  buildSuggestInput(request: {\n    readonly query: string;\n    readonly countriesAllowed?: readonly string[];\n    readonly defaultCountry?: string;\n    readonly languageCode: string;\n  }): Record<string, unknown>;\n  /** Never throws on a well-formed but empty answer; returns `[]`. Throws only on an answer it cannot read. */\n  readSuggestions(output: unknown): readonly ProviderAddressLookupSuggestion[];\n  buildRetrieveInput(request: { readonly suggestion: ProviderAddressLookupSuggestion; readonly languageCode: string }): Record<string, unknown>;\n  /** `undefined` when the vendor answered with no postal address for the place (a place with no street address). */\n  readAddress(output: unknown): AddressValue | undefined;\n}\n/** @wildo_source:part:end saas.models.provider-address-lookup-contract */\n"]}

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */
+/**
+ * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add
+ * operations to that provider.
+ *
+ * ```ts
+ * providers: {
+ *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },
+ *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },
+ * }
+ * ```
+ *
+ * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a
+ * framework provider package, a provider package in the application's own scope
+ * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.
+ *
+ * ## Why an augmentation needs an opt-in at all
+ *
+ * An augmentation adds operations to a provider it does not own, and those operations run with the BASE
+ * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a
+ * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the
+ * application's to make. Installing a package decides nothing: a package that is a dependency and is not
+ * named here contributes no operation. That is also what keeps a provider package that augments many
+ * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.
+ *
+ * ## Why application-level rather than per runtime scope
+ *
+ * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package
+ * in for the backend and not for a minion would give one grant two operation sets, and an operation id
+ * would mean a request in one process and nothing in another. The augmentation applies wherever the base
+ * provider is scoped.
+ *
+ * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a
+ * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.
+ *
+ * Absent means none — never "every installed augmentation".
+ */
+export declare const ProviderAugmentationOptInsSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+export type ProviderAugmentationOptIns = z.infer<typeof ProviderAugmentationOptInsSchema>;
+/** @wildo_source:part:end saas.config.providers.augmentations */
+//# sourceMappingURL=provider-augmentation-opt-ins.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-augmentation-opt-ins.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-augmentation-opt-ins.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gJAAgJ;AAChJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,gCAAgC,mDAW5C,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAC1F,iEAAiE"}

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */
+/**
+ * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add
+ * operations to that provider.
+ *
+ * ```ts
+ * providers: {
+ *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },
+ *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },
+ * }
+ * ```
+ *
+ * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a
+ * framework provider package, a provider package in the application's own scope
+ * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.
+ *
+ * ## Why an augmentation needs an opt-in at all
+ *
+ * An augmentation adds operations to a provider it does not own, and those operations run with the BASE
+ * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a
+ * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the
+ * application's to make. Installing a package decides nothing: a package that is a dependency and is not
+ * named here contributes no operation. That is also what keeps a provider package that augments many
+ * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.
+ *
+ * ## Why application-level rather than per runtime scope
+ *
+ * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package
+ * in for the backend and not for a minion would give one grant two operation sets, and an operation id
+ * would mean a request in one process and nothing in another. The augmentation applies wherever the base
+ * provider is scoped.
+ *
+ * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a
+ * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.
+ *
+ * Absent means none — never "every installed augmentation".
+ */
+export const ProviderAugmentationOptInsSchema = z.record(z.string().min(1), z.array(z.string().min(1)).min(1).superRefine((packageNames, ctx) => {
+    const seen = new Set();
+    for (const [index, packageName] of packageNames.entries()) {
+        if (seen.has(packageName)) {
+            ctx.addIssue({ code: 'custom', path: [index], message: `"${packageName}" is opted in twice for one provider.` });
+        }
+        seen.add(packageName);
+    }
+}));
+/** @wildo_source:part:end saas.config.providers.augmentations */
+//# sourceMappingURL=provider-augmentation-opt-ins.shared.schemas.js.map

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-augmentation-opt-ins.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-augmentation-opt-ins.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gJAAgJ;AAChJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CACtD,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EACjB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,YAAY,EAAE,GAAG,EAAE,EAAE;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1D,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,WAAW,uCAAuC,EAAE,CAAC,CAAC;QACnH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxB,CAAC;AACH,CAAC,CAAC,CACH,CAAC;AAEF,iEAAiE","sourcesContent":["import { z } from 'zod';\n\n/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */\n/**\n * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add\n * operations to that provider.\n *\n * ```ts\n * providers: {\n *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },\n *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },\n * }\n * ```\n *\n * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a\n * framework provider package, a provider package in the application's own scope\n * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.\n *\n * ## Why an augmentation needs an opt-in at all\n *\n * An augmentation adds operations to a provider it does not own, and those operations run with the BASE\n * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a\n * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the\n * application's to make. Installing a package decides nothing: a package that is a dependency and is not\n * named here contributes no operation. That is also what keeps a provider package that augments many\n * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.\n *\n * ## Why application-level rather than per runtime scope\n *\n * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package\n * in for the backend and not for a minion would give one grant two operation sets, and an operation id\n * would mean a request in one process and nothing in another. The augmentation applies wherever the base\n * provider is scoped.\n *\n * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a\n * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.\n *\n * Absent means none — never \"every installed augmentation\".\n */\nexport const ProviderAugmentationOptInsSchema = z.record(\n  z.string().min(1),\n  z.array(z.string().min(1)).min(1).superRefine((packageNames, ctx) => {\n    const seen = new Set<string>();\n    for (const [index, packageName] of packageNames.entries()) {\n      if (seen.has(packageName)) {\n        ctx.addIssue({ code: 'custom', path: [index], message: `\"${packageName}\" is opted in twice for one provider.` });\n      }\n      seen.add(packageName);\n    }\n  }),\n);\nexport type ProviderAugmentationOptIns = z.infer<typeof ProviderAugmentationOptInsSchema>;\n/** @wildo_source:part:end saas.config.providers.augmentations */\n"]}

package/dist/esm/external-providers/provider-authentication-assurance.shared.schemas.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/** Policy for an otherwise valid external login that cannot demonstrate required MFA. */
+export declare enum ExternalAssuranceEnforcement {
+    WARN = "warn",
+    STRICT = "strict"
+}
+/** Do not collapse contractual delegation, measured MFA and warning admission into one boolean. */
+export declare enum ExternalAssuranceDecision {
+    NOT_REQUIRED = "not_required",
+    DELEGATED = "delegated",
+    VERIFIED_MFA = "verified_mfa",
+    WARNED = "warned",
+    REFUSED = "refused"
+}
+export declare enum ExternalAssuranceReason {
+    POLICY_NOT_REQUIRED = "policy_not_required",
+    ENTERPRISE_DELEGATION = "enterprise_delegation",
+    SESSION_MFA = "session_mfa",
+    EVIDENCE_MISSING = "evidence_missing",
+    EVIDENCE_INSUFFICIENT = "evidence_insufficient",
+    METHOD_REQUIREMENT_UNPROVEN = "method_requirement_unproven"
+}
+/** Safe decision summary: no upstream token, raw claims, nonce, or user profile. */
+export declare const ExternalAssuranceAssessmentSchema: z.ZodObject<{
+    decision: z.ZodEnum<typeof ExternalAssuranceDecision>;
+    reason: z.ZodEnum<typeof ExternalAssuranceReason>;
+    enforcement: z.ZodEnum<typeof ExternalAssuranceEnforcement>;
+}, z.core.$strip>;
+export type ExternalAssuranceAssessment = z.infer<typeof ExternalAssuranceAssessmentSchema>;
+//# sourceMappingURL=provider-authentication-assurance.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-authentication-assurance.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-authentication-assurance.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,oBAAY,4BAA4B;IACtC,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,mGAAmG;AACnG,oBAAY,yBAAyB;IACnC,YAAY,iBAAiB;IAC7B,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AACD,oBAAY,uBAAuB;IACjC,mBAAmB,wBAAwB;IAC3C,qBAAqB,0BAA0B;IAC/C,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;CAC5D;AAED,oFAAoF;AACpF,eAAO,MAAM,iCAAiC;;;;iBAI5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC"}

package/dist/esm/external-providers/provider-authentication-assurance.shared.schemas.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/** Policy for an otherwise valid external login that cannot demonstrate required MFA. */
+export var ExternalAssuranceEnforcement;
+(function (ExternalAssuranceEnforcement) {
+    ExternalAssuranceEnforcement["WARN"] = "warn";
+    ExternalAssuranceEnforcement["STRICT"] = "strict";
+})(ExternalAssuranceEnforcement || (ExternalAssuranceEnforcement = {}));
+/** Do not collapse contractual delegation, measured MFA and warning admission into one boolean. */
+export var ExternalAssuranceDecision;
+(function (ExternalAssuranceDecision) {
+    ExternalAssuranceDecision["NOT_REQUIRED"] = "not_required";
+    ExternalAssuranceDecision["DELEGATED"] = "delegated";
+    ExternalAssuranceDecision["VERIFIED_MFA"] = "verified_mfa";
+    ExternalAssuranceDecision["WARNED"] = "warned";
+    ExternalAssuranceDecision["REFUSED"] = "refused";
+})(ExternalAssuranceDecision || (ExternalAssuranceDecision = {}));
+export var ExternalAssuranceReason;
+(function (ExternalAssuranceReason) {
+    ExternalAssuranceReason["POLICY_NOT_REQUIRED"] = "policy_not_required";
+    ExternalAssuranceReason["ENTERPRISE_DELEGATION"] = "enterprise_delegation";
+    ExternalAssuranceReason["SESSION_MFA"] = "session_mfa";
+    ExternalAssuranceReason["EVIDENCE_MISSING"] = "evidence_missing";
+    ExternalAssuranceReason["EVIDENCE_INSUFFICIENT"] = "evidence_insufficient";
+    ExternalAssuranceReason["METHOD_REQUIREMENT_UNPROVEN"] = "method_requirement_unproven";
+})(ExternalAssuranceReason || (ExternalAssuranceReason = {}));
+/** Safe decision summary: no upstream token, raw claims, nonce, or user profile. */
+export const ExternalAssuranceAssessmentSchema = z.object({
+    decision: z.enum(ExternalAssuranceDecision),
+    reason: z.enum(ExternalAssuranceReason),
+    enforcement: z.enum(ExternalAssuranceEnforcement),
+});
+//# sourceMappingURL=provider-authentication-assurance.shared.schemas.js.map

package/dist/esm/external-providers/provider-authentication-assurance.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-authentication-assurance.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,MAAM,CAAN,IAAY,4BAGX;AAHD,WAAY,4BAA4B;IACtC,6CAAa,CAAA;IACb,iDAAiB,CAAA;AACnB,CAAC,EAHW,4BAA4B,KAA5B,4BAA4B,QAGvC;AAED,mGAAmG;AACnG,MAAM,CAAN,IAAY,yBAMX;AAND,WAAY,yBAAyB;IACnC,0DAA6B,CAAA;IAC7B,oDAAuB,CAAA;IACvB,0DAA6B,CAAA;IAC7B,8CAAiB,CAAA;IACjB,gDAAmB,CAAA;AACrB,CAAC,EANW,yBAAyB,KAAzB,yBAAyB,QAMpC;AACD,MAAM,CAAN,IAAY,uBAOX;AAPD,WAAY,uBAAuB;IACjC,sEAA2C,CAAA;IAC3C,0EAA+C,CAAA;IAC/C,sDAA2B,CAAA;IAC3B,gEAAqC,CAAA;IACrC,0EAA+C,CAAA;IAC/C,sFAA2D,CAAA;AAC7D,CAAC,EAPW,uBAAuB,KAAvB,uBAAuB,QAOlC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACvC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC;CAClD,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/** Policy for an otherwise valid external login that cannot demonstrate required MFA. */\nexport enum ExternalAssuranceEnforcement {\n  WARN = 'warn',\n  STRICT = 'strict',\n}\n\n/** Do not collapse contractual delegation, measured MFA and warning admission into one boolean. */\nexport enum ExternalAssuranceDecision {\n  NOT_REQUIRED = 'not_required',\n  DELEGATED = 'delegated',\n  VERIFIED_MFA = 'verified_mfa',\n  WARNED = 'warned',\n  REFUSED = 'refused',\n}\nexport enum ExternalAssuranceReason {\n  POLICY_NOT_REQUIRED = 'policy_not_required',\n  ENTERPRISE_DELEGATION = 'enterprise_delegation',\n  SESSION_MFA = 'session_mfa',\n  EVIDENCE_MISSING = 'evidence_missing',\n  EVIDENCE_INSUFFICIENT = 'evidence_insufficient',\n  METHOD_REQUIREMENT_UNPROVEN = 'method_requirement_unproven',\n}\n\n/** Safe decision summary: no upstream token, raw claims, nonce, or user profile. */\nexport const ExternalAssuranceAssessmentSchema = z.object({\n  decision: z.enum(ExternalAssuranceDecision),\n  reason: z.enum(ExternalAssuranceReason),\n  enforcement: z.enum(ExternalAssuranceEnforcement),\n});\nexport type ExternalAssuranceAssessment = z.infer<typeof ExternalAssuranceAssessmentSchema>;\n"]}

package/dist/esm/external-providers/provider-browser-operations.shared.schemas.d.ts

@@ -0,0 +1,139 @@
+/**
+ * WHICH provider operations a signed-in person's browser may trigger — the application's decision (#367).
+ *
+ * ## The question this answers, and why nothing else did
+ *
+ * A provider operation runs on the backend, through `ProviderOperationExecutorBackendService`, because
+ * the credential it spends must never travel to a browser. A custom backend service reaches it through
+ * a generated typed client. A custom FRONTEND component had no way to reach it at all, and the door
+ * that gives it one has to answer a question no existing engine surface answers: *which operations may
+ * a browser trigger, for whom, and on whose account*.
+ *
+ * The answer is a DECLARATION, authored in the application's SaaS config beside `providers.connections`
+ * and with the same standing: both are the application's decisions about providers, as opposed to what
+ * a vendor's catalogue says it can support.
+ *
+ * ## Fail closed, by construction
+ *
+ * An operation absent from this map is NOT reachable from a browser. There is no default, no
+ * "READ operations are fine" shortcut — classification is not sufficient: a READ still spends a tenant's
+ * credential, can page a vendor's whole account, and returns whatever the vendor holds. The map is the
+ * only thing that opens the door, one operation at a time.
+ *
+ * ## Rejected: a flag on the operation in the provider catalogue
+ *
+ * The catalogue is generated from third-party sources and overwritten on every regeneration, and it
+ * describes the VENDOR. Letting it decide what a browser may trigger would let a scraped listing grant
+ * access in every application that installs the provider — and a regeneration could grant or revoke it
+ * without anyone opening the application.
+ */
+import { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
+import { z } from 'zod';
+import { type RateLimitConfiguration } from '../requests/rate-limits.shared.schemas';
+/** @wildo_source:part:start saas.models.providers.browser-operation-policy facet:layer:shared facet:family:config facet:audience:app-developer */
+/**
+ * One browser-reachable operation.
+ *
+ * ## `connections` — whose account a browser-triggered call may spend
+ *
+ * Owner-scope × delegation pairs, in the vocabulary the catalogue, `providers.connections`, the connect
+ * leg and the resolver already share. NARROWING ONLY: a call must satisfy this list AND the provider's
+ * admissible connections as `providers.connections` narrows them. Naming a shape the provider does not
+ * admit grants nothing.
+ *
+ * Every call still passes the target-authorization port before anything is spent — a person may name
+ * only an organization they belong to organization-wide, and only their own user account. This list
+ * narrows further; it can never widen what that port allows.
+ *
+ * ## `allowedRoles` — who may trigger it
+ *
+ * Role keys, resolved through the LIVE role hierarchy (a custom role inheriting from a listed one
+ * qualifies), and read in the scope of the ACCOUNT BEING SPENT:
+ *
+ * | target | roles are read from |
+ * |---|---|
+ * | `organization` | the caller's organization-WIDE roles in THAT organization — a unit-scoped grant never counts |
+ * | `application` | the caller's application roles |
+ * | `user` | not applicable — a person acting on their own account holds no role over it, so declaring roles on a policy that admits `user` refuses those calls |
+ *
+ * Absent means any signed-in caller the target-authorization port admits. That is a legitimate choice
+ * for a person's own account or a member acting for their own tenant, and it is REFUSED at parse time
+ * when the policy admits an `application`-owned connection: without roles, every signed-in person could
+ * spend the application's own vendor account.
+ *
+ * ## `callerRateLimit` — how often ONE person may trigger it (#561)
+ *
+ * Counted per signed-in person, per provider operation. Before it, the door's only limits were a
+ * per-provider window (off unless a provider declared one) and the IP-keyed perimeter limiter, so one
+ * person's typing into an address lookup could spend a vendor allowance the whole application shares.
+ *
+ * Absent does NOT mean unlimited: the framework applies
+ * {@link DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT}, generous enough for a person typing into a
+ * lookup. The two differ in one way that matters, and it is the same split the rest of the engine draws
+ * between an authored and a default limit: a DECLARED limit fails CLOSED when the limiter's store is
+ * unavailable (the application stated it, so an outage must not quietly lift it), while the framework
+ * default fails OPEN (nobody declared it, so it must never be why a door stops working).
+ */
+export declare const ProviderBrowserOperationPolicySchema: z.ZodObject<{
+    connections: z.ZodArray<z.ZodObject<{
+        ownerScope: z.ZodEnum<typeof ExternalProvider_Connection_OwnerScope>;
+        delegation: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ExternalProvider_Connection_DelegationMode>>;
+    }, z.core.$strip>>;
+    allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    callerRateLimit: z.ZodOptional<z.ZodObject<{
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type ProviderBrowserOperationPolicy = z.infer<typeof ProviderBrowserOperationPolicySchema>;
+/**
+ * The per-person limit a browser-reachable operation gets when its policy declares none (#561).
+ *
+ * Sized for the most frequent legitimate caller, a person typing into an address lookup: suggestions start at
+ * three characters and are debounced, so one address is a handful of calls, and sixty a minute is a person
+ * typing without pause. The hourly window is what stops a script holding a session from draining a vendor
+ * allowance at a steady sixty a minute.
+ */
+export declare const DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT: RateLimitConfiguration;
+/** Where the limit a browser-triggered call is counted against came from — and so how an outage of the limiter is treated. */
+export declare enum ProviderBrowserOperationCallerRateLimitSource {
+    /** Declared on the policy: fails CLOSED on a limiter outage. */
+    DECLARED = "DECLARED",
+    /** The framework default: fails OPEN on a limiter outage. */
+    FRAMEWORK_DEFAULT = "FRAMEWORK_DEFAULT"
+}
+/** The one reading of a policy's per-person limit: its own, or the framework default, and which. */
+export declare function resolveProviderBrowserOperationCallerRateLimit(policy: Pick<ProviderBrowserOperationPolicy, 'callerRateLimit'>): {
+    readonly limit: RateLimitConfiguration;
+    readonly source: ProviderBrowserOperationCallerRateLimitSource;
+};
+/**
+ * `providerRef` → `operationId` → policy. The operation id is the catalogue's own, exactly as a typed
+ * client or an ETL binding reference names it.
+ *
+ * Absent is an EMPTY map — nothing is browser-reachable — never "everything".
+ */
+export declare const ProviderBrowserOperationPoliciesSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+    connections: z.ZodArray<z.ZodObject<{
+        ownerScope: z.ZodEnum<typeof ExternalProvider_Connection_OwnerScope>;
+        delegation: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ExternalProvider_Connection_DelegationMode>>;
+    }, z.core.$strip>>;
+    allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    callerRateLimit: z.ZodOptional<z.ZodObject<{
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>>>>;
+export type ProviderBrowserOperationPolicies = z.infer<typeof ProviderBrowserOperationPoliciesSchema>;
+/** @wildo_source:part:end saas.models.providers.browser-operation-policy */
+//# sourceMappingURL=provider-browser-operations.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-browser-operations.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-browser-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-browser-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,sCAAsC,EAEvC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAEnH,kJAAkJ;AAClJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;kBAiC/C,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAElG;;;;;;;GAOG;AACH,eAAO,MAAM,oDAAoD,EAAE,sBAGjE,CAAC;AAEH,8HAA8H;AAC9H,oBAAY,6CAA6C;IACvD,gEAAgE;IAChE,QAAQ,aAAa;IACrB,6DAA6D;IAC7D,iBAAiB,sBAAsB;CACxC;AAED,oGAAoG;AACpG,wBAAgB,8CAA8C,CAAC,MAAM,EAAE,IAAI,CAAC,8BAA8B,EAAE,iBAAiB,CAAC,GAAG;IAC/H,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,6CAA6C,CAAC;CAChE,CAIA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;qBAG9B,CAAC;AACtB,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AACtG,4EAA4E"}