@corbado/observe 0.16.5 → 0.16.6

package/dist/index.d.mts

@@ -58,7 +58,10 @@ type UserReference = {
     /** Shared UUID used to link sessions across environments. */
     crossEnvironmentTransactionID?: string;
 };
-/** A stable reference to all flows opened by one flow_started event. */
+/**
+ * A stable reference to the flows one flow event belongs to: every flow a `flow_started` opened,
+ * or the flow a `flow_finished` finished.
+ */
 interface FlowHandle {
     /** Attach identity to this journey, including after it finishes or the tracker session changes.
      * Resolves when tracking/enqueue completes, not when server delivery is acknowledged.
@@ -262,6 +265,14 @@ interface EventBatchMeta {
      * changes propagate with page-load lag, so calendar-date cohorts are mixed).
      */
     configVersion?: string;
+    /**
+     * Project-scoped data policy code (integer 0..255; an opaque selector of a policy configured in
+     * Corbado, 0 = the project default) the tracker is running under, as set via
+     * `init({ dataPolicy })` or `setDataPolicy()`. Once known it is sent on every batch (including an
+     * explicit 0); omitted while no policy has ever been set. The server records the latest code it
+     * receives per session (last write wins), so the SDK always sends the current value.
+     */
+    dataPolicy?: number;
 }
 interface EventMeta {
     initiator?: LowEventInitiator;
@@ -1227,6 +1238,12 @@ interface TrackerOptions {
      * assignments and then attached to every event the tracker produces (see {@link CorbadoTracker.setExperiment}).
      */
     experiments?: Record<string, string>;
+    /**
+     * Data policy code to seed at init: a project-scoped non-negative integer (0..255) selecting a
+     * policy configured in Corbado (0 is the project default). Overlays any persisted code and is then
+     * sent as `meta.dataPolicy` on every batch (see {@link CorbadoTracker.setDataPolicy}).
+     */
+    dataPolicy?: number;
     applicationId?: string;
     /**
      * @deprecated The flush interval is server-controlled via the SDK reliability config
@@ -1267,6 +1284,11 @@ declare class CorbadoTracker {
     private lastActivityWriteAt;
     /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
     private experiments;
+    /**
+     * Persistent data policy code, stamped into every batch's `meta.dataPolicy` once set. Never
+     * cleared (only overwritten): it survives reloads, session rotation, resetSession and destroy.
+     */
+    private dataPolicy?;
     /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
     private telemetryReporting;
     private telemetryReady;
@@ -1315,6 +1337,23 @@ declare class CorbadoTracker {
      * @returns A frozen snapshot, created fresh on every call.
      */
     getSdkConfig(): ObserveSdkConfigSnapshot;
+    /**
+     * Set the data policy code for this tracker (e.g. `setDataPolicy(1)` once the user agreed to
+     * extended processing; `setDataPolicy(0)` to return to the project default). Codes are
+     * project-scoped non-negative integers (0..255) selecting a policy configured in Corbado; they
+     * carry no ordering.
+     *
+     * The code is persisted (localStorage, project-scoped) and sent as `meta.dataPolicy` on every
+     * subsequent batch, across reloads and session rotation. It is never cleared, only overwritten.
+     * The server records the latest code it receives for a session (last write wins). Invalid codes
+     * are ignored with a debug log; never throws.
+     */
+    setDataPolicy(code: number): void;
+    /** Returns the current data policy code, or undefined when none has ever been set. */
+    getDataPolicy(): number | undefined;
+    private static isValidDataPolicy;
+    private loadPersistedDataPolicy;
+    private persistDataPolicy;
     private static isValidExperimentKey;
     private static isValidExperimentVariant;
     private loadPersistedExperiments;
@@ -1427,7 +1466,7 @@ declare class CorbadoTracker {
      * (such as login vs signup), pass `flowNames` and optionally `defaultFlowName`.
      *
      * The returned handle can attach identity after completion with `await flow.enrich({ userId })`.
-     * Enrichment requires a backend supporting explicit start-event targeting.
+     * Enrichment requires a backend supporting explicit event targeting.
      *
      * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
@@ -1491,7 +1530,12 @@ declare class CorbadoTracker {
      * @remarks
      * Fire this when the user has finished the target flow end-to-end, such as completed login,
      * signup, or recovery. Record identity with `setUser()` while the flow is active,
-     * or use the handle returned by `flowStarted()` to enrich it after completion.
+     * or enrich it after completion through the handle returned by `flowStarted()` or by this call.
+     *
+     * The returned handle targets the flow this event finished, so identity learned only after
+     * completion — for example from a profile request that follows account creation — can be
+     * attached with `await finished.enrich({ userId })` even on a page that never saw the flow start.
+     * Enrichment requires a backend supporting explicit flow-event targeting.
      *
      * Legacy identity fields in `data` remain supported but are deprecated.
      *
@@ -1500,12 +1544,14 @@ declare class CorbadoTracker {
      *
      * @example
      * ```typescript
-     * tracker.flowFinished({
-     *   flowName: "login",
-     * });
+     * const finished = tracker.flowFinished({ flowName: "signup" });
+     * const userId = await hashUserId(createdAccountId);
+     * await finished.enrich({ userId });
      * ```
      */
-    flowFinished(data: FlowFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    flowFinished(data: FlowFinished, tags?: Record<string, string>, experiments?: Record<string, string>): FlowHandle;
+    /** Emits `flow_enriched` against an explicit target, in the session that emitted the target. */
+    private flowHandle;
     /**
      * Track when an in-progress flow is reset and restarted.
      *
@@ -1951,6 +1997,11 @@ interface QueueOptions {
      * {@link EventStore}). Defaults to the shared {@link OUTBOX_LOCK_NAME}.
      */
     outboxLockName?: string;
+    /**
+     * Returns the data policy code to stamp into `meta.dataPolicy` of every batch, or undefined when
+     * none has ever been set. Read at send time so a change applies to the next batch without a flush.
+     */
+    getDataPolicy?: () => number | undefined;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -2004,6 +2055,7 @@ declare class RequestQueue {
     private readonly debug;
     private readonly requestConfig;
     private readonly onConfigReceived?;
+    private readonly getDataPolicy?;
     /** Current delivery policy, including live updates. */
     private config;
     /**
@@ -2074,10 +2126,13 @@ declare class RequestQueue {
      * Stamps delivery metadata onto the batch: the trigger that caused this flush, the config version
      * this load runs under (omitted on built-in defaults) and the number of prior failed delivery
      * attempts (the max across its entries, only when at least one entry is a retry). `entry.attempts`
-     * is incremented on each failed flush, so it equals the retry count at send time. The transport
-     * later merges in `sent`/`transport`.
+     * is incremented on each failed flush, so it equals the retry count at send time. The data policy
+     * code (when one has ever been set) is read live, so it reflects the tracker state at send time.
+     * The transport later merges in `sent`/`transport`.
      */
     private attachBatchMeta;
+    /** The data policy code from the tracker, or undefined; a throwing getter must never break a flush. */
+    private readDataPolicy;
     private getDuePending;
     private takeLows;
     private validPendingLow;

package/dist/index.d.ts

@@ -58,7 +58,10 @@ type UserReference = {
     /** Shared UUID used to link sessions across environments. */
     crossEnvironmentTransactionID?: string;
 };
-/** A stable reference to all flows opened by one flow_started event. */
+/**
+ * A stable reference to the flows one flow event belongs to: every flow a `flow_started` opened,
+ * or the flow a `flow_finished` finished.
+ */
 interface FlowHandle {
     /** Attach identity to this journey, including after it finishes or the tracker session changes.
      * Resolves when tracking/enqueue completes, not when server delivery is acknowledged.
@@ -262,6 +265,14 @@ interface EventBatchMeta {
      * changes propagate with page-load lag, so calendar-date cohorts are mixed).
      */
     configVersion?: string;
+    /**
+     * Project-scoped data policy code (integer 0..255; an opaque selector of a policy configured in
+     * Corbado, 0 = the project default) the tracker is running under, as set via
+     * `init({ dataPolicy })` or `setDataPolicy()`. Once known it is sent on every batch (including an
+     * explicit 0); omitted while no policy has ever been set. The server records the latest code it
+     * receives per session (last write wins), so the SDK always sends the current value.
+     */
+    dataPolicy?: number;
 }
 interface EventMeta {
     initiator?: LowEventInitiator;
@@ -1227,6 +1238,12 @@ interface TrackerOptions {
      * assignments and then attached to every event the tracker produces (see {@link CorbadoTracker.setExperiment}).
      */
     experiments?: Record<string, string>;
+    /**
+     * Data policy code to seed at init: a project-scoped non-negative integer (0..255) selecting a
+     * policy configured in Corbado (0 is the project default). Overlays any persisted code and is then
+     * sent as `meta.dataPolicy` on every batch (see {@link CorbadoTracker.setDataPolicy}).
+     */
+    dataPolicy?: number;
     applicationId?: string;
     /**
      * @deprecated The flush interval is server-controlled via the SDK reliability config
@@ -1267,6 +1284,11 @@ declare class CorbadoTracker {
     private lastActivityWriteAt;
     /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
     private experiments;
+    /**
+     * Persistent data policy code, stamped into every batch's `meta.dataPolicy` once set. Never
+     * cleared (only overwritten): it survives reloads, session rotation, resetSession and destroy.
+     */
+    private dataPolicy?;
     /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
     private telemetryReporting;
     private telemetryReady;
@@ -1315,6 +1337,23 @@ declare class CorbadoTracker {
      * @returns A frozen snapshot, created fresh on every call.
      */
     getSdkConfig(): ObserveSdkConfigSnapshot;
+    /**
+     * Set the data policy code for this tracker (e.g. `setDataPolicy(1)` once the user agreed to
+     * extended processing; `setDataPolicy(0)` to return to the project default). Codes are
+     * project-scoped non-negative integers (0..255) selecting a policy configured in Corbado; they
+     * carry no ordering.
+     *
+     * The code is persisted (localStorage, project-scoped) and sent as `meta.dataPolicy` on every
+     * subsequent batch, across reloads and session rotation. It is never cleared, only overwritten.
+     * The server records the latest code it receives for a session (last write wins). Invalid codes
+     * are ignored with a debug log; never throws.
+     */
+    setDataPolicy(code: number): void;
+    /** Returns the current data policy code, or undefined when none has ever been set. */
+    getDataPolicy(): number | undefined;
+    private static isValidDataPolicy;
+    private loadPersistedDataPolicy;
+    private persistDataPolicy;
     private static isValidExperimentKey;
     private static isValidExperimentVariant;
     private loadPersistedExperiments;
@@ -1427,7 +1466,7 @@ declare class CorbadoTracker {
      * (such as login vs signup), pass `flowNames` and optionally `defaultFlowName`.
      *
      * The returned handle can attach identity after completion with `await flow.enrich({ userId })`.
-     * Enrichment requires a backend supporting explicit start-event targeting.
+     * Enrichment requires a backend supporting explicit event targeting.
      *
      * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
@@ -1491,7 +1530,12 @@ declare class CorbadoTracker {
      * @remarks
      * Fire this when the user has finished the target flow end-to-end, such as completed login,
      * signup, or recovery. Record identity with `setUser()` while the flow is active,
-     * or use the handle returned by `flowStarted()` to enrich it after completion.
+     * or enrich it after completion through the handle returned by `flowStarted()` or by this call.
+     *
+     * The returned handle targets the flow this event finished, so identity learned only after
+     * completion — for example from a profile request that follows account creation — can be
+     * attached with `await finished.enrich({ userId })` even on a page that never saw the flow start.
+     * Enrichment requires a backend supporting explicit flow-event targeting.
      *
      * Legacy identity fields in `data` remain supported but are deprecated.
      *
@@ -1500,12 +1544,14 @@ declare class CorbadoTracker {
      *
      * @example
      * ```typescript
-     * tracker.flowFinished({
-     *   flowName: "login",
-     * });
+     * const finished = tracker.flowFinished({ flowName: "signup" });
+     * const userId = await hashUserId(createdAccountId);
+     * await finished.enrich({ userId });
      * ```
      */
-    flowFinished(data: FlowFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    flowFinished(data: FlowFinished, tags?: Record<string, string>, experiments?: Record<string, string>): FlowHandle;
+    /** Emits `flow_enriched` against an explicit target, in the session that emitted the target. */
+    private flowHandle;
     /**
      * Track when an in-progress flow is reset and restarted.
      *
@@ -1951,6 +1997,11 @@ interface QueueOptions {
      * {@link EventStore}). Defaults to the shared {@link OUTBOX_LOCK_NAME}.
      */
     outboxLockName?: string;
+    /**
+     * Returns the data policy code to stamp into `meta.dataPolicy` of every batch, or undefined when
+     * none has ever been set. Read at send time so a change applies to the next batch without a flush.
+     */
+    getDataPolicy?: () => number | undefined;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -2004,6 +2055,7 @@ declare class RequestQueue {
     private readonly debug;
     private readonly requestConfig;
     private readonly onConfigReceived?;
+    private readonly getDataPolicy?;
     /** Current delivery policy, including live updates. */
     private config;
     /**
@@ -2074,10 +2126,13 @@ declare class RequestQueue {
      * Stamps delivery metadata onto the batch: the trigger that caused this flush, the config version
      * this load runs under (omitted on built-in defaults) and the number of prior failed delivery
      * attempts (the max across its entries, only when at least one entry is a retry). `entry.attempts`
-     * is incremented on each failed flush, so it equals the retry count at send time. The transport
-     * later merges in `sent`/`transport`.
+     * is incremented on each failed flush, so it equals the retry count at send time. The data policy
+     * code (when one has ever been set) is read live, so it reflects the tracker state at send time.
+     * The transport later merges in `sent`/`transport`.
      */
     private attachBatchMeta;
+    /** The data policy code from the tracker, or undefined; a throwing getter must never break a flush. */
+    private readDataPolicy;
     private getDuePending;
     private takeLows;
     private validPendingLow;