@stapel/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @stapel/core
+
+The Stapel frontend runtime (L0, frontend-standard §1). Everything the
+`@stapel/<module>-react` pairs build on:
+
+- **`createStapelClient`** — typed fetch wrapper: base URL, auth token getter
+  + refresh seam, parses the Stapel error envelope
+  `{localizable_error, error, params}` into `StapelApiError`
+  (`code` = the `localizable_error` i18n key, `params` for interpolation).
+- **Verification-403 interception** — when a 403 body carries a
+  `verification` object (`challenge_id`/`scope`/`factors`), the configured
+  `onVerificationChallenge(challenge)` is invoked; on
+  `{ retry: true, token }` the original request is retried once with
+  `X-Verification-Token`. This is the seam `@stapel/auth-react`'s factor
+  machines plug into (the flagship cross-module flow, standard §2).
+- **`StapelConfigProvider`** — provides the default client plus per-module
+  client overrides (client injection, the fork-resolution seam of §7.2).
+- **Query layer** — `createStapelQueryClient()`: TanStack Query v5 client
+  with a persistence runtime: IndexedDB via `idb-keyval`, `localStorage`
+  fallback, in-memory last resort; **per-user namespace** via
+  `setPersistUser(userId)`; `purgePersistedCache()` for logout/GDPR;
+  cache-version buster (set it to your package version).
+- **i18n engine** — key→string dictionaries, `{param}` interpolation,
+  `I18nProvider` / `useT` / `useI18n`, static bundles + async locale loader
+  seam (point it at `translate.resolve` of stapel-translate), missing keys
+  fall back to the key itself.
+- **`useBreakpoint()`** — resolves the three `@stapel/tokens` breakpoints;
+  SSR-safe (`undefined` until mounted).
+- **Analytics facade** — see the dedicated section below
+  (analytics-standard §2).
+
+## Analytics facade
+
+Per [analytics-standard](../../../docs/analytics-standard.md) §1–2 and
+frontend-standard §4.7: packages and hosts talk to the facade only, never to
+providers directly.
+
+```ts
+import {
+  createAnalytics,
+  consoleProvider,
+  stapelCollectorProvider,
+  trackFlowStep,
+} from "@stapel/core";
+
+const analytics = createAnalytics({
+  providers: {
+    stapel: stapelCollectorProvider({ client, writeKey: "wk_…" }),
+    console: consoleProvider(), // dev
+  },
+  registry: eventsJson.map((e) => e.name), // dev warning; hard gate = eslint
+  piiGuard: "strip", // email/phone-like prop values → "[redacted]"
+});
+
+analytics.track("cart.checkout", { total: 42 });
+analytics.identify(user.id, { plan: "pro" }); // id is SHA-256-hashed first
+analytics.page("pricing");
+await analytics.setConsent("granted"); // "pending" buffers, "denied" drops
+trackFlowStep(analytics, "onboarding", "otp", "completed"); // flow.<id>.<step>
+```
+
+Semantics: consent gate (buffer while `pending`, flush on `granted`, drop +
+no-op on `denied`; consent persists), offline queue on the shared persist
+storage (IndexedDB → localStorage → memory; survives instance recreation),
+batched fan-out to all registered providers with per-provider delivery
+tracking, exponential-backoff retries (drop with a warning after
+`maxAttempts`), flush on interval / `maxSize` / explicit `flush()` /
+`pagehide` + `visibilitychange: hidden` (the Stapel collector uses
+`navigator.sendBeacon` for that final batch). `register`/`unregister` change
+the fan-out at runtime — extra providers (Mixpanel, GA4, PostHog…) are tiny
+`@stapel/analytics-<provider>` packages or app-layer classes. Wire React via
+`<StapelConfigProvider analytics={analytics}>` and `useAnalytics()`.
+
+## Quick start
+
+```tsx
+import {
+  createStapelClient,
+  createStapelQueryClient,
+  createI18n,
+  StapelConfigProvider,
+  I18nProvider,
+} from "@stapel/core";
+import { QueryClientProvider } from "@tanstack/react-query";
+
+const client = createStapelClient({
+  baseUrl: "https://api.example.com",
+  getToken: () => auth.accessToken,
+  onAuthRefresh: () => auth.refresh(),
+  onVerificationChallenge: (challenge) => verificationUi.run(challenge),
+});
+
+const query = createStapelQueryClient({ cacheVersion: "0.1.0" });
+const i18n = createI18n({
+  locale: "en",
+  loadLocale: (locale) => translateClient.resolve(locale), // stapel-translate
+});
+
+<StapelConfigProvider config={{ client }}>
+  <QueryClientProvider client={query.queryClient}>
+    <I18nProvider i18n={i18n}>{app}</I18nProvider>
+  </QueryClientProvider>
+</StapelConfigProvider>;
+
+// on login:  await query.setPersistUser(user.id);
+// on logout: await query.purgePersistedCache();
+```
+
+## Notes
+
+- Peer deps: `react >= 19`, `@tanstack/react-query ^5`. Only runtime dep:
+  `idb-keyval` (+ `@stapel/tokens`).
+- Standalone-buildable; the npm tarball ships `src/` (frontend-standard §7).
+- TODO(frontend-standard §4.5): precompile with React Compiler at publish so
+  consumers outside the Stapel toolchain get baked-in memoization. The package
+  is currently hooks-only (no JSX-heavy render paths), so the compiler yields
+  nothing yet; wire it into the publish pipeline together with the first
+  headless components.

package/dist/analytics/context.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from "react";
+import type { Analytics } from "./types.js";
+/**
+ * Provided by `<StapelConfigProvider analytics={...}>` (or directly via
+ * `AnalyticsContext.Provider`).
+ */
+export declare const AnalyticsContext: Context<Analytics | null>;
+export declare function useAnalytics(): Analytics;
+//# sourceMappingURL=context.d.ts.map

package/dist/analytics/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/analytics/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAChB,CAAC;AAExC,wBAAgB,YAAY,IAAI,SAAS,CAQxC"}

package/dist/analytics/context.js

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+/**
+ * Provided by `<StapelConfigProvider analytics={...}>` (or directly via
+ * `AnalyticsContext.Provider`).
+ */
+export const AnalyticsContext = createContext(null);
+export function useAnalytics() {
+    const analytics = useContext(AnalyticsContext);
+    if (analytics === null) {
+        throw new Error("useAnalytics requires an analytics instance — pass it to <StapelConfigProvider analytics={...}>");
+    }
+    return analytics;
+}
+//# sourceMappingURL=context.js.map

package/dist/analytics/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/analytics/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAIlD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,aAAa,CAAmB,IAAI,CAAC,CAAC;AAExC,MAAM,UAAU,YAAY;IAC1B,MAAM,SAAS,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/analytics/createAnalytics.d.ts

@@ -0,0 +1,10 @@
+import type { Analytics, AnalyticsOptions } from "./types.js";
+/** Exponential backoff delay for a batch delivery attempt (1-based). */
+export declare function backoffDelay(attempt: number, baseMs: number): number;
+/**
+ * The analytics facade (analytics-standard §2): fan-out to N providers,
+ * consent gate, offline queue on the core persist layer, batched delivery
+ * with retry/backoff, PII guard, hashed identify.
+ */
+export declare function createAnalytics(options?: AnalyticsOptions): Analytics;
+//# sourceMappingURL=createAnalytics.d.ts.map

package/dist/analytics/createAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAnalytics.d.ts","sourceRoot":"","sources":["../../src/analytics/createAnalytics.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,SAAS,EAGT,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAEpB,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAyBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAuQzE"}

package/dist/analytics/createAnalytics.js

@@ -0,0 +1,273 @@
+import { defaultPersistStorage } from "../storage.js";
+import { guardPii } from "./pii.js";
+import { sha256Hex } from "./hash.js";
+/** Exponential backoff delay for a batch delivery attempt (1-based). */
+export function backoffDelay(attempt, baseMs) {
+    return Math.min(30_000, baseMs * 2 ** Math.max(0, attempt - 1));
+}
+async function deliverToProvider(provider, events) {
+    for (const event of events) {
+        if (event.kind === "identify" && provider.identify) {
+            await provider.identify(event.userHash ?? "", event.props);
+        }
+        else if (event.kind === "page" && provider.page) {
+            await provider.page(event.name, event.props);
+        }
+        else {
+            await provider.track(event);
+        }
+    }
+    await provider.flush?.();
+}
+/**
+ * The analytics facade (analytics-standard §2): fan-out to N providers,
+ * consent gate, offline queue on the core persist layer, batched delivery
+ * with retry/backoff, PII guard, hashed identify.
+ */
+export function createAnalytics(options = {}) {
+    const providers = new Map(Object.entries(options.providers ?? {}));
+    const registry = options.registry !== undefined ? new Set(options.registry) : null;
+    const piiMode = options.piiGuard ?? "strip";
+    const persistKey = options.persistKey ?? "stapel-analytics";
+    const storage = options.storage ?? defaultPersistStorage();
+    const maxSize = options.batch?.maxSize ?? 20;
+    const flushIntervalMs = options.batch?.flushIntervalMs ?? 10_000;
+    const maxAttempts = options.batch?.maxAttempts ?? 5;
+    const backoffBaseMs = options.batch?.backoffBaseMs ?? 500;
+    const eventsKey = `${persistKey}:events`;
+    const consentKey = `${persistKey}:consent`;
+    let consent = options.consent ?? "pending";
+    let queue = [];
+    let batch = null;
+    let flushing = false;
+    let retryTimer = null;
+    let seq = 0;
+    const warnedPii = new Set();
+    const warnedRegistry = new Set();
+    /** In-flight async work (identify hashing, persist writes) awaited by flush. */
+    let pendingOps = [];
+    /** Serializes identify hashing so enqueue order matches call order. */
+    let identifyChain = Promise.resolve();
+    const ready = (async () => {
+        try {
+            const storedConsent = await storage.get(consentKey);
+            if (storedConsent === "granted" ||
+                storedConsent === "denied" ||
+                storedConsent === "pending") {
+                consent = storedConsent;
+            }
+            const storedEvents = await storage.get(eventsKey);
+            if (Array.isArray(storedEvents)) {
+                // Restored events precede anything captured before init finished.
+                queue = [...storedEvents, ...queue];
+            }
+        }
+        catch {
+            // Storage unavailable — degrade to in-memory only.
+        }
+    })();
+    async function persistQueue() {
+        try {
+            if (consent === "denied") {
+                await storage.del(eventsKey);
+                return;
+            }
+            const pending = batch ? [...batch.events, ...queue] : queue;
+            await storage.set(eventsKey, pending);
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    function schedulePersist() {
+        pendingOps.push(ready.then(persistQueue));
+    }
+    function clearRetryTimer() {
+        if (retryTimer !== null) {
+            clearTimeout(retryTimer);
+            retryTimer = null;
+        }
+    }
+    function scheduleRetry(delayMs) {
+        if (retryTimer !== null)
+            return;
+        retryTimer = setTimeout(() => {
+            retryTimer = null;
+            void flush();
+        }, delayMs);
+        retryTimer.unref?.();
+    }
+    function enqueue(kind, name, props, userHash) {
+        seq += 1;
+        const event = {
+            id: `${String(Date.now())}-${String(seq)}`,
+            kind,
+            name,
+            props,
+            ...(userHash !== undefined ? { userHash } : {}),
+            ts: Date.now(),
+        };
+        queue.push(event);
+        schedulePersist();
+        if (consent === "granted" && queue.length >= maxSize) {
+            void flush();
+        }
+    }
+    /** One delivery attempt for the current batch. True = batch settled. */
+    async function attemptBatch() {
+        const current = batch;
+        if (current === null)
+            return true;
+        current.attempts += 1;
+        await Promise.all([...providers.entries()].map(async ([name, provider]) => {
+            if (current.delivered.has(name))
+                return;
+            try {
+                await deliverToProvider(provider, current.events);
+                current.delivered.add(name);
+            }
+            catch {
+                // Undelivered for this provider; batch will be retried.
+            }
+        }));
+        const undelivered = [...providers.keys()].filter((name) => !current.delivered.has(name));
+        if (undelivered.length === 0) {
+            batch = null;
+            clearRetryTimer();
+            return true;
+        }
+        if (current.attempts >= maxAttempts) {
+            console.warn(`[stapel analytics] dropping a batch of ${String(current.events.length)} event(s) ` +
+                `after ${String(current.attempts)} attempts; undelivered to: ${undelivered.join(", ")}`);
+            batch = null;
+            clearRetryTimer();
+            return true;
+        }
+        scheduleRetry(backoffDelay(current.attempts, backoffBaseMs));
+        return false;
+    }
+    async function flush() {
+        await ready;
+        const ops = pendingOps;
+        pendingOps = [];
+        await Promise.all(ops);
+        if (flushing)
+            return;
+        flushing = true;
+        try {
+            if (consent !== "granted")
+                return;
+            for (;;) {
+                if (batch === null) {
+                    if (queue.length === 0 || providers.size === 0)
+                        break;
+                    batch = {
+                        events: queue.splice(0, maxSize),
+                        attempts: 0,
+                        delivered: new Set(),
+                    };
+                }
+                const settled = await attemptBatch();
+                if (!settled)
+                    break;
+            }
+        }
+        finally {
+            flushing = false;
+            await persistQueue();
+        }
+    }
+    async function setConsent(state) {
+        await ready;
+        consent = state;
+        try {
+            await storage.set(consentKey, state);
+        }
+        catch {
+            // Best-effort.
+        }
+        if (state === "denied") {
+            queue = [];
+            batch = null;
+            clearRetryTimer();
+            try {
+                await storage.del(eventsKey);
+            }
+            catch {
+                // Best-effort.
+            }
+            return;
+        }
+        if (state === "granted") {
+            await flush();
+        }
+    }
+    function track(event, props) {
+        if (consent === "denied")
+            return;
+        if (registry && !registry.has(event) && !warnedRegistry.has(event)) {
+            warnedRegistry.add(event);
+            console.warn(`[stapel analytics] event "${event}" is not in the registry ` +
+                "(analytics-standard §1.1) — delivered anyway; declare it in events.json.");
+        }
+        enqueue("track", event, guardPii(event, props ?? {}, piiMode, warnedPii));
+    }
+    function page(name, props) {
+        if (consent === "denied")
+            return;
+        enqueue("page", name, guardPii(name, props ?? {}, piiMode, warnedPii));
+    }
+    function identify(userId, traits) {
+        if (consent === "denied")
+            return;
+        const guarded = guardPii("identify", traits ?? {}, piiMode, warnedPii);
+        identifyChain = identifyChain
+            .then(() => sha256Hex(userId))
+            .then((userHash) => {
+            enqueue("identify", "identify", guarded, userHash);
+        });
+        pendingOps.push(identifyChain);
+    }
+    function finalFlush() {
+        // Best-effort teardown flush; batching providers use sendBeacon here.
+        void flush();
+        for (const provider of providers.values()) {
+            try {
+                void provider.flush?.();
+            }
+            catch {
+                // Never break page teardown.
+            }
+        }
+    }
+    if (typeof window !== "undefined") {
+        window.addEventListener("pagehide", finalFlush);
+    }
+    if (typeof document !== "undefined") {
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "hidden")
+                finalFlush();
+        });
+    }
+    const interval = setInterval(() => {
+        if (consent === "granted" && (queue.length > 0 || batch !== null)) {
+            void flush();
+        }
+    }, flushIntervalMs);
+    interval.unref?.();
+    return {
+        track,
+        identify,
+        page,
+        flush,
+        setConsent,
+        getConsent: () => consent,
+        register: (name, provider) => {
+            providers.set(name, provider);
+        },
+        unregister: (name) => {
+            providers.delete(name);
+        },
+    };
+}
+//# sourceMappingURL=createAnalytics.js.map

package/dist/analytics/createAnalytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAnalytics.js","sourceRoot":"","sources":["../../src/analytics/createAnalytics.ts"],"names":[],"mappings":"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"}

package/dist/analytics/flow.d.ts

@@ -0,0 +1,10 @@
+import type { Analytics } from "./types.js";
+export type FlowStepPhase = "started" | "completed" | "failed";
+/**
+ * Auto-instrumentation seam for flow machines (analytics-standard §1.2):
+ * emits `flow.<flowId>.<stepId>` with `{phase, ...props}`. Funnel = flow —
+ * the `@stapel/<module>-react` machines call this on every transition, so
+ * funnels exist without hand-written instrumentation.
+ */
+export declare function trackFlowStep(analytics: Analytics, flowId: string, stepId: string, phase: FlowStepPhase, props?: Record<string, unknown>): void;
+//# sourceMappingURL=flow.d.ts.map

package/dist/analytics/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/analytics/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAEN"}

package/dist/analytics/flow.js

@@ -0,0 +1,10 @@
+/**
+ * Auto-instrumentation seam for flow machines (analytics-standard §1.2):
+ * emits `flow.<flowId>.<stepId>` with `{phase, ...props}`. Funnel = flow —
+ * the `@stapel/<module>-react` machines call this on every transition, so
+ * funnels exist without hand-written instrumentation.
+ */
+export function trackFlowStep(analytics, flowId, stepId, phase, props) {
+    analytics.track(`flow.${flowId}.${stepId}`, { phase, ...props });
+}
+//# sourceMappingURL=flow.js.map

package/dist/analytics/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../../src/analytics/flow.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAoB,EACpB,MAAc,EACd,MAAc,EACd,KAAoB,EACpB,KAA+B;IAE/B,SAAS,CAAC,KAAK,CAAC,QAAQ,MAAM,IAAI,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;AACnE,CAAC"}

package/dist/analytics/hash.d.ts

@@ -0,0 +1,3 @@
+/** SHA-256 hex via WebCrypto — user ids are hashed before any provider sees them. */
+export declare function sha256Hex(input: string): Promise<string>;
+//# sourceMappingURL=hash.d.ts.map

package/dist/analytics/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/analytics/hash.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc9D"}

package/dist/analytics/hash.js

@@ -0,0 +1,12 @@
+/** SHA-256 hex via WebCrypto — user ids are hashed before any provider sees them. */
+export async function sha256Hex(input) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("[stapel analytics] crypto.subtle is unavailable; cannot hash user ids");
+    }
+    const digest = await subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+//# sourceMappingURL=hash.js.map

package/dist/analytics/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/analytics/hash.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa;IAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAChC,SAAS,EACT,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAChC,CAAC;IACF,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACjD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/analytics/pii.d.ts

@@ -0,0 +1,9 @@
+import type { PiiGuardMode } from "./types.js";
+export declare function looksLikePii(value: string): boolean;
+export declare const PII_REDACTED = "[redacted]";
+/**
+ * Guard a props/traits object. Warns once per event name (per facade
+ * instance) via the caller-owned `warned` set.
+ */
+export declare function guardPii(eventName: string, props: Record<string, unknown>, mode: PiiGuardMode, warned: Set<string>): Record<string, unknown>;
+//# sourceMappingURL=pii.d.ts.map

package/dist/analytics/pii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.d.ts","sourceRoot":"","sources":["../../src/analytics/pii.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAY/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKnD;AAED,eAAO,MAAM,YAAY,eAAe,CAAC;AAwBzC;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/analytics/pii.js

@@ -0,0 +1,52 @@
+/**
+ * PII guard heuristics (analytics-standard §1.4): prop VALUES that look
+ * like emails or phone numbers are redacted ("strip"), kept with a warning
+ * ("warn"), or passed through ("off"). Applies to track/page props and
+ * identify traits. Keys are not judged — only values.
+ */
+const EMAIL_RE = /[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}/;
+const PHONE_SHAPE_RE = /^\+?[\d\s\-().]{7,}$/;
+export function looksLikePii(value) {
+    if (EMAIL_RE.test(value))
+        return true;
+    const trimmed = value.trim();
+    if (!PHONE_SHAPE_RE.test(trimmed))
+        return false;
+    return trimmed.replace(/\D/g, "").length >= 7;
+}
+export const PII_REDACTED = "[redacted]";
+function sanitizeValue(value, mode, hit) {
+    if (typeof value === "string" && looksLikePii(value)) {
+        hit.found = true;
+        return mode === "strip" ? PII_REDACTED : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeValue(item, mode, hit));
+    }
+    if (typeof value === "object" && value !== null) {
+        const result = {};
+        for (const [key, nested] of Object.entries(value)) {
+            result[key] = sanitizeValue(nested, mode, hit);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Guard a props/traits object. Warns once per event name (per facade
+ * instance) via the caller-owned `warned` set.
+ */
+export function guardPii(eventName, props, mode, warned) {
+    if (mode === "off")
+        return props;
+    const hit = { found: false };
+    const guarded = sanitizeValue(props, mode, hit);
+    if (hit.found && !warned.has(eventName)) {
+        warned.add(eventName);
+        console.warn(`[stapel analytics] PII-like value in props of "${eventName}" — ` +
+            (mode === "strip" ? "redacted" : "kept (piiGuard: warn)") +
+            ". PII in analytics props is banned (analytics-standard §1.4).");
+    }
+    return guarded;
+}
+//# sourceMappingURL=pii.js.map

package/dist/analytics/pii.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.js","sourceRoot":"","sources":["../../src/analytics/pii.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,QAAQ,GAAG,+BAA+B,CAAC;AACjD,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC;AAEzC,SAAS,aAAa,CACpB,KAAc,EACd,IAAkB,EAClB,GAAuB;IAEvB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;QACjB,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC;IACjD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,SAAiB,EACjB,KAA8B,EAC9B,IAAkB,EAClB,MAAmB;IAEnB,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAA4B,CAAC;IAC3E,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,kDAAkD,SAAS,MAAM;YAC/D,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,uBAAuB,CAAC;YACzD,+DAA+D,CAClE,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/analytics/providers.d.ts

@@ -0,0 +1,28 @@
+import type { StapelClient } from "../client.js";
+import type { AnalyticsProvider } from "./types.js";
+/** Dev provider: logs every event via console.debug. Never throws. */
+export declare function consoleProvider(): AnalyticsProvider;
+export interface StapelCollectorOptions {
+    /** Collector origin, e.g. `https://api.example.com`. */
+    readonly baseUrl?: string;
+    /**
+     * Alternatively reuse a `StapelClient` (its base URL, auth headers and
+     * error envelope handling).
+     */
+    readonly client?: StapelClient;
+    /** Source write key (analytics-standard §3); sent in the batch body. */
+    readonly writeKey?: string;
+    /** Injectable fetch (tests). */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Built-in provider for the stapel-analytics ingest endpoint: buffers
+ * events handed over by the facade and POSTs `{events: [...]}` to
+ * `{base}/analytics/api/events` on flush (one request per facade batch).
+ * During page teardown (document hidden) it prefers `navigator.sendBeacon`
+ * so the final batch survives navigation; otherwise fetch with keepalive.
+ * On a failed send the buffer is surrendered back to the facade's retry
+ * (the facade re-delivers the batch, repopulating the buffer).
+ */
+export declare function stapelCollectorProvider(options: StapelCollectorOptions): AnalyticsProvider;
+//# sourceMappingURL=providers.d.ts.map

package/dist/analytics/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/analytics/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpE,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,iBAAiB,CAmBnD;AAED,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAC1C;AAID;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,GAC9B,iBAAiB,CAuDnB"}