@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/external-providers/provider-frontend-component-contract.shared.types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The contract between a provider's frontend COMPONENT and the framework surface
+ * that mounts it.
+ *
+ * ## Why it lives here and not beside the module types it serves
+ *
+ * These types were written in `@wildo-ai/external-connectors-public`, next to the
+ * facet module types that declare a component — which reads as the right place
+ * until you follow what depends on what:
+ *
+ *   - a component lives in its own package (`@wildo-ai/providers-frontend-<vendor>`,
+ *     issue #394) because it carries React, which the connectors package must not;
+ *   - that package needs this contract to type its component;
+ *   - the connectors package needs to RESOLVE that package, because it reaches the
+ *     component by a bare dynamic import.
+ *
+ * With the contract in the connectors package that is a cycle *through emitted
+ * declarations*: the component package's `.d.ts` references the connectors
+ * package's `.d.ts`, which makes the connectors package's own `dist` an INPUT of
+ * its own build. Measured, not predicted — `tsc` refuses with `TS5055 Cannot
+ * write file … because it would overwrite input file`, once per emitted
+ * declaration.
+ *
+ * So the contract belongs BELOW both, and `saas-models` is where "below both"
+ * already is.
+ *
+ * ## Why function-valued types are allowed in this package
+ *
+ * The sibling `provider-frontend-surface.shared.schemas.ts` states that
+ * everything in it is the DATA half, and that nothing function-valued may join
+ * it. That rule is about VALUES crossing a JSON channel — a projected `activate`
+ * would be dropped by `JSON.stringify` with no error anywhere. A TYPE crosses
+ * nothing. `onSelect` here is a compile-time obligation on two parties, and it
+ * never appears in a wire record.
+ *
+ * `File` is a DOM type, which this package already uses
+ * (`files.shared.utils.ts`), so nothing new is required of its lib.
+ */
+import type { ProviderFrontendSelectionDelivery } from './provider-frontend-surface.shared.schemas';
+/**
+ * What a provider's file picker hands back for ONE chosen file.
+ *
+ * The three arms are the three answers to issue #383, and the union exists
+ * because the decision was **per vendor**: a picker for a credentialed vendor and
+ * a picker for a vendor with a browser-safe public token genuinely cannot return
+ * the same thing, and both must ship.
+ *
+ * `kind` is not a runtime choice. Each arm corresponds to exactly one
+ * `ProviderFrontendSelectionDelivery`, the provider DECLARES which one it emits,
+ * and the framework refuses a selection whose `kind` contradicts that
+ * declaration. Without the refusal the union would be the hedge the decision
+ * rejected — a contract that says "one of these three, we will find out at
+ * runtime" is not one an application's file field can be written against.
+ */
+export type ProviderFileSelection = {
+    /** @see ProviderFrontendSelectionDelivery.REMOTE_REFERENCE */
+    readonly kind: ProviderFrontendSelectionDelivery.REMOTE_REFERENCE;
+    /** Opaque to everything in the browser. Only the application backend can resolve it. */
+    readonly externalId: string;
+    /** What to show the user before the backend has resolved anything. */
+    readonly displayName?: string;
+    readonly mimeType?: string;
+    readonly sizeBytes?: number;
+} | {
+    /** @see ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE */
+    readonly kind: ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE;
+    readonly file: File;
+} | {
+    /** @see ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL */
+    readonly kind: ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL;
+    /** Fetchable by the browser. Its origin must be admitted by the surface's composed CSP. */
+    readonly url: string;
+    readonly displayName?: string;
+    readonly mimeType?: string;
+    readonly sizeBytes?: number;
+};
+/**
+ * The constraints a framework file field imposes on a picker.
+ *
+ * Resolved by the framework — schema metadata first, then the provider's own
+ * `publicConfig` through the capability's named schema — so a picker never
+ * re-reads either. `maxSize` is BYTES; a provider stating megabytes in its public
+ * config (`maxFileSizeMb`) is converted before it reaches here.
+ *
+ * ## Why the field names are these and not clearer ones
+ *
+ * They are the framework file field's OWN names:
+ * `resolveFormFieldFileProviderConstraints` in `@wildo-ai/saas-frontend-lib`
+ * produces exactly this shape and its `ResolvedFormFieldFileProviderConstraints`
+ * is an alias of this type, so there is one source rather than two spellings of
+ * one contract.
+ *
+ * That is not tidiness. The first draft called the size cap `maxSizeBytes` while
+ * the resolver called it `maxSize` — both BYTES, both optional — and TypeScript
+ * accepts the assignment: the weak-type check is satisfied by the two names that
+ * DO match, so wiring the resolver into a picker would have compiled and silently
+ * dropped the size cap. A picker would then accept files the field rejects, and
+ * the user finds out after choosing one.
+ */
+export interface ProviderFilePickerConstraints {
+    /**
+     * A MUTABLE array, deliberately: `@wildo-ai/zod-decorators`' MIME helpers
+     * (`isMimeTypeAllowed`, `buildAcceptAttribute`) take `string[]`, and this
+     * type's whole reason for existing is to BE the framework file field's own
+     * shape rather than a second one. A `readonly string[]` here would be a better
+     * type in isolation and would force a cast at every one of those call sites,
+     * which is how the drift this type prevents starts again.
+     */
+    allowedMimeTypes?: string[];
+    /** BYTES, not megabytes. */
+    maxSize?: number;
+    maxFiles?: number;
+}
+/**
+ * The props every `FRONTEND_FILE_PICKER` component receives.
+ *
+ * `onSelect` takes an ARRAY even for a single-file field. A picker that supports
+ * multi-select otherwise needs a second callback or a hidden convention, and a
+ * field that allows one file can reject a second selection with a message instead
+ * of silently keeping whichever arrived first — which is what a single-value
+ * callback forces it to do.
+ */
+export interface ProviderFilePickerProps {
+    /** The provider's own `ref`, so a picker can label what it renders without being told twice. */
+    readonly providerRef: string;
+    /**
+     * The provider's public configuration, already validated against the module's
+     * `publicConfigSchema` when it declares one. A picker never re-coerces it.
+     */
+    readonly publicConfig: Readonly<Record<string, unknown>>;
+    readonly constraints: ProviderFilePickerConstraints;
+    /**
+     * An access token for THIS provider, on behalf of the current user, when the
+     * application has one.
+     *
+     * Optional, and its absence is a real state rather than a defect: a picker that
+     * authenticates through its own vendor popup (OneDrive's does) needs nothing
+     * here, and an application that has not connected a user's account to this
+     * provider has nothing to give. A picker that does need one must call this and
+     * report through `onError` when it is absent — never fall back to a token from
+     * `publicConfig`, which is served to every browser.
+     *
+     * Supplying it is the account-connection surface's job (issue #333), which does
+     * not exist yet; until it does, the framework passes nothing and a picker that
+     * requires a token says so. The prop is declared now so that the dependency is
+     * VISIBLE in the contract rather than discovered by whoever writes the second
+     * picker.
+     */
+    getAccessToken?(): Promise<string | undefined>;
+    /**
+     * Called with everything the user chose. May be called once with several files;
+     * must not be called after `onCancel`.
+     */
+    onSelect(selections: readonly ProviderFileSelection[]): void;
+    /** The user dismissed the picker without choosing. */
+    onCancel(): void;
+    /**
+     * The picker could not run — the vendor SDK failed to load, a grant was
+     * refused, the vendor returned an error. Reported rather than thrown: a throw
+     * inside a picker's own event handler does not reach a React error boundary, so
+     * it would be a surface that silently stops responding.
+     */
+    onError(error: Error): void;
+}
+//# sourceMappingURL=provider-frontend-component-contract.shared.types.d.ts.map

package/dist/esm/external-providers/provider-frontend-component-contract.shared.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-frontend-component-contract.shared.types.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-frontend-component-contract.shared.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,4CAA4C,CAAC;AAEpG;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IACA,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,gBAAgB,CAAC;IAClE,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GACC;IACA,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,qBAAqB,CAAC;IACvE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB,GACC;IACA,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,oBAAoB,CAAC;IACtE,2FAA2F;IAC3F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,WAAW,EAAE,6BAA6B,CAAC;IACpD;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,GAAG,IAAI,CAAC;IAC7D,sDAAsD;IACtD,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC7B"}

package/dist/esm/external-providers/provider-frontend-component-contract.shared.types.js

@@ -0,0 +1,39 @@
+/**
+ * The contract between a provider's frontend COMPONENT and the framework surface
+ * that mounts it.
+ *
+ * ## Why it lives here and not beside the module types it serves
+ *
+ * These types were written in `@wildo-ai/external-connectors-public`, next to the
+ * facet module types that declare a component — which reads as the right place
+ * until you follow what depends on what:
+ *
+ *   - a component lives in its own package (`@wildo-ai/providers-frontend-<vendor>`,
+ *     issue #394) because it carries React, which the connectors package must not;
+ *   - that package needs this contract to type its component;
+ *   - the connectors package needs to RESOLVE that package, because it reaches the
+ *     component by a bare dynamic import.
+ *
+ * With the contract in the connectors package that is a cycle *through emitted
+ * declarations*: the component package's `.d.ts` references the connectors
+ * package's `.d.ts`, which makes the connectors package's own `dist` an INPUT of
+ * its own build. Measured, not predicted — `tsc` refuses with `TS5055 Cannot
+ * write file … because it would overwrite input file`, once per emitted
+ * declaration.
+ *
+ * So the contract belongs BELOW both, and `saas-models` is where "below both"
+ * already is.
+ *
+ * ## Why function-valued types are allowed in this package
+ *
+ * The sibling `provider-frontend-surface.shared.schemas.ts` states that
+ * everything in it is the DATA half, and that nothing function-valued may join
+ * it. That rule is about VALUES crossing a JSON channel — a projected `activate`
+ * would be dropped by `JSON.stringify` with no error anywhere. A TYPE crosses
+ * nothing. `onSelect` here is a compile-time obligation on two parties, and it
+ * never appears in a wire record.
+ *
+ * `File` is a DOM type, which this package already uses
+ * (`files.shared.utils.ts`), so nothing new is required of its lib.
+ */
+//# sourceMappingURL=provider-frontend-component-contract.shared.types.js.map

package/dist/esm/external-providers/provider-frontend-component-contract.shared.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-frontend-component-contract.shared.types.js","sourceRoot":"","sources":["../../../src/external-providers/provider-frontend-component-contract.shared.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG","sourcesContent":["/**\n * The contract between a provider's frontend COMPONENT and the framework surface\n * that mounts it.\n *\n * ## Why it lives here and not beside the module types it serves\n *\n * These types were written in `@wildo-ai/external-connectors-public`, next to the\n * facet module types that declare a component — which reads as the right place\n * until you follow what depends on what:\n *\n *   - a component lives in its own package (`@wildo-ai/providers-frontend-<vendor>`,\n *     issue #394) because it carries React, which the connectors package must not;\n *   - that package needs this contract to type its component;\n *   - the connectors package needs to RESOLVE that package, because it reaches the\n *     component by a bare dynamic import.\n *\n * With the contract in the connectors package that is a cycle *through emitted\n * declarations*: the component package's `.d.ts` references the connectors\n * package's `.d.ts`, which makes the connectors package's own `dist` an INPUT of\n * its own build. Measured, not predicted — `tsc` refuses with `TS5055 Cannot\n * write file … because it would overwrite input file`, once per emitted\n * declaration.\n *\n * So the contract belongs BELOW both, and `saas-models` is where \"below both\"\n * already is.\n *\n * ## Why function-valued types are allowed in this package\n *\n * The sibling `provider-frontend-surface.shared.schemas.ts` states that\n * everything in it is the DATA half, and that nothing function-valued may join\n * it. That rule is about VALUES crossing a JSON channel — a projected `activate`\n * would be dropped by `JSON.stringify` with no error anywhere. A TYPE crosses\n * nothing. `onSelect` here is a compile-time obligation on two parties, and it\n * never appears in a wire record.\n *\n * `File` is a DOM type, which this package already uses\n * (`files.shared.utils.ts`), so nothing new is required of its lib.\n */\n\nimport type { ProviderFrontendSelectionDelivery } from './provider-frontend-surface.shared.schemas';\n\n/**\n * What a provider's file picker hands back for ONE chosen file.\n *\n * The three arms are the three answers to issue #383, and the union exists\n * because the decision was **per vendor**: a picker for a credentialed vendor and\n * a picker for a vendor with a browser-safe public token genuinely cannot return\n * the same thing, and both must ship.\n *\n * `kind` is not a runtime choice. Each arm corresponds to exactly one\n * `ProviderFrontendSelectionDelivery`, the provider DECLARES which one it emits,\n * and the framework refuses a selection whose `kind` contradicts that\n * declaration. Without the refusal the union would be the hedge the decision\n * rejected — a contract that says \"one of these three, we will find out at\n * runtime\" is not one an application's file field can be written against.\n */\nexport type ProviderFileSelection =\n  | {\n    /** @see ProviderFrontendSelectionDelivery.REMOTE_REFERENCE */\n    readonly kind: ProviderFrontendSelectionDelivery.REMOTE_REFERENCE;\n    /** Opaque to everything in the browser. Only the application backend can resolve it. */\n    readonly externalId: string;\n    /** What to show the user before the backend has resolved anything. */\n    readonly displayName?: string;\n    readonly mimeType?: string;\n    readonly sizeBytes?: number;\n  }\n  | {\n    /** @see ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE */\n    readonly kind: ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE;\n    readonly file: File;\n  }\n  | {\n    /** @see ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL */\n    readonly kind: ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL;\n    /** Fetchable by the browser. Its origin must be admitted by the surface's composed CSP. */\n    readonly url: string;\n    readonly displayName?: string;\n    readonly mimeType?: string;\n    readonly sizeBytes?: number;\n  };\n\n/**\n * The constraints a framework file field imposes on a picker.\n *\n * Resolved by the framework — schema metadata first, then the provider's own\n * `publicConfig` through the capability's named schema — so a picker never\n * re-reads either. `maxSize` is BYTES; a provider stating megabytes in its public\n * config (`maxFileSizeMb`) is converted before it reaches here.\n *\n * ## Why the field names are these and not clearer ones\n *\n * They are the framework file field's OWN names:\n * `resolveFormFieldFileProviderConstraints` in `@wildo-ai/saas-frontend-lib`\n * produces exactly this shape and its `ResolvedFormFieldFileProviderConstraints`\n * is an alias of this type, so there is one source rather than two spellings of\n * one contract.\n *\n * That is not tidiness. The first draft called the size cap `maxSizeBytes` while\n * the resolver called it `maxSize` — both BYTES, both optional — and TypeScript\n * accepts the assignment: the weak-type check is satisfied by the two names that\n * DO match, so wiring the resolver into a picker would have compiled and silently\n * dropped the size cap. A picker would then accept files the field rejects, and\n * the user finds out after choosing one.\n */\nexport interface ProviderFilePickerConstraints {\n  /**\n   * A MUTABLE array, deliberately: `@wildo-ai/zod-decorators`' MIME helpers\n   * (`isMimeTypeAllowed`, `buildAcceptAttribute`) take `string[]`, and this\n   * type's whole reason for existing is to BE the framework file field's own\n   * shape rather than a second one. A `readonly string[]` here would be a better\n   * type in isolation and would force a cast at every one of those call sites,\n   * which is how the drift this type prevents starts again.\n   */\n  allowedMimeTypes?: string[];\n  /** BYTES, not megabytes. */\n  maxSize?: number;\n  maxFiles?: number;\n}\n\n/**\n * The props every `FRONTEND_FILE_PICKER` component receives.\n *\n * `onSelect` takes an ARRAY even for a single-file field. A picker that supports\n * multi-select otherwise needs a second callback or a hidden convention, and a\n * field that allows one file can reject a second selection with a message instead\n * of silently keeping whichever arrived first — which is what a single-value\n * callback forces it to do.\n */\nexport interface ProviderFilePickerProps {\n  /** The provider's own `ref`, so a picker can label what it renders without being told twice. */\n  readonly providerRef: string;\n  /**\n   * The provider's public configuration, already validated against the module's\n   * `publicConfigSchema` when it declares one. A picker never re-coerces it.\n   */\n  readonly publicConfig: Readonly<Record<string, unknown>>;\n  readonly constraints: ProviderFilePickerConstraints;\n  /**\n   * An access token for THIS provider, on behalf of the current user, when the\n   * application has one.\n   *\n   * Optional, and its absence is a real state rather than a defect: a picker that\n   * authenticates through its own vendor popup (OneDrive's does) needs nothing\n   * here, and an application that has not connected a user's account to this\n   * provider has nothing to give. A picker that does need one must call this and\n   * report through `onError` when it is absent — never fall back to a token from\n   * `publicConfig`, which is served to every browser.\n   *\n   * Supplying it is the account-connection surface's job (issue #333), which does\n   * not exist yet; until it does, the framework passes nothing and a picker that\n   * requires a token says so. The prop is declared now so that the dependency is\n   * VISIBLE in the contract rather than discovered by whoever writes the second\n   * picker.\n   */\n  getAccessToken?(): Promise<string | undefined>;\n  /**\n   * Called with everything the user chose. May be called once with several files;\n   * must not be called after `onCancel`.\n   */\n  onSelect(selections: readonly ProviderFileSelection[]): void;\n  /** The user dismissed the picker without choosing. */\n  onCancel(): void;\n  /**\n   * The picker could not run — the vendor SDK failed to load, a grant was\n   * refused, the vendor returned an error. Reported rather than thrown: a throw\n   * inside a picker's own event handler does not reach a React error boundary, so\n   * it would be a surface that silently stops responding.\n   */\n  onError(error: Error): void;\n}\n"]}

package/dist/esm/external-providers/provider-frontend-surface.shared.schemas.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Frontend-surface atoms a provider declares: what it needs the page to be
+ * ALLOWED to reach (its CSP footprint), which vendor SDK package it loads, and
+ * which third-party `<script>` tags it asks the surface to add.
+ *
+ * ## Why these are DATA and live here
+ *
+ * A frontend provider reaches its surface through TWO channels, and only one of
+ * them can carry code:
+ *
+ *   - the **DATA** channel — `FrontendProviderEntry`, projected by the backend
+ *     into `/application-config` and materialized into the generated
+ *     frontend-services artifact. It is JSON end to end, so nothing
+ *     function-valued survives it (it used to be cast to a module type anyway,
+ *     which is the defect this split closes);
+ *   - the **CODE** channel — the provider package's own facet barrel, imported
+ *     by the bundle through the generated `frontend-providers.generated.ts`.
+ *
+ * Everything in this file is the DATA half. It is what the CLI, the CSP
+ * composer and the bundle-isolation policy need to SEE without executing any
+ * frontend module — and the CLI genuinely cannot execute one: it is a Node
+ * process and these modules are browser-bound. The executable half (`sdk.activate`,
+ * `publicConfigSchema`) lives on the facet module types in
+ * `@wildo-ai/external-connectors-public` and never crosses this boundary.
+ *
+ * Added by slice S4a of epic #337 (issue #332).
+ */
+import { z } from 'zod';
+/**
+ * The origins a provider needs the composed Content-Security-Policy to admit,
+ * grouped by WHAT THE PROVIDER IS REACHING rather than by CSP directive name.
+ *
+ * ## Why semantic buckets and not directive names
+ *
+ * `CSP_DIRECTIVE_NAMES` is a closed vocabulary that already has one named
+ * runtime source, in `@wildo-ai/platform-config-lib`. That package DEPENDS on
+ * this one, so this file cannot reference it, and re-declaring the list here
+ * would create a second source for one vocabulary — precisely what the
+ * one-named-source rule exists to prevent, and the way the two copies would
+ * drift the first time a directive is added.
+ *
+ * Keying on intent instead is also the better contract. A provider author knows
+ * "my SDK is fetched from `https://js.stripe.com` and it calls back to
+ * `https://api.stripe.com`"; which directive grades which fetch is framework
+ * knowledge, and it lives in exactly one place — the bucket-to-directive
+ * mapping in `platform-config-lib`'s `csp-emit.ts`.
+ *
+ * ## Why it is STRICT while the entry that carries it is loose
+ *
+ * The entry is a WIRE record read by a possibly-older consumer, so it tolerates
+ * unknown keys (see `frontend-provider-entry.shared.schemas.ts`). This footprint
+ * is AUTHORED, by a provider package, and validated where it is authored — so a
+ * misspelled bucket must fail loudly rather than contribute nothing. That
+ * distinction matters more here than anywhere else in the frontend surface:
+ * CSP is enforced in production and report-only in development, so a bucket that
+ * silently contributes nothing is invisible until the provider breaks in
+ * production only.
+ *
+ * Adding a bucket is not a one-sided producer change either — a new bucket is
+ * useless until `csp-emit.ts` maps it to a directive — so strictness costs no
+ * version-skew tolerance that was ever available.
+ *
+ * Every field defaults to `[]`: a provider that declares a footprint at all is
+ * making a complete statement about the buckets it did not name.
+ */
+/**
+ * Which bucket an origin lands in, as a value a provider can name.
+ *
+ * The bucket names are already the footprint's field names; this enum is what
+ * lets a provider REFER to one — a derived origin has to say where it goes, and
+ * a bare string there would be a second, unexplained spelling of a closed
+ * vocabulary. A compile-time check below pins the two together.
+ */
+export declare enum ProviderFrontendCspOriginBucket {
+    SCRIPT = "scriptOrigins",
+    CONNECT = "connectOrigins",
+    FRAME = "frameOrigins",
+    IMG = "imgOrigins",
+    STYLE = "styleOrigins",
+    FONT = "fontOrigins"
+}
+/**
+ * An origin the framework must READ OUT OF the provider's own public config,
+ * because the provider cannot know it.
+ *
+ * The case that forced this: an error-monitoring provider sends to the host
+ * inside its DSN, and a product-analytics provider to whatever `apiHost` the
+ * application configured — including a self-hosted one. Both are per
+ * APPLICATION, and often per ENVIRONMENT, so no static list on the provider
+ * module can contain them. Without this the application would have to author
+ * the same host twice — once as the provider's config and once in its CSP — and
+ * the copy that drifts fails in production only, because development is
+ * report-only.
+ *
+ * Resolution is data, not code: the CLI takes `publicConfig[publicConfigKey]`,
+ * reads its URL origin, and adds it to `bucket`. An absent key contributes
+ * nothing (the provider simply is not configured for that service); a key that
+ * is present and is NOT a URL fails the sync loudly, because silently dropping
+ * it is the exact failure this exists to prevent.
+ */
+export declare const ProviderFrontendCspDerivedOriginSchema: z.ZodObject<{
+    /** Key in this provider's `publicConfig` whose value is a URL. */
+    publicConfigKey: z.ZodString;
+    bucket: z.ZodEnum<typeof ProviderFrontendCspOriginBucket>;
+}, z.core.$strict>;
+export type ProviderFrontendCspDerivedOrigin = z.infer<typeof ProviderFrontendCspDerivedOriginSchema>;
+export declare const ProviderFrontendCspFootprintSchema: z.ZodObject<{
+    /** Origins the surface loads executable script from (`script-src`). */
+    scriptOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Origins the provider's code opens fetch / XHR / WebSocket connections to (`connect-src`). */
+    connectOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Origins the provider embeds in an iframe — a picker, a checkout, a meeting (`frame-src`). */
+    frameOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Origins the provider loads images or pixels from (`img-src`). */
+    imgOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Origins the provider loads stylesheets from (`style-src`). */
+    styleOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Origins the provider loads web fonts from (`font-src`). */
+    fontOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /**
+     * Origins the framework reads out of this provider's own `publicConfig`,
+     * for the endpoints a provider cannot know in advance. See
+     * {@link ProviderFrontendCspDerivedOriginSchema}.
+     */
+    derivedOrigins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Key in this provider's `publicConfig` whose value is a URL. */
+        publicConfigKey: z.ZodString;
+        bucket: z.ZodEnum<typeof ProviderFrontendCspOriginBucket>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ProviderFrontendCspFootprint = z.infer<typeof ProviderFrontendCspFootprintSchema>;
+/**
+ * The footprint as a provider AUTHORS it: name only the buckets you reach.
+ *
+ * Authoring and the wire are deliberately different shapes, and the asymmetry
+ * is the point.
+ *
+ *   - **Authoring is partial.** A provider that only loads a script should write
+ *     `{ scriptOrigins: ['https://js.acme.com'] }`, not that plus four empty
+ *     arrays. Four empty arrays are noise at exactly the place the declaration
+ *     should be readable, and noise is what stops a reviewer noticing the one
+ *     line that grants an origin.
+ *   - **The wire is total.** Every bucket is present by the time the footprint
+ *     reaches an entry, so the CSP composer never branches on absence and the
+ *     staleness comparison between a served footprint and its module's has two
+ *     comparable shapes rather than a partial and a total that differ in every
+ *     bucket nobody named.
+ *
+ * Derived as `z.input` rather than written as a `Partial<…>`, so it cannot drift
+ * from the schema: adding a bucket makes it optional here automatically.
+ */
+export type ProviderFrontendCspFootprintDeclaration = z.input<typeof ProviderFrontendCspFootprintSchema>;
+/**
+ * Fills in the buckets a declaration did not name.
+ *
+ * The ONE place that normalization happens, used by the projection that builds
+ * an entry and by the hydration join that compares one against a module. Two
+ * copies would eventually disagree about whether an unnamed bucket is `[]` or
+ * absent, and the join reads that difference as a stale artifact — a false
+ * alarm on the diagnostic whose whole job is to be believed.
+ */
+export declare function normalizeProviderFrontendCspFootprint(declaration: ProviderFrontendCspFootprintDeclaration): ProviderFrontendCspFootprint;
+/**
+ * The DATA half of a provider's `sdk` declaration: WHICH npm package carries the
+ * vendor SDK, and at which range.
+ *
+ * The CODE half — the dynamic import and the vendor's initialization call — is
+ * `ProviderFrontendSdk.activate` on the facet module type, and is deliberately
+ * absent here: a function cannot cross a JSON channel, and a channel that
+ * silently drops one is worse than a channel that never carried it.
+ *
+ * The descriptor is not decoration. It is what the bundle-isolation policy reads
+ * to decide whether a bare specifier a provider package imports was DECLARED,
+ * what an application's dependency alignment needs in order to install the SDK
+ * as an optional peer, and what a human reads when asking why a bundle grew.
+ *
+ * Who authors it, since the epic's bulk-integration model was reversed on
+ * 2026-09-06: a FIRST-CLASS provider package or an application's own provider
+ * module. The scraper-mapper that fills the catalogue emits identity, auth, a
+ * secrets contract and an operation catalogue on the `rest` arm — a
+ * backend-only package — so a scraped provider has no frontend facet to carry
+ * this. That is a narrowing of the population, not of the contract: the pickers
+ * and embeds this surface exists for were always the hand-authored kind.
+ */
+export declare const ProviderFrontendSdkDescriptorSchema: z.ZodObject<{
+    /** npm package name of the vendor SDK, e.g. `@sentry/browser`. */
+    packageName: z.ZodString;
+    /**
+     * Semver range the provider was built against. Optional because a provider
+     * that pins its SDK as a direct dependency has already said so in its own
+     * manifest; stating it here as well would be a second copy of that pin.
+     */
+    versionRange: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProviderFrontendSdkDescriptor = z.infer<typeof ProviderFrontendSdkDescriptorSchema>;
+/**
+ * `crossorigin` attribute values for a provider-declared `<script>`.
+ *
+ * A closed vocabulary with a named runtime source rather than a bare literal
+ * union, so each member can carry why it exists — and there are exactly two
+ * reasons to pick one over the other.
+ */
+export declare enum ProviderFrontendScriptCrossOrigin {
+    /** No credentials are sent; the response must carry `Access-Control-Allow-Origin`. The right choice for a public CDN script. */
+    ANONYMOUS = "anonymous",
+    /** Cookies and TLS client certificates are sent. Only for a vendor that authenticates the script fetch itself. */
+    USE_CREDENTIALS = "use-credentials"
+}
+/**
+ * A third-party `<script>` a provider asks its surface to add — the case a
+ * dynamic `import()` cannot serve, because the vendor ships a global-installing
+ * tag rather than an npm module (reCAPTCHA, most tag managers, several chat
+ * widgets).
+ *
+ * `integrity` is Subresource Integrity. It is optional because a vendor that
+ * versionless-serves a mutable URL (again, reCAPTCHA) cannot publish a stable
+ * hash — but when it IS given the surface must also send `crossorigin`, or the
+ * browser refuses the integrity check outright. That coupling is enforced below
+ * rather than left to each surface to remember.
+ */
+export declare const ProviderFrontendScriptDeclarationSchema: z.ZodObject<{
+    /** Absolute URL of the script. Its origin must also appear in `csp.scriptOrigins`. */
+    src: z.ZodString;
+    /** Subresource-integrity hash, e.g. `sha384-…`. */
+    integrity: z.ZodOptional<z.ZodString>;
+    crossOrigin: z.ZodOptional<z.ZodEnum<typeof ProviderFrontendScriptCrossOrigin>>;
+    async: z.ZodOptional<z.ZodBoolean>;
+    defer: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ProviderFrontendScriptDeclaration = z.infer<typeof ProviderFrontendScriptDeclarationSchema>;
+/**
+ * WHAT a provider's component hands back, when what it hands back is a thing
+ * rather than a value.
+ *
+ * ## The question this answers, and why it is a DECLARATION
+ *
+ * An application's objective is that it calls third-party APIs directly from
+ * custom frontend components. On the backend that is unambiguous. In a browser
+ * it is not, because a tenant credential must never get there — so a picker for
+ * a credentialed vendor and a picker for a vendor with a browser-safe public
+ * token cannot hand back the same thing, and the framework surface that
+ * receives a selection has to know which before it mounts anything.
+ *
+ * Settled 2026-09-07 (issue #383, recorded as Q5 of the provider-architecture
+ * plan): **per vendor, DECLARED.** Both shapes are real and both ship; which one
+ * a provider emits is a static fact about that provider, stated here and
+ * visible on the DATA channel without executing a line of its code.
+ *
+ * The word doing the work is *declared*. A discriminated union alone would let a
+ * provider decide at runtime, which is the shape the decision explicitly
+ * rejected — so the framework REFUSES a selection whose discriminant contradicts
+ * this field. Without that refusal the declaration is decoration, and a reviewer
+ * reading a provider's manifest would be reading a wish.
+ *
+ * ## Why a single value and not a set
+ *
+ * A provider that genuinely could emit either — Google's Picker hands back both
+ * a file id and a URL, and which is usable depends on the granted OAuth scope —
+ * was the argument for `selectionDelivery: [...]`. Rejected: an array puts the
+ * choice back at runtime, which is the half of the decision that carries all the
+ * weight. A vendor whose two modes are both wanted contributes two components,
+ * and the chooser then shows them as what they are — two different things a user
+ * can pick between — rather than one component whose behaviour a reader cannot
+ * predict.
+ *
+ * ## What it means for CSP
+ *
+ * `REMOTE_REFERENCE` does NOT imply a provider needs no `connectOrigins`: a
+ * picker still talks to its vendor to RENDER, even when the bytes it selects are
+ * fetched later by the backend. So this field does not gate the CSP buckets, and
+ * a guard inferring otherwise would break every real picker. What it does gate
+ * is where the SELECTED OBJECT travels.
+ */
+export declare enum ProviderFrontendSelectionDelivery {
+    /**
+     * An opaque handle only the application backend can resolve — a Drive file id,
+     * a DAM asset key. The browser never holds the bytes and never authenticates
+     * to the vendor for them; the framework routes the reference to the
+     * application's executor door, which holds the tenant credential.
+     */
+    REMOTE_REFERENCE = "REMOTE_REFERENCE",
+    /**
+     * Bytes the browser already holds, as a `File`. Available only to a vendor
+     * whose picker runs on a browser-safe grant — a publishable key, a
+     * user-consented OAuth token, a picker's own scoped grant — so nothing
+     * tenant-secret is involved. The framework uploads it exactly as it uploads a
+     * file chosen from disk.
+     */
+    BROWSER_READABLE_FILE = "BROWSER_READABLE_FILE",
+    /**
+     * A URL the browser may fetch, under the same browser-safe-grant condition as
+     * `BROWSER_READABLE_FILE`. Distinct from it because the framework must fetch
+     * before it can upload, and that fetch is a network call the composed CSP has
+     * to admit — a difference the surface cannot discover from a `File`.
+     */
+    BROWSER_READABLE_URL = "BROWSER_READABLE_URL"
+}
+/**
+ * The DATA half of one component a provider contributes — everything about it
+ * that a reviewer, the CLI or a build step can read without running a browser.
+ *
+ * The loader is the CODE half and stays on the facet module in
+ * `@wildo-ai/external-connectors-public`, exactly as `sdk.activate` does. What
+ * crosses the wire is the fact that a component EXISTS for this capability, plus
+ * the contract it commits to.
+ *
+ * Strict, and for the same reason the CSP footprint is: this is AUTHORED by a
+ * provider package rather than received from an older producer, so a misspelled
+ * key must fail where it is written instead of contributing nothing.
+ */
+export declare const ProviderFrontendComponentDescriptorSchema: z.ZodObject<{
+    /**
+     * What a selection from this component contains. Absent for a capability whose
+     * component returns a plain value rather than a thing — a captcha widget hands
+     * back a token, and there is no delivery question to answer about a string.
+     */
+    selectionDelivery: z.ZodOptional<z.ZodEnum<typeof ProviderFrontendSelectionDelivery>>;
+}, z.core.$strict>;
+export type ProviderFrontendComponentDescriptor = z.infer<typeof ProviderFrontendComponentDescriptorSchema>;
+/**
+ * A provider's component descriptors, keyed by the CAPABILITY each fills.
+ *
+ * The key is a capability token rather than a member of a closed enum because
+ * `ProviderCapability` is OPEN — an application extends it by module
+ * augmentation — so a `z.enum` here would refuse an application's own
+ * capability. The registry that consumes this makes the same choice for the same
+ * reason.
+ */
+export declare const ProviderFrontendComponentDescriptorsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    /**
+     * What a selection from this component contains. Absent for a capability whose
+     * component returns a plain value rather than a thing — a captcha widget hands
+     * back a token, and there is no delivery question to answer about a string.
+     */
+    selectionDelivery: z.ZodOptional<z.ZodEnum<typeof ProviderFrontendSelectionDelivery>>;
+}, z.core.$strict>>;
+export type ProviderFrontendComponentDescriptors = z.infer<typeof ProviderFrontendComponentDescriptorsSchema>;
+//# sourceMappingURL=provider-frontend-surface.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-frontend-surface.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-frontend-surface.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-frontend-surface.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;;;;;;;GAOG;AACH,oBAAY,+BAA+B;IACzC,MAAM,kBAAkB;IACxB,OAAO,mBAAmB;IAC1B,KAAK,iBAAiB;IACtB,GAAG,eAAe;IAClB,KAAK,iBAAiB;IACtB,IAAI,gBAAgB;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC;IACjD,kEAAkE;;;kBAGlE,CAAC;AACH,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAEtG,eAAO,MAAM,kCAAkC;IAC7C,uEAAuE;;IAEvE,gGAAgG;;IAEhG,gGAAgG;;IAEhG,oEAAoE;;IAEpE,iEAAiE;;IAEjE,8DAA8D;;IAE9D;;;;OAIG;;QAvBH,kEAAkE;;;;kBAyBlE,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAEzG;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,uCAAuC,GACnD,4BAA4B,CAE9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mCAAmC;IAC9C,kEAAkE;;IAElE;;;;OAIG;;kBAEH,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG;;;;;;GAMG;AACH,oBAAY,iCAAiC;IAC3C,gIAAgI;IAChI,SAAS,cAAc;IACvB,kHAAkH;IAClH,eAAe,oBAAoB;CACpC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uCAAuC;IAEhD,sFAAsF;;IAEtF,mDAAmD;;;;;kBAgBnD,CAAC;AACL,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,oBAAY,iCAAiC;IAC3C;;;;;OAKG;IACH,gBAAgB,qBAAqB;IACrC;;;;;;OAMG;IACH,qBAAqB,0BAA0B;IAC/C;;;;;OAKG;IACH,oBAAoB,yBAAyB;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yCAAyC;IACpD;;;;OAIG;;kBAEH,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;AAE5G;;;;;;;;GAQG;AACH,eAAO,MAAM,0CAA0C;IAlBrD;;;;OAIG;;mBAiBJ,CAAC;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC"}