@shipeasy/sdk 3.1.0 → 4.2.0

package/README.md

@@ -53,6 +53,58 @@ const client = new FlagsClient({ sdkKey: process.env.SHIPEASY_SERVER_KEY! });
 const cfg = await client.getConfig("plan_limits", { user_id: "u-1" });
 ```
 
+## Error tracking — `see()`
+
+`see` (shipeasy error) is the structured error reporter — opes-style: every
+handled exception documents its **product consequence**, not just its stack.
+Works in vanilla JS on both sides; the whole grammar hangs off one import:
+
+```ts
+import { see } from "@shipeasy/sdk/client"; // or "@shipeasy/sdk/server"
+
+try {
+  await submitOrder(order);
+} catch (e) {
+  see(e).causes_the("checkout").to("use cached prices").extras({ order_id: order.id });
+}
+
+// Non-exception problems — the name is a stable identifier (it participates
+// in the issue fingerprint); variable data goes in .message() / .extras():
+if (rows.length > LIMIT) {
+  see.Violation("large query")
+    .message(`got ${rows.length} rows`)
+    .causes_the("search results")
+    .to("be trimmed");
+}
+
+// Expected control-flow exceptions: document them, report nothing —
+// auto-capture skips marked errors. The reason must start with "because".
+try {
+  return decodeFoo(blob);
+} catch (e) {
+  see.ControlFlowException(e, "because it wasn't an encoded Foo");
+  return decodeBar(blob);
+}
+```
+
+Reports land in the Shipeasy **errors** primitive: fingerprint-grouped issues
+(open / resolved / ignored, regression auto-reopens) with a near-real-time
+occurrence timeseries. The chain dispatches on the next microtask — no
+`.send()` — and ships immediately (`sendBeacon` in the browser, fire-and-forget
+`fetch` on the server), spam-guarded by a 30s dedup window and a per-session
+cap.
+
+The client SDK also auto-captures uncaught exceptions, unhandled rejections,
+and network failures (fetch network errors + 5xx) into the same primitive
+(`autoCollect: { errors }`, on by default). Auto-capture is the outer safety
+net — it does not replace `see()` in catch blocks, where you know the
+consequence and it cannot.
+
+**Rules**: if you don't know the consequence, don't catch the exception. Never
+`see()` then `throw` (double counting — either handle or rethrow). Never use
+`see.Violation()` for a caught exception (you'd drop the stack). No PII or
+high-cardinality data in extras.
+
 ## Drop-in `<script>` loader (no bundler)
 
 ```html

package/dist/client/index.d.mts

@@ -1,3 +1,84 @@
+type SeeExtras = Record<string, string | number | boolean | null | undefined>;
+type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
+/** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+/**
+ * Non-exception problem, built by `violation(name)`. A plain branded object
+ * (not an Error subclass) so `.message()` can be a builder method without
+ * colliding with `Error.prototype.message`.
+ */
+interface Violation {
+    readonly __seViolation: true;
+    readonly violationName: string;
+    readonly violationMessage?: string;
+    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
+    message(msg: string): Violation;
+}
+/**
+ * Identity of a problem that see() already reported, carried on the wire as
+ * the `caused_by` of a later occurrence. Holds exactly the fields the worker's
+ * fingerprint function consumes (raw `message`/`stack` — the server normalizes
+ * them) so the backend can recompute the prior issue's fingerprint and link
+ * the two issues. See `findCausedBy` for how the link is discovered.
+ */
+interface SeeCausedBy {
+    error_type: string;
+    message: string;
+    stack?: string;
+    subject: string;
+    outcome: string;
+}
+/** Wire shape — the `type:"error"` RawEvent variant accepted by POST /collect. */
+interface SeeErrorEvent {
+    type: "error";
+    kind: SeeKind;
+    /** Error class/name (e.g. "TypeError") or the violation name. */
+    error_type: string;
+    message: string;
+    stack?: string;
+    /** Consequence: "<error_type> causes the <subject> to <outcome>". */
+    subject: string;
+    outcome: string;
+    extras?: Record<string, string | number | boolean>;
+    url?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    side: "client" | "server";
+    env?: string;
+    sdk_version: string;
+    ts: number;
+    /**
+     * The earlier reported problem this occurrence descends from — present when
+     * the same error was caught + reported at an inner boundary and then
+     * re-thrown (or wrapped via `{ cause }`) and reported again at an outer one.
+     * Lets the backend stitch the two issues into a cause chain instead of
+     * double-counting them as unrelated.
+     */
+    caused_by?: SeeCausedBy;
+}
+interface SeeExtrasTail {
+    /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
+    extras(extras: SeeExtras): SeeExtrasTail;
+}
+interface SeeOutcomeStep {
+    /** The user-visible impact: `.causes_the("checkout").to("use cached prices")`. */
+    to(outcome: string): SeeExtrasTail;
+}
+interface SeeChain {
+    /** Start the consequence sentence — the product surface affected. */
+    causes_the(subject: string): SeeOutcomeStep;
+    /** camelCase alias of {@link SeeChain.causes_the}. */
+    causesThe(subject: string): SeeOutcomeStep;
+}
+interface SeeViolationChain extends SeeChain {
+    /** Free-form detail. Variable data goes here (or extras), never in the name. */
+    message(msg: string): SeeViolationChain;
+}
+
 declare global {
     interface Window {
         i18n?: {
@@ -8,7 +89,7 @@ declare global {
         };
     }
 }
-declare const version = "1.0.0";
+declare const version = "4.0.0";
 interface User {
     user_id?: string;
     [attr: string]: unknown;
@@ -51,6 +132,13 @@ interface FlagsClientBrowserOptions {
      * true when `autoGuardrails` is true).
      */
     autoGuardrailGroups?: Partial<AutoCollectGroups>;
+    /**
+     * Emit `__auto_*` metric events for ALL visitors, not just experiment
+     * participants. Default false: auto-metrics are gated on the visitor having
+     * seen ≥1 experiment exposure (the only data the analysis pipeline reads;
+     * ungated emission is pure AE write cost at scale — see cost.md).
+     */
+    autoCollectAlways?: boolean;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientBrowserEnv;
     /**
@@ -68,12 +156,14 @@ declare class FlagsClientBrowser {
     private readonly baseUrl;
     private readonly autoGuardrails;
     private readonly autoGuardrailGroups;
+    private readonly autoCollectAlways;
     private readonly env;
     private evalResult;
     private anonId;
     private userId;
     private buffer;
     private telemetry;
+    private seeLimiter;
     private guardrailsInstalled;
     private listeners;
     private overrideListenerInstalled;
@@ -81,6 +171,12 @@ declare class FlagsClientBrowser {
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
     identify(user: User): Promise<void>;
+    /**
+     * Report a structured error into the errors primitive. Flushes immediately
+     * (beacon-first) — error occurrences are near-real-time, never queued behind
+     * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
@@ -171,10 +267,11 @@ interface ShipeasyClientConfig {
      */
     autoIdentify?: boolean;
     /**
-     * Capture web vitals (LCP, CLS, INP, TTFB, FCP, navigation timing), JS /
-     * network errors, and engagement signals (abandonment) as `__auto_*`
-     * metric events. Defaults to `true` — the worker bypasses event-catalog
-     * validation for `__auto_*` names so this is safe out of the box.
+     * Capture web vitals (LCP, CLS, INP, TTFB, FCP, navigation timing) and
+     * engagement signals (abandonment) as `__auto_*` metric events, plus JS /
+     * network errors as structured error events in the errors primitive (same
+     * pipeline as `see()` — grouped by fingerprint, near-real-time). Defaults
+     * to `true`.
      *
      * Pass `false` to disable everything, or a per-group object to narrow:
      *
@@ -183,8 +280,23 @@ interface ShipeasyClientConfig {
      * shipeasy({ clientKey, autoCollect: { errors: false } });   // vitals + engagement only
      * shipeasy({ clientKey });                                   // all groups on
      * ```
+     *
+     * Since 4.1.0, `__auto_*` metric events are only emitted for visitors who
+     * are in ≥1 active experiment (the analysis pipeline reads nothing else;
+     * gating cuts the dominant Analytics Engine write cost at scale). Pass
+     * `{ always: true }` to collect site-wide vitals regardless of experiment
+     * participation:
+     *
+     * ```ts
+     * shipeasy({ clientKey, autoCollect: { always: true } });    // site-wide vitals
+     * ```
+     *
+     * `__auto_abandoned` is always emitted (it fires when the user leaves
+     * before exposures could land) and error capture is unaffected.
      */
-    autoCollect?: boolean | Partial<AutoCollectGroups>;
+    autoCollect?: boolean | (Partial<AutoCollectGroups> & {
+        always?: boolean;
+    });
     /**
      * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
@@ -276,6 +388,58 @@ declare const flags: {
     /** True once identify() has completed and flags are available. */
     readonly ready: boolean;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/client";
+     *
+     * try {
+     *   await submitOrder(order);
+     * } catch (e) {
+     *   see(e).causes_the("checkout").to("use cached prices").extras({ order_id: order.id });
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask, so the report ships
+     * immediately after the statement (no `.send()` needed) into the errors
+     * primitive — grouped by fingerprint, near-real-time timeseries. If you
+     * don't know the consequence of an exception, don't catch it.
+     */
+    (problem: unknown): SeeChain;
+    /**
+     * Report a non-exception problem. Prefer passing a caught Error to `see()`
+     * when one exists. The name is a stable identifier (it participates in the
+     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     *
+     * ```ts
+     * if (rows.length > LIMIT) {
+     *   see.Violation("large query").message(`got ${rows.length} rows`)
+     *      .causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — auto-capture skips it and
+     * nothing is reported. The reason must start with "because".
+     *
+     * ```ts
+     * } catch (e) {
+     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   return decodeAsBar(blob);
+     * }
+     * ```
+     */
+    ControlFlowException(err: unknown, because: string): void;
+}
+/**
+ * Structured error reporter — the whole grammar hangs off this one import.
+ * Safe to import anywhere; a call before `shipeasy({ clientKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 declare const LABEL_MARKER_START = "\uFFF9";
 declare const LABEL_MARKER_SEP = "\uFFFA";
 declare const LABEL_MARKER_END = "\uFFFB";
@@ -314,4 +478,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -1,3 +1,84 @@
+type SeeExtras = Record<string, string | number | boolean | null | undefined>;
+type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
+/** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+/**
+ * Non-exception problem, built by `violation(name)`. A plain branded object
+ * (not an Error subclass) so `.message()` can be a builder method without
+ * colliding with `Error.prototype.message`.
+ */
+interface Violation {
+    readonly __seViolation: true;
+    readonly violationName: string;
+    readonly violationMessage?: string;
+    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
+    message(msg: string): Violation;
+}
+/**
+ * Identity of a problem that see() already reported, carried on the wire as
+ * the `caused_by` of a later occurrence. Holds exactly the fields the worker's
+ * fingerprint function consumes (raw `message`/`stack` — the server normalizes
+ * them) so the backend can recompute the prior issue's fingerprint and link
+ * the two issues. See `findCausedBy` for how the link is discovered.
+ */
+interface SeeCausedBy {
+    error_type: string;
+    message: string;
+    stack?: string;
+    subject: string;
+    outcome: string;
+}
+/** Wire shape — the `type:"error"` RawEvent variant accepted by POST /collect. */
+interface SeeErrorEvent {
+    type: "error";
+    kind: SeeKind;
+    /** Error class/name (e.g. "TypeError") or the violation name. */
+    error_type: string;
+    message: string;
+    stack?: string;
+    /** Consequence: "<error_type> causes the <subject> to <outcome>". */
+    subject: string;
+    outcome: string;
+    extras?: Record<string, string | number | boolean>;
+    url?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    side: "client" | "server";
+    env?: string;
+    sdk_version: string;
+    ts: number;
+    /**
+     * The earlier reported problem this occurrence descends from — present when
+     * the same error was caught + reported at an inner boundary and then
+     * re-thrown (or wrapped via `{ cause }`) and reported again at an outer one.
+     * Lets the backend stitch the two issues into a cause chain instead of
+     * double-counting them as unrelated.
+     */
+    caused_by?: SeeCausedBy;
+}
+interface SeeExtrasTail {
+    /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
+    extras(extras: SeeExtras): SeeExtrasTail;
+}
+interface SeeOutcomeStep {
+    /** The user-visible impact: `.causes_the("checkout").to("use cached prices")`. */
+    to(outcome: string): SeeExtrasTail;
+}
+interface SeeChain {
+    /** Start the consequence sentence — the product surface affected. */
+    causes_the(subject: string): SeeOutcomeStep;
+    /** camelCase alias of {@link SeeChain.causes_the}. */
+    causesThe(subject: string): SeeOutcomeStep;
+}
+interface SeeViolationChain extends SeeChain {
+    /** Free-form detail. Variable data goes here (or extras), never in the name. */
+    message(msg: string): SeeViolationChain;
+}
+
 declare global {
     interface Window {
         i18n?: {
@@ -8,7 +89,7 @@ declare global {
         };
     }
 }
-declare const version = "1.0.0";
+declare const version = "4.0.0";
 interface User {
     user_id?: string;
     [attr: string]: unknown;
@@ -51,6 +132,13 @@ interface FlagsClientBrowserOptions {
      * true when `autoGuardrails` is true).
      */
     autoGuardrailGroups?: Partial<AutoCollectGroups>;
+    /**
+     * Emit `__auto_*` metric events for ALL visitors, not just experiment
+     * participants. Default false: auto-metrics are gated on the visitor having
+     * seen ≥1 experiment exposure (the only data the analysis pipeline reads;
+     * ungated emission is pure AE write cost at scale — see cost.md).
+     */
+    autoCollectAlways?: boolean;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientBrowserEnv;
     /**
@@ -68,12 +156,14 @@ declare class FlagsClientBrowser {
     private readonly baseUrl;
     private readonly autoGuardrails;
     private readonly autoGuardrailGroups;
+    private readonly autoCollectAlways;
     private readonly env;
     private evalResult;
     private anonId;
     private userId;
     private buffer;
     private telemetry;
+    private seeLimiter;
     private guardrailsInstalled;
     private listeners;
     private overrideListenerInstalled;
@@ -81,6 +171,12 @@ declare class FlagsClientBrowser {
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
     identify(user: User): Promise<void>;
+    /**
+     * Report a structured error into the errors primitive. Flushes immediately
+     * (beacon-first) — error occurrences are near-real-time, never queued behind
+     * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
@@ -171,10 +267,11 @@ interface ShipeasyClientConfig {
      */
     autoIdentify?: boolean;
     /**
-     * Capture web vitals (LCP, CLS, INP, TTFB, FCP, navigation timing), JS /
-     * network errors, and engagement signals (abandonment) as `__auto_*`
-     * metric events. Defaults to `true` — the worker bypasses event-catalog
-     * validation for `__auto_*` names so this is safe out of the box.
+     * Capture web vitals (LCP, CLS, INP, TTFB, FCP, navigation timing) and
+     * engagement signals (abandonment) as `__auto_*` metric events, plus JS /
+     * network errors as structured error events in the errors primitive (same
+     * pipeline as `see()` — grouped by fingerprint, near-real-time). Defaults
+     * to `true`.
      *
      * Pass `false` to disable everything, or a per-group object to narrow:
      *
@@ -183,8 +280,23 @@ interface ShipeasyClientConfig {
      * shipeasy({ clientKey, autoCollect: { errors: false } });   // vitals + engagement only
      * shipeasy({ clientKey });                                   // all groups on
      * ```
+     *
+     * Since 4.1.0, `__auto_*` metric events are only emitted for visitors who
+     * are in ≥1 active experiment (the analysis pipeline reads nothing else;
+     * gating cuts the dominant Analytics Engine write cost at scale). Pass
+     * `{ always: true }` to collect site-wide vitals regardless of experiment
+     * participation:
+     *
+     * ```ts
+     * shipeasy({ clientKey, autoCollect: { always: true } });    // site-wide vitals
+     * ```
+     *
+     * `__auto_abandoned` is always emitted (it fires when the user leaves
+     * before exposures could land) and error capture is unaffected.
      */
-    autoCollect?: boolean | Partial<AutoCollectGroups>;
+    autoCollect?: boolean | (Partial<AutoCollectGroups> & {
+        always?: boolean;
+    });
     /**
      * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
@@ -276,6 +388,58 @@ declare const flags: {
     /** True once identify() has completed and flags are available. */
     readonly ready: boolean;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/client";
+     *
+     * try {
+     *   await submitOrder(order);
+     * } catch (e) {
+     *   see(e).causes_the("checkout").to("use cached prices").extras({ order_id: order.id });
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask, so the report ships
+     * immediately after the statement (no `.send()` needed) into the errors
+     * primitive — grouped by fingerprint, near-real-time timeseries. If you
+     * don't know the consequence of an exception, don't catch it.
+     */
+    (problem: unknown): SeeChain;
+    /**
+     * Report a non-exception problem. Prefer passing a caught Error to `see()`
+     * when one exists. The name is a stable identifier (it participates in the
+     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     *
+     * ```ts
+     * if (rows.length > LIMIT) {
+     *   see.Violation("large query").message(`got ${rows.length} rows`)
+     *      .causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — auto-capture skips it and
+     * nothing is reported. The reason must start with "because".
+     *
+     * ```ts
+     * } catch (e) {
+     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   return decodeAsBar(blob);
+     * }
+     * ```
+     */
+    ControlFlowException(err: unknown, because: string): void;
+}
+/**
+ * Structured error reporter — the whole grammar hangs off this one import.
+ * Safe to import anywhere; a call before `shipeasy({ clientKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 declare const LABEL_MARKER_START = "\uFFF9";
 declare const LABEL_MARKER_SEP = "\uFFFA";
 declare const LABEL_MARKER_END = "\uFFFB";
@@ -314,4 +478,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, see, shipeasy, version };