@wildo-ai/saas-models 1.1.1 → 1.1.3

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"}