@nodii/onboarding 0.0.1 → 0.1.0-dev.0

package/dist/model-IEyDI54w.d.ts

@@ -0,0 +1,487 @@
+import { z } from 'zod/v3';
+
+/**
+ * D540 §1 onboarding-spec model — mirrors the LOCKED hub REST contract:
+ *   GET /api/v1/public/onboarding/spec (PublicOnboardingSpecResponse)
+ *
+ * Response shape (hub JSON Schema, both tiers identical):
+ *   {
+ *     specVersion:   string (monotonic; echo on submit; stale ⇒ 409),
+ *     onboarderTier: "platform" | "tenant",
+ *     botChallenge:  { provider: "recaptcha", siteKey: string },
+ *     forms: {
+ *       contact: { fields: SpecField[] },
+ *       signup:  { steps: [{ stage: "lead"|"prospect"|"activation",
+ *                            fields: SpecField[] }] }
+ *     }
+ *   }
+ *
+ * SpecField (required: key, type, label, required):
+ *   { key, type, label, required, validation?, options?, serviceSelection?,
+ *     piiClass?: "none"|"context"|"always"|"reference" }
+ *
+ * The Zod schema below validates a fetched spec BEFORE the SDK renders
+ * anything from it — a malformed spec throws OnboardingSpecInvalidError
+ * (a half-parsed spec could silently drop required fields).
+ */
+
+type OnboarderTier = "platform" | "tenant";
+type PiiClass = "none" | "context" | "always" | "reference";
+type SpecStage = "lead" | "prospect" | "activation";
+type TerminalStage = "prospect" | "inactive" | "active";
+/**
+ * Field keys are interpolated into DOM element ids and (historically) CSS
+ * selectors by the widget layer. Constrain them to a strict identifier
+ * alphabet so a MALICIOUS or compromised onboarder spec cannot smuggle CSS
+ * metacharacters or selector-breakout payloads (e.g. `evil], [onclick=…`)
+ * through the fetched spec. A spec with an out-of-alphabet key is REJECTED
+ * at parse time → OnboardingSpecInvalidError (fail-closed; never rendered).
+ * This is layer 1; the widget also CSS.escapes ids as defense-in-depth.
+ */
+declare const FIELD_KEY_PATTERN: RegExp;
+declare const specFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodBoolean;
+    validation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    serviceSelection: z.ZodOptional<z.ZodBoolean>;
+    piiClass: z.ZodOptional<z.ZodEnum<["none", "context", "always", "reference"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    key: string;
+    label: string;
+    required: boolean;
+    options?: unknown[] | undefined;
+    validation?: Record<string, unknown> | undefined;
+    serviceSelection?: boolean | undefined;
+    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+}, {
+    type: string;
+    key: string;
+    label: string;
+    required: boolean;
+    options?: unknown[] | undefined;
+    validation?: Record<string, unknown> | undefined;
+    serviceSelection?: boolean | undefined;
+    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+}>;
+type SpecField = z.infer<typeof specFieldSchema>;
+declare const specStepSchema: z.ZodObject<{
+    stage: z.ZodEnum<["lead", "prospect", "activation"]>;
+    fields: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodBoolean;
+        validation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        serviceSelection: z.ZodOptional<z.ZodBoolean>;
+        piiClass: z.ZodOptional<z.ZodEnum<["none", "context", "always", "reference"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        key: string;
+        label: string;
+        required: boolean;
+        options?: unknown[] | undefined;
+        validation?: Record<string, unknown> | undefined;
+        serviceSelection?: boolean | undefined;
+        piiClass?: "none" | "context" | "always" | "reference" | undefined;
+    }, {
+        type: string;
+        key: string;
+        label: string;
+        required: boolean;
+        options?: unknown[] | undefined;
+        validation?: Record<string, unknown> | undefined;
+        serviceSelection?: boolean | undefined;
+        piiClass?: "none" | "context" | "always" | "reference" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    stage: "lead" | "prospect" | "activation";
+    fields: {
+        type: string;
+        key: string;
+        label: string;
+        required: boolean;
+        options?: unknown[] | undefined;
+        validation?: Record<string, unknown> | undefined;
+        serviceSelection?: boolean | undefined;
+        piiClass?: "none" | "context" | "always" | "reference" | undefined;
+    }[];
+}, {
+    stage: "lead" | "prospect" | "activation";
+    fields: {
+        type: string;
+        key: string;
+        label: string;
+        required: boolean;
+        options?: unknown[] | undefined;
+        validation?: Record<string, unknown> | undefined;
+        serviceSelection?: boolean | undefined;
+        piiClass?: "none" | "context" | "always" | "reference" | undefined;
+    }[];
+}>;
+type SpecStep = z.infer<typeof specStepSchema>;
+declare const onboardingSpecSchema: z.ZodObject<{
+    specVersion: z.ZodString;
+    onboarderTier: z.ZodEnum<["platform", "tenant"]>;
+    botChallenge: z.ZodObject<{
+        provider: z.ZodLiteral<"recaptcha">;
+        siteKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        provider: "recaptcha";
+        siteKey: string;
+    }, {
+        provider: "recaptcha";
+        siteKey: string;
+    }>;
+    forms: z.ZodObject<{
+        contact: z.ZodObject<{
+            fields: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                type: z.ZodString;
+                label: z.ZodString;
+                required: z.ZodBoolean;
+                validation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                options: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+                serviceSelection: z.ZodOptional<z.ZodBoolean>;
+                piiClass: z.ZodOptional<z.ZodEnum<["none", "context", "always", "reference"]>>;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }, {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        }, {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        }>;
+        signup: z.ZodObject<{
+            steps: z.ZodArray<z.ZodObject<{
+                stage: z.ZodEnum<["lead", "prospect", "activation"]>;
+                fields: z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    type: z.ZodString;
+                    label: z.ZodString;
+                    required: z.ZodBoolean;
+                    validation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    options: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+                    serviceSelection: z.ZodOptional<z.ZodBoolean>;
+                    piiClass: z.ZodOptional<z.ZodEnum<["none", "context", "always", "reference"]>>;
+                }, "strip", z.ZodTypeAny, {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }, {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }>, "many">;
+            }, "strip", z.ZodTypeAny, {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }, {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        }, {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    }, {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    specVersion: string;
+    onboarderTier: "platform" | "tenant";
+    botChallenge: {
+        provider: "recaptcha";
+        siteKey: string;
+    };
+    forms: {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    };
+}, {
+    specVersion: string;
+    onboarderTier: "platform" | "tenant";
+    botChallenge: {
+        provider: "recaptcha";
+        siteKey: string;
+    };
+    forms: {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    };
+}>;
+type OnboardingSpec = z.infer<typeof onboardingSpecSchema>;
+/**
+ * Parse an unknown value as an OnboardingSpec.
+ * Returns a SafeParseReturnType (inferred).
+ */
+declare function validateOnboardingSpec(value: unknown): z.SafeParseReturnType<{
+    specVersion: string;
+    onboarderTier: "platform" | "tenant";
+    botChallenge: {
+        provider: "recaptcha";
+        siteKey: string;
+    };
+    forms: {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    };
+}, {
+    specVersion: string;
+    onboarderTier: "platform" | "tenant";
+    botChallenge: {
+        provider: "recaptcha";
+        siteKey: string;
+    };
+    forms: {
+        contact: {
+            fields: {
+                type: string;
+                key: string;
+                label: string;
+                required: boolean;
+                options?: unknown[] | undefined;
+                validation?: Record<string, unknown> | undefined;
+                serviceSelection?: boolean | undefined;
+                piiClass?: "none" | "context" | "always" | "reference" | undefined;
+            }[];
+        };
+        signup: {
+            steps: {
+                stage: "lead" | "prospect" | "activation";
+                fields: {
+                    type: string;
+                    key: string;
+                    label: string;
+                    required: boolean;
+                    options?: unknown[] | undefined;
+                    validation?: Record<string, unknown> | undefined;
+                    serviceSelection?: boolean | undefined;
+                    piiClass?: "none" | "context" | "always" | "reference" | undefined;
+                }[];
+            }[];
+        };
+    };
+}>;
+
+export { FIELD_KEY_PATTERN as F, type OnboarderTier as O, type PiiClass as P, type SpecField as S, type TerminalStage as T, type OnboardingSpec as a, type SpecStage as b, type SpecStep as c, specStepSchema as d, onboardingSpecSchema as o, specFieldSchema as s, validateOnboardingSpec as v };

package/dist/recaptcha/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * reCAPTCHA v3 loader and token executor.
+ *
+ * Per D537:
+ *   - Site key is public (supplied at mount time from the spec response).
+ *   - Secret key is NEVER in the browser — only the site key is here.
+ *   - v3 score-based by default; the operator may configure a v2 fallback
+ *     on the server side for low-score requests.
+ *   - The loader injects the reCAPTCHA script once and exposes execute()
+ *     to obtain a fresh token before each submit.
+ *
+ * Failure semantics (all recoverable, all bounded by opts.timeoutMs / 10s):
+ *   - A script load failure (adblock / CSP / offline) REJECTS with
+ *     RecaptchaError(kind:"load_failed"), EVICTS the cached promise, and
+ *     REMOVES the injected script tag — the next loadRecaptcha call starts
+ *     fresh. A transient failure never poisons the siteKey.
+ *   - EVERY wait is bounded, including grecaptcha.ready() AFTER onload and on
+ *     the adoption/poll paths: if api.js serves but the inner runtime never
+ *     boots (ready() never fires), the loader rejects RecaptchaError(
+ *     kind:"timeout") and evicts, rather than hanging the widget on
+ *     "Sending…" forever.
+ *   - The "existing script tag but no grecaptcha global" poll is BOUNDED,
+ *     then the subsequent ready() is bounded by the remaining budget.
+ *
+ * Multi-siteKey + foreign-global handling (honest):
+ *   - The v3 script loads with `?render=<siteKey>` and initializes for ONE
+ *     site key per page. A SECOND different siteKey after our first load is
+ *     rejected RecaptchaError(kind:"sitekey_mismatch").
+ *   - If the HOST page pre-loaded grecaptcha with an unknown render key (a
+ *     FOREIGN global this SDK did not create), we CANNOT introspect its key,
+ *     so executing our key against it would be the exact silent misfire we
+ *     promise to prevent. We reject RecaptchaError(kind:"sitekey_mismatch")
+ *     instead. (Detection: we only adopt a global we brought up ourselves or
+ *     that our own script tag is loading.)
+ *
+ * execute() rejections (invalid key at execute time, Google-internal errors,
+ * often plain strings) are wrapped in RecaptchaError(kind:"execute_failed").
+ *
+ * This module is browser-only. It accesses the `window` and `document`
+ * globals explicitly.
+ */
+declare global {
+    interface Window {
+        grecaptcha?: Grecaptcha;
+    }
+}
+interface Grecaptcha {
+    ready(callback: () => void): void;
+    execute(siteKey: string, options: {
+        action: string;
+    }): Promise<string>;
+}
+type RecaptchaErrorKind = "load_failed" | "timeout" | "sitekey_mismatch" | "execute_failed" | "unavailable";
+/** Typed error for every reCAPTCHA loader failure path. */
+declare class RecaptchaError extends Error {
+    readonly kind: RecaptchaErrorKind;
+    constructor(kind: RecaptchaErrorKind, message: string);
+}
+interface RecaptchaLoadOptions {
+    /**
+     * Max time to wait for the script / grecaptcha global to become ready
+     * before rejecting with RecaptchaError(kind:"timeout"). Default 10s.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Inject the reCAPTCHA v3 script for the given siteKey.
+ * Idempotent per siteKey: concurrent/repeated calls share one load.
+ * A FAILED load is evicted — the next call retries from scratch.
+ *
+ * @throws {RecaptchaError} kind:"sitekey_mismatch" — a different siteKey
+ *   is already active (single-render-script limitation, see module doc).
+ * @throws {RecaptchaError} kind:"load_failed" — script failed to load.
+ * @throws {RecaptchaError} kind:"timeout" — script/global never became ready.
+ * @throws {RecaptchaError} kind:"unavailable" — no DOM (not a browser).
+ */
+declare function loadRecaptcha(siteKey: string, opts?: RecaptchaLoadOptions): Promise<void>;
+/**
+ * Obtain a fresh reCAPTCHA v3 token for the given action.
+ * Loads the script if not already loaded. A previous load FAILURE does not
+ * block this call — the loader retries from scratch (see loadRecaptcha).
+ *
+ * @param siteKey - The public reCAPTCHA site key (from the spec endpoint).
+ * @param action  - The action name (e.g. "contact_submit"). Used for score analytics.
+ * @param opts    - Optional load options (timeoutMs — also bounds execute()).
+ * @returns A fresh reCAPTCHA token. Valid for ~2 minutes.
+ *
+ * @throws {RecaptchaError} kind:"timeout" if execute() does not settle within
+ *   the timeout (Google runtime hung) — bounded so the widget re-enables.
+ * @throws {RecaptchaError} on any load failure (see loadRecaptcha kinds) or
+ *   an execute() rejection (kind:"execute_failed").
+ */
+declare function executeRecaptcha(siteKey: string, action: string, opts?: RecaptchaLoadOptions): Promise<string>;
+/**
+ * Reset ALL loader state: cached load promise, active siteKey, and the
+ * injected script tag (removed from the DOM if present). Primarily for
+ * tests and for host pages that intentionally tear down reCAPTCHA.
+ * Does NOT unset window.grecaptcha (the script may still own it).
+ */
+declare function _resetRecaptchaState(): void;
+
+export { RecaptchaError, type RecaptchaErrorKind, type RecaptchaLoadOptions, _resetRecaptchaState, executeRecaptcha, loadRecaptcha };

package/dist/recaptcha/index.js

@@ -0,0 +1,4 @@
+import '../chunk-VH6FWDWI.js';
+export { RecaptchaError, _resetRecaptchaState, executeRecaptcha, loadRecaptcha } from '../chunk-7NS7ENJV.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/recaptcha/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}