@shipeasy/sdk 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,40 @@
+Shipeasy Source-Available License (Shipeasy-SAL) 1.0
+
+Copyright (c) 2026 Shipeasy, Inc. All rights reserved.
+
+1. License Grant.
+   Subject to the terms of this License, Shipeasy, Inc. ("Shipeasy") grants
+   you a non-exclusive, non-transferable, revocable, worldwide license to:
+
+   (a) Use, copy, and modify the Software solely as a client integration for
+       interacting with Shipeasy's hosted services (the "Service");
+   (b) Distribute the Software as part of an application that calls the
+       Service, in object form, provided the recipient also agrees to this
+       License.
+
+2. Restrictions.
+   You may not:
+
+   (a) Use the Software, in whole or in part, to build, host, or operate any
+       service that competes with the Service or that provides feature-flag,
+       experimentation, configuration, internationalization, or related
+       functionality to third parties on a commercial basis;
+   (b) Sublicense, sell, rent, or lease the Software;
+   (c) Remove or alter copyright notices, license terms, or attribution.
+
+3. Contributions.
+   Any pull request you submit is licensed back to Shipeasy under this
+   License plus a perpetual, irrevocable right for Shipeasy to relicense.
+
+4. Trademarks.
+   This License does not grant rights in the names "Shipeasy", related
+   marks, or logos.
+
+5. No Warranty / Limitation of Liability.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO
+   EVENT SHALL SHIPEASY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY ARISING FROM USE OF THE SOFTWARE.
+
+6. Termination.
+   This License terminates automatically if you breach it. Sections 2-5
+   survive termination.

package/README.md

@@ -0,0 +1,94 @@
+# @shipeasy/sdk
+
+Feature gates, runtime configs, experiments, and metrics for the
+[Shipeasy](https://shipeasy.ai) hosted service.
+
+> Source-available under the [Shipeasy-SAL 1.0](./LICENSE). Use it freely
+> as a client of Shipeasy. Don't use it to build a competing service.
+
+## Install
+
+```bash
+npm install @shipeasy/sdk
+# or
+pnpm add @shipeasy/sdk
+```
+
+For React projects use [`@shipeasy/sdk-react`](https://github.com/shipeasy-ai/sdk-react)
+which wraps this package with a `<ShipeasyProvider>` and hooks.
+
+## Quickstart — browser
+
+```ts
+import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+
+const client = new FlagsClientBrowser({
+  sdkKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY!,
+});
+
+await client.identify({ user_id: "user-123", plan: "pro" });
+
+if (client.getFlag("new_checkout")) {
+  // ship it
+}
+
+const cfg = client.getConfig<{ max_uploads: number }>("upload_limits");
+const { params } = client.getExperiment("hero_cta", {
+  primary_label: "Sign up",
+});
+```
+
+`identify()` automatically merges browser context (`locale`, `timezone`,
+`path`, `referrer`, `screen_*`, `user_agent`) and a persisted
+`anonymous_id` into the payload — so gate rules can target by locale or
+holdouts can hash anonymous visitors out of the box.
+
+## Quickstart — server (Node, Cloudflare Worker, Deno)
+
+```ts
+import { FlagsClient } from "@shipeasy/sdk/server";
+
+const client = new FlagsClient({ sdkKey: process.env.SHIPEASY_SERVER_KEY! });
+
+const cfg = await client.getConfig("plan_limits", { user_id: "u-1" });
+```
+
+## Drop-in `<script>` loader (no bundler)
+
+```html
+<script
+  src="https://cdn.shipeasy.ai/sdk/loader.js"
+  data-sdk-key="sdk_client_..."
+  data-user-id="user-123"
+  data-user-email="u@x.com"
+  data-user-plan="pro"
+  data-attrs='{"country":"US"}'
+  defer
+></script>
+<script>
+  await window.shipeasy.ready;
+  if (window.shipeasy.getFlag("new_checkout")) { /* … */ }
+</script>
+```
+
+The loader IIFE is published to a public R2 bucket on every release and
+cached for 1y at `loader-vX.Y.Z.js` (immutable) plus a rolling 5-minute
+`loader.js`.
+
+## Devtools overlay
+
+Press `Shift+Alt+S` on any page running the SDK (or append `?se=1` to the
+URL). The Shipeasy devtools panel mounts in a Shadow DOM overlay and lets
+you flip every gate / config / experiment / translation **for the current
+session only** — handy for QA, demos, and bug repro.
+
+## Documentation
+
+Full docs at [docs.shipeasy.ai](https://docs.shipeasy.ai). API surfaces
+covered there: targeting rules, holdouts, sequential stats, custom
+metrics, Slack digests, OAuth/SSO, Claude/MCP integration.
+
+## License
+
+[Shipeasy-SAL 1.0](./LICENSE) — source-available, non-commercial-use,
+permitted for use as a Shipeasy client.

package/dist/client/index.d.mts

@@ -1,3 +1,13 @@
+declare global {
+    interface Window {
+        i18n?: {
+            t: (key: string, vars?: Record<string, string | number>) => string;
+            ready: (cb: () => void) => void;
+            on: (event: "update", cb: () => void) => () => void;
+            locale: string | null;
+        };
+    }
+}
 declare const version = "1.0.0";
 interface User {
     user_id?: string;
@@ -8,41 +18,167 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
-interface EvalFlagResult {
-    enabled: boolean;
-}
 interface EvalExpResult {
-    in_experiment: boolean;
+    inExperiment: boolean;
     group: string;
     params: Record<string, unknown>;
 }
 interface EvalResponse {
-    flags: Record<string, EvalFlagResult>;
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
 }
+type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
 interface FlagsClientBrowserOptions {
     sdkKey: string;
     baseUrl?: string;
     autoGuardrails?: boolean;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientBrowserEnv;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
     private readonly baseUrl;
     private readonly autoGuardrails;
+    private readonly env;
     private evalResult;
     private anonId;
     private userId;
     private buffer;
     private guardrailsInstalled;
+    private listeners;
+    private overrideListenerInstalled;
+    private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
     identify(user: User): Promise<void>;
+    get ready(): boolean;
+    private notify;
     initFromBootstrap(data: EvalResponse): void;
     getFlag(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    /**
+     * Subscribe to state changes — fires after identify() completes and on
+     * `se:override:change` events from the devtools overlay. Returns an
+     * unsubscribe function. Used by framework adapters to trigger re-renders.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Publishes the SDK to `window.__shipeasy` so the devtools overlay can read
+     * current values. Idempotent. Returns the bridge object for tests.
+     */
+    installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
     flush(): Promise<void>;
     destroy(): void;
 }
+declare function readGateOverride(name: string): boolean | null;
+declare function readConfigOverride(name: string): unknown;
+declare function readExpOverride(name: string): string | null;
+declare function isDevtoolsRequested(): boolean;
+/** Bridge written to window.__shipeasy — mirrors @shipeasy/devtools' contract. */
+interface ShipeasySdkBridge {
+    getFlag(name: string): boolean;
+    getExperiment(name: string): {
+        inExperiment: boolean;
+        group: string;
+    } | undefined;
+    getConfig(name: string): unknown;
+}
+/**
+ * If the host page already mounted the standalone devtools IIFE bundle (which
+ * exposes `window.__shipeasy_devtools_global`), call its init() and wire up a
+ * toggle handle at `window.__shipeasy_devtools`. No-op when the bundle is
+ * absent — the customer is responsible for mounting it themselves.
+ */
+declare function loadDevtools(opts?: {
+    adminUrl?: string;
+    edgeUrl?: string;
+}): void;
+interface AttachDevtoolsOptions {
+    /** Hotkey string in the form "Shift+Alt+S". */
+    hotkey?: string;
+    adminUrl?: string;
+    edgeUrl?: string;
+}
+/**
+ * One-call bootstrap for the devtools overlay. Installs the bridge, optionally
+ * auto-loads the overlay if the page was opened with `?se`, registers a hotkey
+ * listener for opening/toggling the overlay, and re-publishes the bridge after
+ * each `identify()`/override change. Returns an unsubscribe function for
+ * cleanup (e.g. React effect teardown).
+ */
+declare function attachDevtools(client: FlagsClientBrowser, opts?: AttachDevtoolsOptions): () => void;
+/** Configure the singleton. Idempotent — re-calling with the same opts is a no-op. */
+declare function configureShipeasy(opts: FlagsClientBrowserOptions): FlagsClientBrowser;
+/** Returns the configured singleton, or null if configureShipeasy() hasn't run yet. */
+declare function getShipeasyClient(): FlagsClientBrowser | null;
+/**
+ * Test helper — drop the singleton so the next configureShipeasy() builds fresh.
+ * Not part of the documented surface; production code should never call this.
+ */
+declare function _resetShipeasyForTests(): void;
+/**
+ * Universal flags facade. Methods return safe defaults when the singleton
+ * hasn't been configured yet (false / undefined / `notIn` experiment), so
+ * importing this in a module that loads before app boot is harmless.
+ */
+declare const flags: {
+    configure(opts: FlagsClientBrowserOptions): void;
+    identify(user: User): Promise<void>;
+    /** Read a feature gate. Returns false until identify() resolves. */
+    get(name: string): boolean;
+    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    track(eventName: string, props?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    /** Subscribe for change notifications (identify/override). Used by framework adapters. */
+    subscribe(listener: () => void): () => void;
+    /** True once identify() has completed and flags are available. */
+    readonly ready: boolean;
+};
+declare const LABEL_MARKER_START = "\uFFF9";
+declare const LABEL_MARKER_SEP = "\uFFFA";
+declare const LABEL_MARKER_END = "\uFFFB";
+declare const LABEL_MARKER_RE: RegExp;
+declare function encodeLabelMarker(key: string, value: string): string;
+interface LabelAttrs {
+    "data-label": string;
+    "data-variables"?: string;
+    "data-label-desc"?: string;
+}
+declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
+/**
+ * Universal i18n facade. Backed by the `window.i18n` global the loader
+ * script installs. Returns the key itself when the loader hasn't run
+ * (SSR, missing script tag, before profile fetch completes), so call
+ * sites never need to null-check.
+ */
+declare const i18n: {
+    t(key: string, variables?: Record<string, string | number>): string;
+    /**
+     * Translate a key and return a framework element (e.g. React <span>)
+     * carrying `data-label` / `data-variables` attributes so the ShipEasy
+     * devtools "Edit labels" overlay can highlight and edit it in place.
+     *
+     * Requires a one-time setup call: `i18n.configure({ createElement })`.
+     * The returned value is whatever `createElement` returns — pass React's
+     * `createElement`, Vue's `h`, Solid's `createSignal`-based factory, etc.
+     *
+     * Falls back to a plain translated string if `createElement` was not
+     * configured (e.g. server-side or in non-JSX contexts).
+     */
+    tEl(key: string, variables?: Record<string, string | number>, desc?: string): any;
+    /** Wire up the element creator once at app startup (call before any tEl use). */
+    configure(opts: {
+        createElement: (tag: string, props: object, children: string) => any;
+    }): void;
+    readonly locale: string | null;
+    readonly ready: boolean;
+    /** Resolves when the loader has installed window.i18n and fetched a profile. */
+    whenReady(): Promise<void>;
+    /** Subscribe to locale/profile updates. Returns an unsubscribe fn. */
+    onUpdate(cb: () => void): () => void;
+};
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserOptions, type User, version };
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };

package/dist/client/index.d.ts

@@ -1,3 +1,13 @@
+declare global {
+    interface Window {
+        i18n?: {
+            t: (key: string, vars?: Record<string, string | number>) => string;
+            ready: (cb: () => void) => void;
+            on: (event: "update", cb: () => void) => () => void;
+            locale: string | null;
+        };
+    }
+}
 declare const version = "1.0.0";
 interface User {
     user_id?: string;
@@ -8,41 +18,167 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
-interface EvalFlagResult {
-    enabled: boolean;
-}
 interface EvalExpResult {
-    in_experiment: boolean;
+    inExperiment: boolean;
     group: string;
     params: Record<string, unknown>;
 }
 interface EvalResponse {
-    flags: Record<string, EvalFlagResult>;
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
 }
+type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
 interface FlagsClientBrowserOptions {
     sdkKey: string;
     baseUrl?: string;
     autoGuardrails?: boolean;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientBrowserEnv;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
     private readonly baseUrl;
     private readonly autoGuardrails;
+    private readonly env;
     private evalResult;
     private anonId;
     private userId;
     private buffer;
     private guardrailsInstalled;
+    private listeners;
+    private overrideListenerInstalled;
+    private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
     identify(user: User): Promise<void>;
+    get ready(): boolean;
+    private notify;
     initFromBootstrap(data: EvalResponse): void;
     getFlag(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    /**
+     * Subscribe to state changes — fires after identify() completes and on
+     * `se:override:change` events from the devtools overlay. Returns an
+     * unsubscribe function. Used by framework adapters to trigger re-renders.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Publishes the SDK to `window.__shipeasy` so the devtools overlay can read
+     * current values. Idempotent. Returns the bridge object for tests.
+     */
+    installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
     flush(): Promise<void>;
     destroy(): void;
 }
+declare function readGateOverride(name: string): boolean | null;
+declare function readConfigOverride(name: string): unknown;
+declare function readExpOverride(name: string): string | null;
+declare function isDevtoolsRequested(): boolean;
+/** Bridge written to window.__shipeasy — mirrors @shipeasy/devtools' contract. */
+interface ShipeasySdkBridge {
+    getFlag(name: string): boolean;
+    getExperiment(name: string): {
+        inExperiment: boolean;
+        group: string;
+    } | undefined;
+    getConfig(name: string): unknown;
+}
+/**
+ * If the host page already mounted the standalone devtools IIFE bundle (which
+ * exposes `window.__shipeasy_devtools_global`), call its init() and wire up a
+ * toggle handle at `window.__shipeasy_devtools`. No-op when the bundle is
+ * absent — the customer is responsible for mounting it themselves.
+ */
+declare function loadDevtools(opts?: {
+    adminUrl?: string;
+    edgeUrl?: string;
+}): void;
+interface AttachDevtoolsOptions {
+    /** Hotkey string in the form "Shift+Alt+S". */
+    hotkey?: string;
+    adminUrl?: string;
+    edgeUrl?: string;
+}
+/**
+ * One-call bootstrap for the devtools overlay. Installs the bridge, optionally
+ * auto-loads the overlay if the page was opened with `?se`, registers a hotkey
+ * listener for opening/toggling the overlay, and re-publishes the bridge after
+ * each `identify()`/override change. Returns an unsubscribe function for
+ * cleanup (e.g. React effect teardown).
+ */
+declare function attachDevtools(client: FlagsClientBrowser, opts?: AttachDevtoolsOptions): () => void;
+/** Configure the singleton. Idempotent — re-calling with the same opts is a no-op. */
+declare function configureShipeasy(opts: FlagsClientBrowserOptions): FlagsClientBrowser;
+/** Returns the configured singleton, or null if configureShipeasy() hasn't run yet. */
+declare function getShipeasyClient(): FlagsClientBrowser | null;
+/**
+ * Test helper — drop the singleton so the next configureShipeasy() builds fresh.
+ * Not part of the documented surface; production code should never call this.
+ */
+declare function _resetShipeasyForTests(): void;
+/**
+ * Universal flags facade. Methods return safe defaults when the singleton
+ * hasn't been configured yet (false / undefined / `notIn` experiment), so
+ * importing this in a module that loads before app boot is harmless.
+ */
+declare const flags: {
+    configure(opts: FlagsClientBrowserOptions): void;
+    identify(user: User): Promise<void>;
+    /** Read a feature gate. Returns false until identify() resolves. */
+    get(name: string): boolean;
+    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    track(eventName: string, props?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    /** Subscribe for change notifications (identify/override). Used by framework adapters. */
+    subscribe(listener: () => void): () => void;
+    /** True once identify() has completed and flags are available. */
+    readonly ready: boolean;
+};
+declare const LABEL_MARKER_START = "\uFFF9";
+declare const LABEL_MARKER_SEP = "\uFFFA";
+declare const LABEL_MARKER_END = "\uFFFB";
+declare const LABEL_MARKER_RE: RegExp;
+declare function encodeLabelMarker(key: string, value: string): string;
+interface LabelAttrs {
+    "data-label": string;
+    "data-variables"?: string;
+    "data-label-desc"?: string;
+}
+declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
+/**
+ * Universal i18n facade. Backed by the `window.i18n` global the loader
+ * script installs. Returns the key itself when the loader hasn't run
+ * (SSR, missing script tag, before profile fetch completes), so call
+ * sites never need to null-check.
+ */
+declare const i18n: {
+    t(key: string, variables?: Record<string, string | number>): string;
+    /**
+     * Translate a key and return a framework element (e.g. React <span>)
+     * carrying `data-label` / `data-variables` attributes so the ShipEasy
+     * devtools "Edit labels" overlay can highlight and edit it in place.
+     *
+     * Requires a one-time setup call: `i18n.configure({ createElement })`.
+     * The returned value is whatever `createElement` returns — pass React's
+     * `createElement`, Vue's `h`, Solid's `createSignal`-based factory, etc.
+     *
+     * Falls back to a plain translated string if `createElement` was not
+     * configured (e.g. server-side or in non-JSX contexts).
+     */
+    tEl(key: string, variables?: Record<string, string | number>, desc?: string): any;
+    /** Wire up the element creator once at app startup (call before any tEl use). */
+    configure(opts: {
+        createElement: (tag: string, props: object, children: string) => any;
+    }): void;
+    readonly locale: string | null;
+    readonly ready: boolean;
+    /** Resolves when the loader has installed window.i18n and fetched a profile. */
+    whenReady(): Promise<void>;
+    /** Subscribe to locale/profile updates. Returns an unsubscribe fn. */
+    onUpdate(cb: () => void): () => void;
+};
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserOptions, type User, version };
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };