@shipeasy/sdk 3.0.1 → 4.1.0

package/dist/server/index.d.mts

@@ -1,4 +1,63 @@
-declare const version = "1.0.0";
+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;
+}
+/** 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;
+}
+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 const version = "4.0.0";
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -51,11 +110,24 @@ interface FlagsClientOptions {
      * for tests; production callers should rely on init()/initOnce().
      */
     initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly telemetry;
+    private readonly seeLimiter;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -75,6 +147,12 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Report a structured error into the errors primitive. Fire-and-forget —
+     * never blocks or throws into the request path. Spam-guarded by a 30s
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     /**
      * Evaluate all flags, configs, and experiments for a user against the locally
      * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -147,6 +225,12 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
+     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     */
+    disableTelemetry?: boolean;
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;
@@ -211,5 +295,49 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/server";
+     *
+     * try {
+     *   await chargeCard(order);
+     * } catch (e) {
+     *   see(e).causes_the("payment").to("use the backup processor").extras({ order_id: order.id });
+     *   await chargeViaBackup(order);
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask — fire-and-forget 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 (results.length > LIMIT) {
+     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — documents the expectation and
+     * reports nothing. The reason must start with "because".
+     */
+    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({ serverKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, see, shipeasy, version };

package/dist/server/index.d.ts

@@ -1,4 +1,63 @@
-declare const version = "1.0.0";
+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;
+}
+/** 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;
+}
+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 const version = "4.0.0";
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -51,11 +110,24 @@ interface FlagsClientOptions {
      * for tests; production callers should rely on init()/initOnce().
      */
     initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly telemetry;
+    private readonly seeLimiter;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -75,6 +147,12 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Report a structured error into the errors primitive. Fire-and-forget —
+     * never blocks or throws into the request path. Spam-guarded by a 30s
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     /**
      * Evaluate all flags, configs, and experiments for a user against the locally
      * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -147,6 +225,12 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
+     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     */
+    disableTelemetry?: boolean;
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;
@@ -211,5 +295,49 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/server";
+     *
+     * try {
+     *   await chargeCard(order);
+     * } catch (e) {
+     *   see(e).causes_the("payment").to("use the backup processor").extras({ order_id: order.id });
+     *   await chargeViaBackup(order);
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask — fire-and-forget 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 (results.length > LIMIT) {
+     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — documents the expectation and
+     * reports nothing. The reason must start with "because".
+     */
+    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({ serverKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, see, shipeasy, version };