@dotlabshq/orbseal-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,267 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigClient: () => ConfigClient,
+  ResolvedConfig: () => ResolvedConfig
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/decrypt.ts
+var B58_ALPHA = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function b58dec(s) {
+  let n = 0n;
+  for (const ch of s) {
+    const i = B58_ALPHA.indexOf(ch);
+    if (i < 0) throw new Error(`Invalid base58 character: ${ch}`);
+    n = n * 58n + BigInt(i);
+  }
+  const hex = n.toString(16);
+  const buf = Buffer.from(hex.length % 2 ? "0" + hex : hex, "hex");
+  return new Uint8Array(buf);
+}
+function parsePrivateKey(raw) {
+  if (raw.startsWith("orbsk-") || raw.startsWith("orb-sk-")) {
+    const dash = raw.indexOf("-", raw.indexOf("-") + 1);
+    return b58dec(raw.slice(dash + 1));
+  }
+  const buf = Buffer.from(raw, "base64");
+  return new Uint8Array(buf);
+}
+async function derivePublicKey(sk) {
+  const sodium = await getSodium();
+  return sodium.crypto_scalarmult_base(sk);
+}
+async function decryptSealed(ciphertext, privateKeyRaw) {
+  const sodium = await getSodium();
+  const sk = parsePrivateKey(privateKeyRaw);
+  const pk = await derivePublicKey(sk);
+  const ct = sodium.from_base64(ciphertext, sodium.base64_variants.ORIGINAL);
+  const plain = sodium.crypto_box_seal_open(ct, pk, sk);
+  return sodium.to_string(plain);
+}
+var _sodium = null;
+async function getSodium() {
+  if (_sodium) return _sodium;
+  try {
+    const mod = await import("libsodium-wrappers");
+    const sodium = mod.default ?? mod;
+    await sodium.ready;
+    _sodium = sodium;
+    return _sodium;
+  } catch {
+    throw new Error(
+      "[orbseal-sdk] libsodium-wrappers is required to decrypt secrets.\nInstall it: npm install libsodium-wrappers"
+    );
+  }
+}
+
+// src/config.ts
+var ResolvedConfig = class {
+  /** ETag of this snapshot — use for conditional re-resolve. */
+  etag;
+  /** ISO timestamp of when this snapshot was resolved. */
+  resolvedAt;
+  #config;
+  #secrets;
+  // still ciphertext
+  #privateKey;
+  #decrypted = /* @__PURE__ */ new Map();
+  constructor(raw, privateKey) {
+    this.#config = raw.config;
+    this.#secrets = raw.secrets;
+    this.#privateKey = privateKey;
+    this.etag = raw.etag;
+    this.resolvedAt = raw.resolved_at;
+  }
+  /**
+   * Get a typed config value.
+   *
+   * @example
+   * const url     = config.get<string>('api_url');
+   * const retries = config.get<number>('max_retries');
+   * const queue   = config.get<'default'|'priority'|'batch'>('queue_name');
+   */
+  get(key) {
+    if (!(key in this.#config)) {
+      throw new Error(`[orbseal] config key not found: "${key}"`);
+    }
+    return this.#config[key];
+  }
+  /**
+   * Get a config value or `undefined` if not set.
+   */
+  getOrNull(key) {
+    return this.#config[key];
+  }
+  /**
+   * Decrypt and return a secret value.
+   * Result is cached — repeated calls are free.
+   *
+   * Requires `privateKey` to be set in `OrbOptions`.
+   *
+   * @example
+   * const webhookSecret = await config.getSecret('webhook_secret');
+   */
+  async getSecret(key) {
+    if (this.#decrypted.has(key)) {
+      return this.#decrypted.get(key);
+    }
+    if (!(key in this.#secrets)) {
+      throw new Error(`[orbseal] secret not found: "${key}"`);
+    }
+    if (!this.#privateKey) {
+      throw new Error(
+        `[orbseal] privateKey is required to decrypt secrets.
+Set it in ConfigClient options: new ConfigClient({ ..., privateKey: process.env.ORBSEAL_PRIVATE_KEY })`
+      );
+    }
+    const plain = await decryptSealed(this.#secrets[key], this.#privateKey);
+    this.#decrypted.set(key, plain);
+    return plain;
+  }
+  /**
+   * Returns true if the key exists as a plain config value.
+   */
+  has(key) {
+    return key in this.#config;
+  }
+  /**
+   * Returns true if the key exists as a secret.
+   */
+  hasSecret(key) {
+    return key in this.#secrets;
+  }
+  /**
+   * All plain config keys available in this snapshot.
+   */
+  keys() {
+    return Object.keys(this.#config);
+  }
+  /**
+   * All secret keys available in this snapshot (ciphertext, not decrypted).
+   */
+  secretKeys() {
+    return Object.keys(this.#secrets);
+  }
+};
+
+// src/client.ts
+var DEFAULT_API_BASE = "https://api.orbseal.com";
+var ConfigClient = class {
+  #apiKey;
+  #project;
+  #environment;
+  #privateKey;
+  #apiBase;
+  // ─── ETag cache ─────────────────────────────────────────────────────────────
+  #cached = null;
+  #cachedFor = null;
+  // "<userId|''>:<etag>"
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("[orbseal] apiKey is required");
+    if (!opts.project) throw new Error("[orbseal] project is required");
+    if (!opts.environment) throw new Error("[orbseal] environment is required");
+    this.#apiKey = opts.apiKey;
+    this.#project = opts.project;
+    this.#environment = opts.environment;
+    this.#privateKey = opts.privateKey;
+    this.#apiBase = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  }
+  /**
+   * Resolve the current config snapshot from the edge.
+   *
+   * - Pass `userId` to include user-scoped overrides.
+   * - Pass `etag` from a previous resolve to get a cached response when nothing changed.
+   *   Returns the same `ResolvedConfig` instance when the server confirms the etag is current.
+   *
+   * @example
+   * // Simple — always fetches fresh
+   * const config = await orb.resolve();
+   *
+   * // With user overrides
+   * const config = await orb.resolve({ userId: 'u_abc123' });
+   *
+   * // With etag caching (returns cached instance if unchanged)
+   * const config = await orb.resolve({ etag: prev?.etag });
+   */
+  async resolve(opts = {}) {
+    const { userId, etag } = opts;
+    const cacheKey = `${userId ?? ""}:${etag ?? ""}`;
+    if (etag && this.#cached && this.#cachedFor === cacheKey) {
+      return this.#cached;
+    }
+    const url = this.#buildUrl(userId);
+    const headers = {
+      "Authorization": `Bearer ${this.#apiKey}`,
+      "Content-Type": "application/json"
+    };
+    if (etag) headers["If-None-Match"] = etag;
+    const res = await fetch(url, { headers });
+    if (res.status === 304 && this.#cached) {
+      return this.#cached;
+    }
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        message = body.error ?? body.code ?? message;
+      } catch {
+      }
+      throw new Error(`[orbseal] resolve failed: ${message}`);
+    }
+    const raw = await res.json();
+    const resolved = new ResolvedConfig(raw, this.#privateKey);
+    this.#cached = resolved;
+    this.#cachedFor = `${userId ?? ""}:${resolved.etag}`;
+    return resolved;
+  }
+  /**
+   * Project + environment the client is scoped to.
+   */
+  get scope() {
+    return { project: this.#project, environment: this.#environment };
+  }
+  // ─── Internal ────────────────────────────────────────────────────────────────
+  #buildUrl(userId) {
+    const params = new URLSearchParams({
+      project: this.#project,
+      environment: this.#environment
+    });
+    if (userId) params.set("user", userId);
+    return `${this.#apiBase}/v1/config/resolve?${params}`;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigClient,
+  ResolvedConfig
+});

package/dist/index.d.cts

@@ -0,0 +1,137 @@
+interface OrbOptions {
+    /** App key (orb_live_... or orb_admin_...) */
+    apiKey: string;
+    /** Project slug as defined in orb.yaml */
+    project: string;
+    /** Environment slug (e.g. "production", "staging") */
+    environment: string;
+    /**
+     * Private key for decrypting sealed secrets.
+     * Accepts orbsk-<base58> format (from `orbseal keygen`) or raw base64.
+     * Required only if you call `config.getSecret(...)`.
+     */
+    privateKey?: string;
+    /** Override the API base URL. Default: https://api.orbseal.com */
+    apiBase?: string;
+}
+interface ResolveOptions {
+    /** End-user ID for user-scoped overrides. */
+    userId?: string;
+    /**
+     * ETag from a previous resolve call.
+     * If the server's etag matches, returns the cached config unchanged.
+     */
+    etag?: string | null;
+}
+interface RawResolveResponse {
+    config: Record<string, unknown>;
+    secrets: Record<string, string>;
+    resolved_at: string;
+    etag: string;
+}
+
+/**
+ * Resolved config snapshot returned by `orb.resolve()`.
+ *
+ * Config values are immediately available via `.get()`.
+ * Secrets are decrypted lazily on the first `.getSecret()` call —
+ * decryption happens in your runtime; the plaintext never leaves your app.
+ */
+declare class ResolvedConfig {
+    #private;
+    /** ETag of this snapshot — use for conditional re-resolve. */
+    readonly etag: string;
+    /** ISO timestamp of when this snapshot was resolved. */
+    readonly resolvedAt: string;
+    constructor(raw: RawResolveResponse, privateKey?: string);
+    /**
+     * Get a typed config value.
+     *
+     * @example
+     * const url     = config.get<string>('api_url');
+     * const retries = config.get<number>('max_retries');
+     * const queue   = config.get<'default'|'priority'|'batch'>('queue_name');
+     */
+    get<T = unknown>(key: string): T;
+    /**
+     * Get a config value or `undefined` if not set.
+     */
+    getOrNull<T = unknown>(key: string): T | undefined;
+    /**
+     * Decrypt and return a secret value.
+     * Result is cached — repeated calls are free.
+     *
+     * Requires `privateKey` to be set in `OrbOptions`.
+     *
+     * @example
+     * const webhookSecret = await config.getSecret('webhook_secret');
+     */
+    getSecret(key: string): Promise<string>;
+    /**
+     * Returns true if the key exists as a plain config value.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns true if the key exists as a secret.
+     */
+    hasSecret(key: string): boolean;
+    /**
+     * All plain config keys available in this snapshot.
+     */
+    keys(): string[];
+    /**
+     * All secret keys available in this snapshot (ciphertext, not decrypted).
+     */
+    secretKeys(): string[];
+}
+
+/**
+ * OrbSeal config client.
+ *
+ * @example
+ * ```ts
+ * import { ConfigClient } from '@dotlabshq/orbseal-sdk';
+ *
+ * const orb = new ConfigClient({
+ *   apiKey:      process.env.ORBSEAL_API_KEY!,
+ *   project:     'taskflow',
+ *   environment: 'production',
+ *   privateKey:  process.env.ORBSEAL_PRIVATE_KEY, // needed for secrets
+ * });
+ *
+ * const config = await orb.resolve();
+ * const apiUrl = config.get<string>('api_url');
+ * const secret = await config.getSecret('webhook_secret');
+ * ```
+ */
+declare class ConfigClient {
+    #private;
+    constructor(opts: OrbOptions);
+    /**
+     * Resolve the current config snapshot from the edge.
+     *
+     * - Pass `userId` to include user-scoped overrides.
+     * - Pass `etag` from a previous resolve to get a cached response when nothing changed.
+     *   Returns the same `ResolvedConfig` instance when the server confirms the etag is current.
+     *
+     * @example
+     * // Simple — always fetches fresh
+     * const config = await orb.resolve();
+     *
+     * // With user overrides
+     * const config = await orb.resolve({ userId: 'u_abc123' });
+     *
+     * // With etag caching (returns cached instance if unchanged)
+     * const config = await orb.resolve({ etag: prev?.etag });
+     */
+    resolve(opts?: ResolveOptions): Promise<ResolvedConfig>;
+    /**
+     * Project + environment the client is scoped to.
+     */
+    get scope(): {
+        project: string;
+        environment: string;
+    };
+}
+
+export { ConfigClient, type OrbOptions, type RawResolveResponse, type ResolveOptions, ResolvedConfig };

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+interface OrbOptions {
+    /** App key (orb_live_... or orb_admin_...) */
+    apiKey: string;
+    /** Project slug as defined in orb.yaml */
+    project: string;
+    /** Environment slug (e.g. "production", "staging") */
+    environment: string;
+    /**
+     * Private key for decrypting sealed secrets.
+     * Accepts orbsk-<base58> format (from `orbseal keygen`) or raw base64.
+     * Required only if you call `config.getSecret(...)`.
+     */
+    privateKey?: string;
+    /** Override the API base URL. Default: https://api.orbseal.com */
+    apiBase?: string;
+}
+interface ResolveOptions {
+    /** End-user ID for user-scoped overrides. */
+    userId?: string;
+    /**
+     * ETag from a previous resolve call.
+     * If the server's etag matches, returns the cached config unchanged.
+     */
+    etag?: string | null;
+}
+interface RawResolveResponse {
+    config: Record<string, unknown>;
+    secrets: Record<string, string>;
+    resolved_at: string;
+    etag: string;
+}
+
+/**
+ * Resolved config snapshot returned by `orb.resolve()`.
+ *
+ * Config values are immediately available via `.get()`.
+ * Secrets are decrypted lazily on the first `.getSecret()` call —
+ * decryption happens in your runtime; the plaintext never leaves your app.
+ */
+declare class ResolvedConfig {
+    #private;
+    /** ETag of this snapshot — use for conditional re-resolve. */
+    readonly etag: string;
+    /** ISO timestamp of when this snapshot was resolved. */
+    readonly resolvedAt: string;
+    constructor(raw: RawResolveResponse, privateKey?: string);
+    /**
+     * Get a typed config value.
+     *
+     * @example
+     * const url     = config.get<string>('api_url');
+     * const retries = config.get<number>('max_retries');
+     * const queue   = config.get<'default'|'priority'|'batch'>('queue_name');
+     */
+    get<T = unknown>(key: string): T;
+    /**
+     * Get a config value or `undefined` if not set.
+     */
+    getOrNull<T = unknown>(key: string): T | undefined;
+    /**
+     * Decrypt and return a secret value.
+     * Result is cached — repeated calls are free.
+     *
+     * Requires `privateKey` to be set in `OrbOptions`.
+     *
+     * @example
+     * const webhookSecret = await config.getSecret('webhook_secret');
+     */
+    getSecret(key: string): Promise<string>;
+    /**
+     * Returns true if the key exists as a plain config value.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns true if the key exists as a secret.
+     */
+    hasSecret(key: string): boolean;
+    /**
+     * All plain config keys available in this snapshot.
+     */
+    keys(): string[];
+    /**
+     * All secret keys available in this snapshot (ciphertext, not decrypted).
+     */
+    secretKeys(): string[];
+}
+
+/**
+ * OrbSeal config client.
+ *
+ * @example
+ * ```ts
+ * import { ConfigClient } from '@dotlabshq/orbseal-sdk';
+ *
+ * const orb = new ConfigClient({
+ *   apiKey:      process.env.ORBSEAL_API_KEY!,
+ *   project:     'taskflow',
+ *   environment: 'production',
+ *   privateKey:  process.env.ORBSEAL_PRIVATE_KEY, // needed for secrets
+ * });
+ *
+ * const config = await orb.resolve();
+ * const apiUrl = config.get<string>('api_url');
+ * const secret = await config.getSecret('webhook_secret');
+ * ```
+ */
+declare class ConfigClient {
+    #private;
+    constructor(opts: OrbOptions);
+    /**
+     * Resolve the current config snapshot from the edge.
+     *
+     * - Pass `userId` to include user-scoped overrides.
+     * - Pass `etag` from a previous resolve to get a cached response when nothing changed.
+     *   Returns the same `ResolvedConfig` instance when the server confirms the etag is current.
+     *
+     * @example
+     * // Simple — always fetches fresh
+     * const config = await orb.resolve();
+     *
+     * // With user overrides
+     * const config = await orb.resolve({ userId: 'u_abc123' });
+     *
+     * // With etag caching (returns cached instance if unchanged)
+     * const config = await orb.resolve({ etag: prev?.etag });
+     */
+    resolve(opts?: ResolveOptions): Promise<ResolvedConfig>;
+    /**
+     * Project + environment the client is scoped to.
+     */
+    get scope(): {
+        project: string;
+        environment: string;
+    };
+}
+
+export { ConfigClient, type OrbOptions, type RawResolveResponse, type ResolveOptions, ResolvedConfig };

package/dist/index.js

@@ -0,0 +1,229 @@
+// src/decrypt.ts
+var B58_ALPHA = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function b58dec(s) {
+  let n = 0n;
+  for (const ch of s) {
+    const i = B58_ALPHA.indexOf(ch);
+    if (i < 0) throw new Error(`Invalid base58 character: ${ch}`);
+    n = n * 58n + BigInt(i);
+  }
+  const hex = n.toString(16);
+  const buf = Buffer.from(hex.length % 2 ? "0" + hex : hex, "hex");
+  return new Uint8Array(buf);
+}
+function parsePrivateKey(raw) {
+  if (raw.startsWith("orbsk-") || raw.startsWith("orb-sk-")) {
+    const dash = raw.indexOf("-", raw.indexOf("-") + 1);
+    return b58dec(raw.slice(dash + 1));
+  }
+  const buf = Buffer.from(raw, "base64");
+  return new Uint8Array(buf);
+}
+async function derivePublicKey(sk) {
+  const sodium = await getSodium();
+  return sodium.crypto_scalarmult_base(sk);
+}
+async function decryptSealed(ciphertext, privateKeyRaw) {
+  const sodium = await getSodium();
+  const sk = parsePrivateKey(privateKeyRaw);
+  const pk = await derivePublicKey(sk);
+  const ct = sodium.from_base64(ciphertext, sodium.base64_variants.ORIGINAL);
+  const plain = sodium.crypto_box_seal_open(ct, pk, sk);
+  return sodium.to_string(plain);
+}
+var _sodium = null;
+async function getSodium() {
+  if (_sodium) return _sodium;
+  try {
+    const mod = await import("libsodium-wrappers");
+    const sodium = mod.default ?? mod;
+    await sodium.ready;
+    _sodium = sodium;
+    return _sodium;
+  } catch {
+    throw new Error(
+      "[orbseal-sdk] libsodium-wrappers is required to decrypt secrets.\nInstall it: npm install libsodium-wrappers"
+    );
+  }
+}
+
+// src/config.ts
+var ResolvedConfig = class {
+  /** ETag of this snapshot — use for conditional re-resolve. */
+  etag;
+  /** ISO timestamp of when this snapshot was resolved. */
+  resolvedAt;
+  #config;
+  #secrets;
+  // still ciphertext
+  #privateKey;
+  #decrypted = /* @__PURE__ */ new Map();
+  constructor(raw, privateKey) {
+    this.#config = raw.config;
+    this.#secrets = raw.secrets;
+    this.#privateKey = privateKey;
+    this.etag = raw.etag;
+    this.resolvedAt = raw.resolved_at;
+  }
+  /**
+   * Get a typed config value.
+   *
+   * @example
+   * const url     = config.get<string>('api_url');
+   * const retries = config.get<number>('max_retries');
+   * const queue   = config.get<'default'|'priority'|'batch'>('queue_name');
+   */
+  get(key) {
+    if (!(key in this.#config)) {
+      throw new Error(`[orbseal] config key not found: "${key}"`);
+    }
+    return this.#config[key];
+  }
+  /**
+   * Get a config value or `undefined` if not set.
+   */
+  getOrNull(key) {
+    return this.#config[key];
+  }
+  /**
+   * Decrypt and return a secret value.
+   * Result is cached — repeated calls are free.
+   *
+   * Requires `privateKey` to be set in `OrbOptions`.
+   *
+   * @example
+   * const webhookSecret = await config.getSecret('webhook_secret');
+   */
+  async getSecret(key) {
+    if (this.#decrypted.has(key)) {
+      return this.#decrypted.get(key);
+    }
+    if (!(key in this.#secrets)) {
+      throw new Error(`[orbseal] secret not found: "${key}"`);
+    }
+    if (!this.#privateKey) {
+      throw new Error(
+        `[orbseal] privateKey is required to decrypt secrets.
+Set it in ConfigClient options: new ConfigClient({ ..., privateKey: process.env.ORBSEAL_PRIVATE_KEY })`
+      );
+    }
+    const plain = await decryptSealed(this.#secrets[key], this.#privateKey);
+    this.#decrypted.set(key, plain);
+    return plain;
+  }
+  /**
+   * Returns true if the key exists as a plain config value.
+   */
+  has(key) {
+    return key in this.#config;
+  }
+  /**
+   * Returns true if the key exists as a secret.
+   */
+  hasSecret(key) {
+    return key in this.#secrets;
+  }
+  /**
+   * All plain config keys available in this snapshot.
+   */
+  keys() {
+    return Object.keys(this.#config);
+  }
+  /**
+   * All secret keys available in this snapshot (ciphertext, not decrypted).
+   */
+  secretKeys() {
+    return Object.keys(this.#secrets);
+  }
+};
+
+// src/client.ts
+var DEFAULT_API_BASE = "https://api.orbseal.com";
+var ConfigClient = class {
+  #apiKey;
+  #project;
+  #environment;
+  #privateKey;
+  #apiBase;
+  // ─── ETag cache ─────────────────────────────────────────────────────────────
+  #cached = null;
+  #cachedFor = null;
+  // "<userId|''>:<etag>"
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("[orbseal] apiKey is required");
+    if (!opts.project) throw new Error("[orbseal] project is required");
+    if (!opts.environment) throw new Error("[orbseal] environment is required");
+    this.#apiKey = opts.apiKey;
+    this.#project = opts.project;
+    this.#environment = opts.environment;
+    this.#privateKey = opts.privateKey;
+    this.#apiBase = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  }
+  /**
+   * Resolve the current config snapshot from the edge.
+   *
+   * - Pass `userId` to include user-scoped overrides.
+   * - Pass `etag` from a previous resolve to get a cached response when nothing changed.
+   *   Returns the same `ResolvedConfig` instance when the server confirms the etag is current.
+   *
+   * @example
+   * // Simple — always fetches fresh
+   * const config = await orb.resolve();
+   *
+   * // With user overrides
+   * const config = await orb.resolve({ userId: 'u_abc123' });
+   *
+   * // With etag caching (returns cached instance if unchanged)
+   * const config = await orb.resolve({ etag: prev?.etag });
+   */
+  async resolve(opts = {}) {
+    const { userId, etag } = opts;
+    const cacheKey = `${userId ?? ""}:${etag ?? ""}`;
+    if (etag && this.#cached && this.#cachedFor === cacheKey) {
+      return this.#cached;
+    }
+    const url = this.#buildUrl(userId);
+    const headers = {
+      "Authorization": `Bearer ${this.#apiKey}`,
+      "Content-Type": "application/json"
+    };
+    if (etag) headers["If-None-Match"] = etag;
+    const res = await fetch(url, { headers });
+    if (res.status === 304 && this.#cached) {
+      return this.#cached;
+    }
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        message = body.error ?? body.code ?? message;
+      } catch {
+      }
+      throw new Error(`[orbseal] resolve failed: ${message}`);
+    }
+    const raw = await res.json();
+    const resolved = new ResolvedConfig(raw, this.#privateKey);
+    this.#cached = resolved;
+    this.#cachedFor = `${userId ?? ""}:${resolved.etag}`;
+    return resolved;
+  }
+  /**
+   * Project + environment the client is scoped to.
+   */
+  get scope() {
+    return { project: this.#project, environment: this.#environment };
+  }
+  // ─── Internal ────────────────────────────────────────────────────────────────
+  #buildUrl(userId) {
+    const params = new URLSearchParams({
+      project: this.#project,
+      environment: this.#environment
+    });
+    if (userId) params.set("user", userId);
+    return `${this.#apiBase}/v1/config/resolve?${params}`;
+  }
+};
+export {
+  ConfigClient,
+  ResolvedConfig
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dotlabshq/orbseal-sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for OrbSeal — typed config and E2E-encrypted secrets",
+  "keywords": ["orbseal", "config", "secrets", "encryption", "edge"],
+  "homepage": "https://orbseal.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dotlabshq/orbseal-sdk"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types":   "./dist/index.d.ts",
+      "import":  "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main":  "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build":     "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev":       "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "libsodium-wrappers": ">=0.7"
+  },
+  "peerDependenciesMeta": {
+    "libsodium-wrappers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@baseworks/tsconfig": "workspace:*",
+    "@types/libsodium-wrappers": "^0.7.14",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  }
+}