@shipeasy/sdk 6.0.0 → 6.2.0

package/dist/server/index.js

@@ -37,7 +37,10 @@ __export(server_exports, {
   _murmur3ForTests: () => _murmur3ForTests,
   _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
+  clearOverrides: () => clearOverrides,
   configure: () => configure,
+  configureForOffline: () => configureForOffline,
+  configureForTesting: () => configureForTesting,
   configureShipeasyServer: () => configureShipeasyServer,
   createInMemoryStickyStore: () => createInMemoryStickyStore,
   fetchLabelsForSSR: () => fetchLabelsForSSR,
@@ -47,6 +50,10 @@ __export(server_exports, {
   getShipeasyServerClient: () => getShipeasyServerClient,
   i18n: () => i18n,
   isExpected: () => isExpected,
+  onChange: () => onChange,
+  overrideConfig: () => overrideConfig,
+  overrideExperiment: () => overrideExperiment,
+  overrideFlag: () => overrideFlag,
   see: () => see,
   seeContext: () => seeContext,
   shipeasy: () => shipeasy,
@@ -981,7 +988,11 @@ var Engine = class _Engine {
     const ks = this.flagsBlob?.killswitches?.[name];
     if (!ks) return false;
     if (switchKey === void 0) return isEnabled(ks.killed);
-    return isEnabled(ks.switches?.[switchKey]);
+    const switches = ks.switches ?? {};
+    if (Object.prototype.hasOwnProperty.call(switches, switchKey)) {
+      return isEnabled(switches[switchKey]);
+    }
+    return isEnabled(ks.killed);
   }
 };
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -1293,16 +1304,74 @@ var flags = {
 var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
 var _attributes = _identityAttributes;
 function configure(opts) {
-  const { attributes, ...engineOpts } = opts;
+  const { attributes, poll = false, init = true, ...engineOpts } = opts;
   _attributes = attributes ?? _identityAttributes;
   const engine = configureShipeasyServer(engineOpts);
-  void engine.initOnce().catch(() => {
-  });
+  if (poll) {
+    void engine.init().catch(() => {
+    });
+  } else if (init) {
+    void engine.initOnce().catch(() => {
+    });
+  }
   return engine;
 }
 function _resetConfigureForTests() {
   _attributes = _identityAttributes;
 }
+function _installGlobalEngine(engine, attributes) {
+  _server?.destroy();
+  _server = engine;
+  _attributes = attributes ?? _identityAttributes;
+  return engine;
+}
+function _applyOverrides(engine, flags2, configs, experiments) {
+  for (const [name, value] of Object.entries(flags2 ?? {})) engine.overrideFlag(name, value);
+  for (const [name, value] of Object.entries(configs ?? {})) engine.overrideConfig(name, value);
+  for (const [name, [group, params]] of Object.entries(experiments ?? {}))
+    engine.overrideExperiment(name, group, params);
+}
+function configureForTesting(opts = {}) {
+  const engine = Engine.forTesting();
+  _applyOverrides(engine, opts.flags, opts.configs, opts.experiments);
+  return _installGlobalEngine(engine, opts.attributes);
+}
+function configureForOffline(opts) {
+  let engine;
+  if (opts.path !== void 0) {
+    engine = Engine.fromFile(opts.path);
+  } else if (opts.snapshot !== void 0) {
+    engine = Engine.fromSnapshot(opts.snapshot);
+  } else {
+    throw new Error("[shipeasy] configureForOffline requires either { snapshot } or { path }");
+  }
+  _applyOverrides(engine, opts.flags, opts.configs, opts.experiments);
+  return _installGlobalEngine(engine, opts.attributes);
+}
+function _requireGlobal(fn) {
+  const engine = getShipeasyServerClient();
+  if (!engine) {
+    throw new Error(
+      `[shipeasy] ${fn}(...) called before configure({ apiKey }) (or a configureFor* sibling).`
+    );
+  }
+  return engine;
+}
+function overrideFlag(name, value) {
+  _requireGlobal("overrideFlag").overrideFlag(name, value);
+}
+function overrideConfig(name, value) {
+  _requireGlobal("overrideConfig").overrideConfig(name, value);
+}
+function overrideExperiment(name, group, params) {
+  _requireGlobal("overrideExperiment").overrideExperiment(name, group, params);
+}
+function clearOverrides() {
+  _requireGlobal("clearOverrides").clearOverrides();
+}
+function onChange(listener) {
+  return _requireGlobal("onChange").onChange(listener);
+}
 var Client = class {
   engine;
   /** The resolved attribute bag this handle evaluates against. */
@@ -1333,6 +1402,27 @@ var Client = class {
   getKillswitch(name, switchKey) {
     return this.engine.getKillswitch(name, switchKey);
   }
+  /**
+   * Record a conversion/metric event for the bound user. Derives the unit from
+   * the resolved attribute bag (`user_id`, else `anonymous_id`) and delegates to
+   * {@link Engine.track} — so an experiment is end-to-end Client-only (no need to
+   * drop down to the Engine to log a conversion). Fire-and-forget; no-op in test
+   * mode.
+   */
+  track(eventName, props) {
+    const id = this.attributes.user_id ?? this.attributes.anonymous_id;
+    if (id === void 0) return;
+    this.engine.track(String(id), eventName, props);
+  }
+  /**
+   * Emit an exposure event for `name` at this server-side decision point for the
+   * bound user. Delegates to {@link Engine.logExposure} with the resolved
+   * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
+   * in test mode).
+   */
+  logExposure(name) {
+    this.engine.logExposure(this.attributes, name);
+  }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
@@ -1357,7 +1447,10 @@ var see = Object.assign(
   _murmur3ForTests,
   _resetConfigureForTests,
   _resetShipeasyServerForTests,
+  clearOverrides,
   configure,
+  configureForOffline,
+  configureForTesting,
   configureShipeasyServer,
   createInMemoryStickyStore,
   fetchLabelsForSSR,
@@ -1367,6 +1460,10 @@ var see = Object.assign(
   getShipeasyServerClient,
   i18n,
   isExpected,
+  onChange,
+  overrideConfig,
+  overrideExperiment,
+  overrideFlag,
   see,
   seeContext,
   shipeasy,

package/dist/server/index.mjs

@@ -934,7 +934,11 @@ var Engine = class _Engine {
     const ks = this.flagsBlob?.killswitches?.[name];
     if (!ks) return false;
     if (switchKey === void 0) return isEnabled(ks.killed);
-    return isEnabled(ks.switches?.[switchKey]);
+    const switches = ks.switches ?? {};
+    if (Object.prototype.hasOwnProperty.call(switches, switchKey)) {
+      return isEnabled(switches[switchKey]);
+    }
+    return isEnabled(ks.killed);
   }
 };
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -1246,16 +1250,74 @@ var flags = {
 var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
 var _attributes = _identityAttributes;
 function configure(opts) {
-  const { attributes, ...engineOpts } = opts;
+  const { attributes, poll = false, init = true, ...engineOpts } = opts;
   _attributes = attributes ?? _identityAttributes;
   const engine = configureShipeasyServer(engineOpts);
-  void engine.initOnce().catch(() => {
-  });
+  if (poll) {
+    void engine.init().catch(() => {
+    });
+  } else if (init) {
+    void engine.initOnce().catch(() => {
+    });
+  }
   return engine;
 }
 function _resetConfigureForTests() {
   _attributes = _identityAttributes;
 }
+function _installGlobalEngine(engine, attributes) {
+  _server?.destroy();
+  _server = engine;
+  _attributes = attributes ?? _identityAttributes;
+  return engine;
+}
+function _applyOverrides(engine, flags2, configs, experiments) {
+  for (const [name, value] of Object.entries(flags2 ?? {})) engine.overrideFlag(name, value);
+  for (const [name, value] of Object.entries(configs ?? {})) engine.overrideConfig(name, value);
+  for (const [name, [group, params]] of Object.entries(experiments ?? {}))
+    engine.overrideExperiment(name, group, params);
+}
+function configureForTesting(opts = {}) {
+  const engine = Engine.forTesting();
+  _applyOverrides(engine, opts.flags, opts.configs, opts.experiments);
+  return _installGlobalEngine(engine, opts.attributes);
+}
+function configureForOffline(opts) {
+  let engine;
+  if (opts.path !== void 0) {
+    engine = Engine.fromFile(opts.path);
+  } else if (opts.snapshot !== void 0) {
+    engine = Engine.fromSnapshot(opts.snapshot);
+  } else {
+    throw new Error("[shipeasy] configureForOffline requires either { snapshot } or { path }");
+  }
+  _applyOverrides(engine, opts.flags, opts.configs, opts.experiments);
+  return _installGlobalEngine(engine, opts.attributes);
+}
+function _requireGlobal(fn) {
+  const engine = getShipeasyServerClient();
+  if (!engine) {
+    throw new Error(
+      `[shipeasy] ${fn}(...) called before configure({ apiKey }) (or a configureFor* sibling).`
+    );
+  }
+  return engine;
+}
+function overrideFlag(name, value) {
+  _requireGlobal("overrideFlag").overrideFlag(name, value);
+}
+function overrideConfig(name, value) {
+  _requireGlobal("overrideConfig").overrideConfig(name, value);
+}
+function overrideExperiment(name, group, params) {
+  _requireGlobal("overrideExperiment").overrideExperiment(name, group, params);
+}
+function clearOverrides() {
+  _requireGlobal("clearOverrides").clearOverrides();
+}
+function onChange(listener) {
+  return _requireGlobal("onChange").onChange(listener);
+}
 var Client = class {
   engine;
   /** The resolved attribute bag this handle evaluates against. */
@@ -1286,6 +1348,27 @@ var Client = class {
   getKillswitch(name, switchKey) {
     return this.engine.getKillswitch(name, switchKey);
   }
+  /**
+   * Record a conversion/metric event for the bound user. Derives the unit from
+   * the resolved attribute bag (`user_id`, else `anonymous_id`) and delegates to
+   * {@link Engine.track} — so an experiment is end-to-end Client-only (no need to
+   * drop down to the Engine to log a conversion). Fire-and-forget; no-op in test
+   * mode.
+   */
+  track(eventName, props) {
+    const id = this.attributes.user_id ?? this.attributes.anonymous_id;
+    if (id === void 0) return;
+    this.engine.track(String(id), eventName, props);
+  }
+  /**
+   * Emit an exposure event for `name` at this server-side decision point for the
+   * bound user. Delegates to {@link Engine.logExposure} with the resolved
+   * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
+   * in test mode).
+   */
+  logExposure(name) {
+    this.engine.logExposure(this.attributes, name);
+  }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
@@ -1309,7 +1392,10 @@ export {
   _murmur3ForTests,
   _resetConfigureForTests,
   _resetShipeasyServerForTests,
+  clearOverrides,
   configure,
+  configureForOffline,
+  configureForTesting,
   configureShipeasyServer,
   createInMemoryStickyStore,
   fetchLabelsForSSR,
@@ -1319,6 +1405,10 @@ export {
   getShipeasyServerClient,
   i18n,
   isExpected,
+  onChange,
+  overrideConfig,
+  overrideExperiment,
+  overrideFlag,
   see,
   seeContext,
   shipeasy,

package/dist/skill-cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/skill-cli.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var DEFAULT_DEST = ".claude/skills/shipeasy-typescript/SKILL.md";
+function skillText() {
+  const candidates = [
+    (0, import_node_path.join)(__dirname, "..", "docs", "skill", "SKILL.md"),
+    (0, import_node_path.join)(__dirname, "..", "..", "docs", "skill", "SKILL.md")
+  ];
+  for (const p of candidates) {
+    try {
+      if ((0, import_node_fs.existsSync)(p)) return (0, import_node_fs.readFileSync)(p, "utf8");
+    } catch {
+    }
+  }
+  throw new Error("shipeasy-skill: bundled SKILL.md not found in the package.");
+}
+function install(dir, force) {
+  let dest = (0, import_node_path.resolve)(dir);
+  const looksLikeDir = (0, import_node_fs.existsSync)(dest) && (0, import_node_fs.statSync)(dest).isDirectory() || !/\.[^/]+$/.test(dest);
+  if (looksLikeDir) dest = (0, import_node_path.join)(dest, "SKILL.md");
+  if ((0, import_node_fs.existsSync)(dest) && !force) {
+    process.stderr.write(`shipeasy-skill: refusing to overwrite ${dest} \u2014 pass --force
+`);
+    return 1;
+  }
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(dest), { recursive: true });
+  (0, import_node_fs.writeFileSync)(dest, skillText(), "utf8");
+  process.stdout.write(`shipeasy-skill: installed the Shipeasy agent skill \u2192 ${dest}
+`);
+  return 0;
+}
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (cmd === "print") {
+    process.stdout.write(skillText());
+    return 0;
+  }
+  if (cmd === "install") {
+    let dir = DEFAULT_DEST;
+    let force = false;
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === "--force") force = true;
+      else if (rest[i] === "--dir") dir = rest[++i] ?? DEFAULT_DEST;
+    }
+    return install(dir, force);
+  }
+  process.stdout.write(
+    "shipeasy-skill \u2014 install the Shipeasy agent skill.\n\n  shipeasy-skill install [--dir <path>] [--force]\n  shipeasy-skill print\n"
+  );
+  return cmd && cmd !== "--help" && cmd !== "-h" ? 1 : 0;
+}
+process.exit(main(process.argv.slice(2)));

package/docs/skill/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: shipeasy-typescript
+description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from TypeScript / JavaScript. Covers configure() + Client(user), getFlag/getConfig/getKillswitch/getExperiment, track, testing, OpenFeature, and the see() error reporter — server (@shipeasy/sdk/server) and browser (@shipeasy/sdk/client).
+---
+
+# Shipeasy TypeScript SDK
+
+`@shipeasy/sdk` — one package, two entrypoints: `@shipeasy/sdk/server` (Node /
+Cloudflare Worker / Deno, **server** key) and `@shipeasy/sdk/client` (browser,
+public **client** key). Everything works from vanilla JS.
+
+> The documented surface is exactly **`configure()`** (setup) and the bound
+> **`new Client(user)`** (use), plus the package-level helpers below. For deeper
+> docs, fetch any page/snippet from the manifest at
+> <https://shipeasy-ai.github.io/sdk/manifest.json> (raw page/snippet URLs below).
+
+## Install
+
+```bash
+npm install @shipeasy/sdk
+```
+
+## Configure once, evaluate per user
+
+```ts
+import { configure, Client } from "@shipeasy/sdk/server"; // or "@shipeasy/sdk/client"
+
+configure({
+  apiKey: process.env.SHIPEASY_SERVER_KEY!,           // browser: clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY
+  attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan }), // optional; omit = identity
+  // poll: true  // long-running server: keep flags fresh with a background poll (no engine.init() needed)
+});
+
+const flags = new Client(currentUser); // browser: await flags.ready() before first read
+
+flags.getFlag("new_checkout");                         // boolean (2nd arg = default if not-ready/not-found)
+flags.getConfig<{ max: number }>("limits", { defaultValue: { max: 50 } });
+flags.getKillswitch("payments");                       // global on/off (not user-bound)
+flags.getFlagDetail("new_checkout");                   // { value, reason }
+```
+
+`configure()` is first-config-wins and owns the fetch lifecycle (one-shot by
+default; `poll: true` for a background refresh). Construct `new Client(user)` once
+per user/request — it binds the user, so no method takes a user argument.
+Full reference: <https://shipeasy-ai.github.io/sdk/pages/configuration.md> ·
+<https://shipeasy-ai.github.io/sdk/pages/flags.md> ·
+snippets <https://shipeasy-ai.github.io/sdk/snippets/release/flags.md> ·
+<https://shipeasy-ai.github.io/sdk/snippets/release/configs.md> ·
+<https://shipeasy-ai.github.io/sdk/snippets/release/killswitches.md>
+
+## Experiments + track (Client-only, end to end)
+
+```ts
+const flags = new Client(currentUser); // construct once per callsite
+const { inExperiment, group, params } = flags.getExperiment("hero_cta", {
+  primary_label: "Sign up", // default params (control / not-enrolled)
+});
+render(params.primary_label);
+
+flags.logExposure("hero_cta");          // record the exposure where you present it
+flags.track("purchase", { value: 42 }); // record a conversion for the bound user
+```
+
+`ExperimentResult = { inExperiment: boolean; group: string; params: P }`. Full
+reference: <https://shipeasy-ai.github.io/sdk/pages/experiments.md> · track snippet
+<https://shipeasy-ai.github.io/sdk/snippets/metrics/track.md>
+
+## i18n
+
+Full i18n ships in this SDK. Wire the loader via the SSR bootstrap (no separate
+init), then render with `i18n.t`:
+
+```ts
+import { i18n } from "@shipeasy/sdk/client";
+i18n.t("checkout.cta", "Place order");
+i18n.t("cart.count", "{count} items", { count: cart.length });
+```
+
+Full reference: <https://shipeasy-ai.github.io/sdk/pages/i18n.md> · snippets
+<https://shipeasy-ai.github.io/sdk/snippets/i18n/setup.md> ·
+<https://shipeasy-ai.github.io/sdk/snippets/i18n/render.md>
+
+## Error reporting (see)
+
+```ts
+import { see } from "@shipeasy/sdk/server"; // or /client
+
+try { await submitOrder(order); }
+catch (e) { see(e).causes_the("checkout").to("use cached prices").extras({ order_id: order.id }); }
+
+see.Violation("large query").causes_the("results").to("be trimmed").extras({ rows });
+see.ControlFlowException(e).because("because it wasn't an encoded Foo"); // expected — reports nothing
+```
+
+Fire-and-forget on the next microtask (no `.send()`). Don't catch what you can't
+name a consequence for. You may `see()` then re-throw (links as `caused_by`). Full
+reference: <https://shipeasy-ai.github.io/sdk/pages/error-reporting.md> · snippet
+<https://shipeasy-ai.github.io/sdk/snippets/ops/see.md>
+
+## Testing — no network
+
+```ts
+import { configureForTesting, configureForOffline, Client, overrideFlag, clearOverrides } from "@shipeasy/sdk/server";
+
+// Seed values up front; reads go through the ordinary new Client(user). Replaces
+// prior config, so each test can reconfigure freely.
+configureForTesting({
+  flags: { new_checkout: true },
+  configs: { limits: { max: 50 } },
+  experiments: { hero_cta: ["treatment", { primary_label: "Buy now" }] },
+});
+const flags = new Client({ user_id: "u_1" });
+flags.getFlag("new_checkout"); // true
+
+overrideFlag("new_checkout", false); // flip on the spot
+clearOverrides();                    // drop every override (incl. the seed)
+
+// Offline: evaluate the REAL rules from a snapshot or JSON file, no network.
+configureForOffline({ path: "./shipeasy-snapshot.json" });
+// or: configureForOffline({ snapshot: { flags, experiments }, flags: { new_checkout: true } });
+```
+
+Full reference: <https://shipeasy-ai.github.io/sdk/pages/testing.md>
+
+## OpenFeature
+
+```ts
+import { OpenFeature } from "@openfeature/server-sdk";
+import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-server"; // or /openfeature-web
+
+// Assumes configure({ apiKey }) ran at startup — the no-arg provider resolves it.
+await OpenFeature.setProviderAndWait(new ShipeasyProvider());
+await OpenFeature.getClient().getBooleanValue("new_checkout", false, { targetingKey: "u1" });
+```
+
+Full reference: <https://shipeasy-ai.github.io/sdk/pages/openfeature.md>
+
+## Advanced
+
+`privateAttributes`, `bucketBy` (custom bucketing unit), `stickyBucketing`
+(browser: on by default, `__se_sticky` cookie), manual exposure
+(`getExperiment(..., { logExposure: false })` + `flags.logExposure(name)`),
+`onChange(cb)` (requires `configure({ poll: true })`) / browser `subscribe()`.
+Devtools overlay: `Shift+Alt+S` or `?se=1`. Full reference:
+<https://shipeasy-ai.github.io/sdk/pages/advanced.md>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -59,12 +59,17 @@
     },
     "./templates/*": "./templates/*.js"
   },
+  "bin": {
+    "shipeasy-skill": "./dist/skill-cli.js"
+  },
   "files": [
     "dist/server/",
     "dist/client/",
     "dist/next/",
     "dist/openfeature-server/",
     "dist/openfeature-web/",
+    "dist/skill-cli.js",
+    "docs/skill/SKILL.md",
     "templates/",
     "LICENSE",
     "README.md"
@@ -74,6 +79,7 @@
     "type-check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "gen:readme": "node scripts/gen-readme.mjs",
     "publish-loader": "wrangler r2 object put shipeasy-sdk/loader-v$npm_package_version.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=31536000, immutable' --remote && wrangler r2 object put shipeasy-sdk/loader.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=300' --remote"
   },
   "dependencies": {