@shipeasy/sdk 1.0.0 → 1.2.0

package/dist/server/index.d.ts

@@ -9,13 +9,17 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
     baseUrl?: string;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientEnv;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly env;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -36,5 +40,38 @@ declare class FlagsClient {
     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;
 }
+interface LabelFile {
+    v: number;
+    profile: string;
+    chunk: string;
+    strings: Record<string, string>;
+}
+interface FetchLabelsOptions {
+    key: string;
+    profile: string;
+    chunk?: string;
+    cdnBaseUrl?: string;
+    timeoutMs?: number;
+}
+declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
+declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
+declare function getShipeasyServerClient(): FlagsClient | null;
+declare function _resetShipeasyServerForTests(): void;
+declare const flags: {
+    configure(opts: FlagsClientOptions): void;
+    /**
+     * Long-running server: starts the background poll. Call once at app boot.
+     * Throws if the initial fetch fails (caller decides whether to crash or degrade).
+     */
+    init(): Promise<void>;
+    /** Serverless / edge: fetch rules once, no background timer. */
+    initOnce(): Promise<void>;
+    /** Stop background timers. Safe to call repeatedly. */
+    destroy(): void;
+    get(name: string, user: User): boolean;
+    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;
+};
 
-export { type ExperimentResult, FlagsClient, type FlagsClientOptions, type User, version };
+export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };

package/dist/server/index.js

@@ -21,6 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   FlagsClient: () => FlagsClient,
+  _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
+  configureShipeasyServer: () => configureShipeasyServer,
+  fetchLabelsForSSR: () => fetchLabelsForSSR,
+  flags: () => flags,
+  getShipeasyServerClient: () => getShipeasyServerClient,
   version: () => version
 });
 module.exports = __toCommonJS(server_exports);
@@ -127,6 +132,7 @@ function evalGateInternal(gate, user) {
 var FlagsClient = class {
   apiKey;
   baseUrl;
+  env;
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -137,6 +143,7 @@ var FlagsClient = class {
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.env = opts.env ?? "prod";
   }
   async init() {
     await this.fetchAll();
@@ -174,7 +181,7 @@ var FlagsClient = class {
   async fetchFlags() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
-    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags`, { headers });
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags?env=${this.env}`, { headers });
     const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
     if (res.status === 304) return interval;
     if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
@@ -265,8 +272,94 @@ var FlagsClient = class {
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
 };
+var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
+async function fetchJson(url, timeoutMs = 2e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      next: { revalidate: 60 }
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchLabelsForSSR(opts) {
+  const cdn = opts.cdnBaseUrl ?? DEFAULT_I18N_CDN;
+  const chunk = opts.chunk ?? "index";
+  try {
+    const manifest = await fetchJson(
+      `${cdn}/labels/${opts.key}/${opts.profile}/manifest.json`,
+      opts.timeoutMs
+    );
+    const fileUrl = manifest[chunk];
+    if (!fileUrl) return null;
+    return await fetchJson(fileUrl, opts.timeoutMs);
+  } catch {
+    return null;
+  }
+}
+var _server = null;
+function configureShipeasyServer(opts) {
+  if (_server) return _server;
+  _server = new FlagsClient(opts);
+  return _server;
+}
+function getShipeasyServerClient() {
+  return _server;
+}
+function _resetShipeasyServerForTests() {
+  _server?.destroy();
+  _server = null;
+}
+var flags = {
+  configure(opts) {
+    configureShipeasyServer(opts);
+  },
+  /**
+   * Long-running server: starts the background poll. Call once at app boot.
+   * Throws if the initial fetch fails (caller decides whether to crash or degrade).
+   */
+  init() {
+    if (!_server) throw new Error("[shipeasy] flags.init called before configure()");
+    return _server.init();
+  },
+  /** Serverless / edge: fetch rules once, no background timer. */
+  initOnce() {
+    if (!_server) throw new Error("[shipeasy] flags.initOnce called before configure()");
+    return _server.initOnce();
+  },
+  /** Stop background timers. Safe to call repeatedly. */
+  destroy() {
+    _server?.destroy();
+  },
+  get(name, user) {
+    return _server?.getFlag(name, user) ?? false;
+  },
+  getConfig(name, decode) {
+    return _server?.getConfig(name, decode);
+  },
+  getExperiment(name, user, defaultParams, decode) {
+    return _server?.getExperiment(name, user, defaultParams, decode) ?? {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+  },
+  track(userId, eventName, props) {
+    _server?.track(userId, eventName, props);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlagsClient,
+  _resetShipeasyServerForTests,
+  configureShipeasyServer,
+  fetchLabelsForSSR,
+  flags,
+  getShipeasyServerClient,
   version
 });

package/dist/server/index.mjs

@@ -102,6 +102,7 @@ function evalGateInternal(gate, user) {
 var FlagsClient = class {
   apiKey;
   baseUrl;
+  env;
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -112,6 +113,7 @@ var FlagsClient = class {
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.env = opts.env ?? "prod";
   }
   async init() {
     await this.fetchAll();
@@ -149,7 +151,7 @@ var FlagsClient = class {
   async fetchFlags() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
-    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags`, { headers });
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags?env=${this.env}`, { headers });
     const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
     if (res.status === 304) return interval;
     if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
@@ -240,7 +242,93 @@ var FlagsClient = class {
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
 };
+var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
+async function fetchJson(url, timeoutMs = 2e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      next: { revalidate: 60 }
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchLabelsForSSR(opts) {
+  const cdn = opts.cdnBaseUrl ?? DEFAULT_I18N_CDN;
+  const chunk = opts.chunk ?? "index";
+  try {
+    const manifest = await fetchJson(
+      `${cdn}/labels/${opts.key}/${opts.profile}/manifest.json`,
+      opts.timeoutMs
+    );
+    const fileUrl = manifest[chunk];
+    if (!fileUrl) return null;
+    return await fetchJson(fileUrl, opts.timeoutMs);
+  } catch {
+    return null;
+  }
+}
+var _server = null;
+function configureShipeasyServer(opts) {
+  if (_server) return _server;
+  _server = new FlagsClient(opts);
+  return _server;
+}
+function getShipeasyServerClient() {
+  return _server;
+}
+function _resetShipeasyServerForTests() {
+  _server?.destroy();
+  _server = null;
+}
+var flags = {
+  configure(opts) {
+    configureShipeasyServer(opts);
+  },
+  /**
+   * Long-running server: starts the background poll. Call once at app boot.
+   * Throws if the initial fetch fails (caller decides whether to crash or degrade).
+   */
+  init() {
+    if (!_server) throw new Error("[shipeasy] flags.init called before configure()");
+    return _server.init();
+  },
+  /** Serverless / edge: fetch rules once, no background timer. */
+  initOnce() {
+    if (!_server) throw new Error("[shipeasy] flags.initOnce called before configure()");
+    return _server.initOnce();
+  },
+  /** Stop background timers. Safe to call repeatedly. */
+  destroy() {
+    _server?.destroy();
+  },
+  get(name, user) {
+    return _server?.getFlag(name, user) ?? false;
+  },
+  getConfig(name, decode) {
+    return _server?.getConfig(name, decode);
+  },
+  getExperiment(name, user, defaultParams, decode) {
+    return _server?.getExperiment(name, user, defaultParams, decode) ?? {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+  },
+  track(userId, eventName, props) {
+    _server?.track(userId, eventName, props);
+  }
+};
 export {
   FlagsClient,
+  _resetShipeasyServerForTests,
+  configureShipeasyServer,
+  fetchLabelsForSSR,
+  flags,
+  getShipeasyServerClient,
   version
 };

package/package.json

@@ -1,10 +1,29 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "1.0.0",
-  "description": "Feature flag and experimentation SDK",
+  "version": "1.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shipeasy-ai/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shipeasy-ai/sdk/issues"
+  },
   "main": "./dist/server/index.js",
   "module": "./dist/server/index.mjs",
   "browser": "./dist/client/index.js",
+  "typesVersions": {
+    "*": {
+      "client": [
+        "./dist/client/index.d.ts"
+      ],
+      "server": [
+        "./dist/server/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "node": "./dist/server/index.js",
@@ -23,13 +42,18 @@
     "./templates/*": "./templates/*.js"
   },
   "files": [
-    "dist/",
-    "templates/"
+    "dist/server/",
+    "dist/client/",
+    "templates/",
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",
-    "test": "vitest"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "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": {
     "murmurhash-js": "^1.0.0"
@@ -38,7 +62,8 @@
     "@types/murmurhash-js": "^1.0.6",
     "tsup": "^8.3.0",
     "typescript": "^5.7.4",
-    "vitest": "^2.1.0"
+    "vitest": "^2.1.0",
+    "wrangler": "^4.83.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0"
@@ -50,5 +75,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }