@nymbalhq/sdk 1.4.0 → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nymbal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,6 @@
+# @nymbalhq/sdk
+
+The client side of a Nymbal store, independent of any framework: stores for the catalogue, cart, account and
+checkout over the store's API.
+
+See the [documentation](https://github.com/nymbalhq/nymbal/blob/main/apps/docs/src/content/docs/index.md).

package/dist/chunk-2EEZZXZX.js

@@ -0,0 +1,601 @@
+// src/adapter/fetch-client.ts
+var NymbalApiError = class extends Error {
+  constructor(code, message, status, context) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.context = context;
+    this.name = "NymbalApiError";
+  }
+  code;
+  status;
+  context;
+};
+var REFRESH_WAIT_MS = 1e4;
+var CSRF_HEADER = "x-csrf-token";
+var UNSAFE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var FetchClient = class {
+  baseUrl;
+  credentials;
+  getAccessToken;
+  getCartToken;
+  onUnauthorized;
+  /** The refresh a refused request started, which every request refused meanwhile waits on rather than its own. */
+  refreshing = null;
+  /** The token `GET /api/csrf` answered: the API's `nymbal.csrf` cookie, which this origin may not be able to read. */
+  csrfToken = null;
+  /** A session restore's refresh, which every request sent meanwhile waits on so that none goes out as a guest. */
+  held = null;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.credentials = options.credentials ?? "include";
+    this.getAccessToken = options.getAccessToken ?? (() => null);
+    this.getCartToken = options.getCartToken;
+    this.onUnauthorized = options.onUnauthorized;
+  }
+  /** Starts the session's refresh, or joins the one in flight: a client sends one refresh at a time. */
+  refreshSession() {
+    if (this.onUnauthorized === void 0) return Promise.resolve();
+    return this.refreshing ?? this.refresh(this.onUnauthorized);
+  }
+  /**
+   * As `refreshSession`, and every other request sent until the refresh settles waits for it, at most
+   * `REFRESH_WAIT_MS`. Held from this call on, before any await: a page's first requests go in the same tick.
+   */
+  restoreSession() {
+    const held = this.waitFor(this.refreshSession()).then(
+      () => void 0,
+      () => void 0
+    );
+    this.held = held;
+    void held.then(() => {
+      if (this.held === held) this.held = null;
+    });
+    return held;
+  }
+  async request(method, path, body, options = {}) {
+    return (await this.requestWithMeta(method, path, body, options)).data;
+  }
+  /** Like `request`, keeping the envelope's `meta` (pagination cursors live there). */
+  async requestWithMeta(method, path, body, options = {}) {
+    if (this.held !== null && options.authRefresh !== true) await this.held;
+    const sentDuring = this.refreshing;
+    let { response, bearer } = await this.doFetch(method, path, body, options);
+    if (await this.isCsrfRejection(response)) {
+      this.csrfToken = null;
+      ({ response, bearer } = await this.doFetch(method, path, body, options));
+    }
+    if (response.status === 401 && this.onUnauthorized && options.authRefresh !== true) {
+      const pending = this.refreshing;
+      const retry = async () => {
+        if (options.keepIdentity === true && bearer !== null && this.getAccessToken() === null) {
+          return this.parseResponse(response);
+        }
+        return this.parseResponse((await this.doFetch(method, path, body, options)).response);
+      };
+      if (pending === null && this.getAccessToken() !== bearer) {
+        return retry();
+      }
+      if (pending !== null && pending === sentDuring) {
+        if (await this.waitFor(pending) && this.getAccessToken() !== bearer) return retry();
+      } else if (await this.waitFor(pending ?? this.refresh(this.onUnauthorized))) {
+        return retry();
+      }
+    }
+    return this.parseResponse(response);
+  }
+  /** Whether the refresh ended within `REFRESH_WAIT_MS`; a refresh that fails throws here, as it always has. */
+  async waitFor(refresh) {
+    let timer;
+    const bound = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(false), REFRESH_WAIT_MS);
+    });
+    try {
+      return await Promise.race([refresh.then(() => true), bound]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  refresh(onUnauthorized) {
+    const refresh = Promise.resolve().then(onUnauthorized).finally(() => {
+      this.refreshing = null;
+    });
+    this.refreshing = refresh;
+    return refresh;
+  }
+  csrf() {
+    this.csrfToken ??= this.fetchCsrfToken().catch((err) => {
+      this.csrfToken = null;
+      throw err;
+    });
+    return this.csrfToken;
+  }
+  async fetchCsrfToken() {
+    const response = await globalThis.fetch(`${this.baseUrl}/api/csrf`, {
+      method: "GET",
+      credentials: this.credentials
+    });
+    const { data } = await this.parseResponse(response);
+    return data.token;
+  }
+  async isCsrfRejection(response) {
+    if (response.status !== 403) return false;
+    const text = await response.clone().text();
+    try {
+      return JSON.parse(text).error?.code === "csrf.invalid";
+    } catch {
+      return false;
+    }
+  }
+  async doFetch(method, path, body, options) {
+    const headers = { ...options.headers };
+    const cookies = [];
+    if (UNSAFE_METHODS.has(method.toUpperCase())) {
+      const csrf = await this.csrf();
+      headers[CSRF_HEADER] = csrf;
+      cookies.push(`nymbal.csrf=${csrf}`);
+    }
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const token = this.getAccessToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+    const cartToken = this.getCartToken?.();
+    if (cartToken) {
+      cookies.unshift(`nymbal.cart=${cartToken}`);
+    }
+    if (cookies.length > 0) {
+      headers["Cookie"] = cookies.join("; ");
+    }
+    const response = await globalThis.fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      credentials: this.credentials,
+      ...body !== void 0 && { body: JSON.stringify(body) }
+    });
+    return { response, bearer: token };
+  }
+  async parseResponse(response) {
+    const text = await response.text();
+    if (!text) {
+      return { data: void 0, meta: {} };
+    }
+    const envelope = JSON.parse(text);
+    if (envelope.error) {
+      throw new NymbalApiError(
+        envelope.error.code,
+        envelope.error.message,
+        response.status,
+        envelope.error.context
+      );
+    }
+    return { data: envelope.data, meta: envelope.meta ?? {} };
+  }
+};
+
+// src/adapter/nymbal-api-adapter.ts
+import {
+  ORDER_EMAIL_HEADER,
+  ORDER_KEY_HEADER
+} from "@nymbalhq/types";
+function createNymbalApiAdapter(fetchClient) {
+  const getOrder = (orderNumber, { key, email } = {}) => fetchClient.request(
+    "GET",
+    `/api/orders/${encodeURIComponent(orderNumber)}`,
+    void 0,
+    {
+      headers: {
+        ...key !== void 0 && { [ORDER_KEY_HEADER]: key },
+        ...email !== void 0 && { [ORDER_EMAIL_HEADER]: email }
+      }
+    }
+  );
+  return {
+    capabilities: {
+      get() {
+        return fetchClient.request("GET", "/api/capabilities");
+      }
+    },
+    cart: {
+      get() {
+        return fetchClient.request("GET", "/api/cart");
+      },
+      addItem(variantId, qty) {
+        return fetchClient.request("POST", "/api/cart/items", { variantId, qty });
+      },
+      removeItem(variantId) {
+        return fetchClient.request(
+          "DELETE",
+          `/api/cart/items/${encodeURIComponent(variantId)}`
+        );
+      },
+      updateQuantity(variantId, qty) {
+        return fetchClient.request(
+          "PATCH",
+          `/api/cart/items/${encodeURIComponent(variantId)}`,
+          { qty }
+        );
+      },
+      clear() {
+        return fetchClient.request("DELETE", "/api/cart");
+      }
+    },
+    products: {
+      getBySlug(slug) {
+        return fetchClient.request(
+          "GET",
+          `/api/products/${encodeURIComponent(slug)}`
+        );
+      },
+      list(params) {
+        const search = new URLSearchParams();
+        if (params?.limit !== void 0) search.set("limit", String(params.limit));
+        if (params?.cursor !== void 0) search.set("cursor", params.cursor);
+        if (params?.category !== void 0) search.set("category", params.category);
+        if (params?.sort !== void 0) search.set("sort", params.sort);
+        const qs = search.toString();
+        return fetchClient.request("GET", `/api/products${qs ? `?${qs}` : ""}`);
+      },
+      search(query, params) {
+        const search = new URLSearchParams();
+        search.set("q", query);
+        if (params?.limit !== void 0) search.set("limit", String(params.limit));
+        if (params?.cursor !== void 0) search.set("cursor", params.cursor);
+        if (params?.category !== void 0) search.set("category", params.category);
+        return fetchClient.request(
+          "GET",
+          `/api/products/search?${search.toString()}`
+        );
+      }
+    },
+    checkout: {
+      create(details) {
+        return fetchClient.request("POST", "/api/checkout", details, {
+          keepIdentity: true
+        });
+      }
+    },
+    customers: {
+      register(params) {
+        return fetchClient.request("POST", "/api/auth/register", params);
+      },
+      login(email, password) {
+        return fetchClient.request("POST", "/api/auth/login", { email, password });
+      },
+      async logout() {
+        await fetchClient.request("POST", "/api/auth/logout");
+      },
+      refresh() {
+        return fetchClient.request(
+          "POST",
+          "/api/auth/refresh",
+          void 0,
+          { authRefresh: true }
+        );
+      },
+      getProfile() {
+        return fetchClient.request("GET", "/api/customers/me");
+      },
+      updateProfile(updates) {
+        return fetchClient.request("PATCH", "/api/customers/me", updates);
+      },
+      listAddresses() {
+        return fetchClient.request("GET", "/api/customers/me/addresses");
+      },
+      addAddress(address) {
+        return fetchClient.request("POST", "/api/customers/me/addresses", address);
+      },
+      async removeAddress(id) {
+        await fetchClient.request(
+          "DELETE",
+          `/api/customers/me/addresses/${encodeURIComponent(id)}`
+        );
+      },
+      async listOrders(params) {
+        const qs = params?.cursor !== void 0 ? `?cursor=${encodeURIComponent(params.cursor)}` : "";
+        const { data, meta } = await fetchClient.requestWithMeta("GET", `/api/orders${qs}`);
+        const nextCursor = typeof meta.nextCursor === "string" ? meta.nextCursor : null;
+        return { items: data ?? [], nextCursor };
+      },
+      getOrder
+    },
+    orders: {
+      get: getOrder,
+      async requestLink({ orderNumber, email }) {
+        await fetchClient.request("POST", "/api/orders/link", {
+          orderNumber,
+          email
+        });
+      }
+    },
+    recentlyViewed: {
+      async record(productId) {
+        await fetchClient.request("POST", "/api/recently-viewed", { productId });
+      },
+      list() {
+        return fetchClient.request("GET", "/api/recently-viewed");
+      }
+    },
+    reviews: {
+      getForProduct(productId, params) {
+        const search = new URLSearchParams();
+        if (params?.limit !== void 0) search.set("limit", String(params.limit));
+        if (params?.cursor !== void 0) search.set("cursor", params.cursor);
+        const qs = search.toString();
+        return fetchClient.request(
+          "GET",
+          `/api/products/${encodeURIComponent(productId)}/reviews${qs ? `?${qs}` : ""}`
+        );
+      },
+      submit(review) {
+        return fetchClient.request("POST", "/api/reviews", review);
+      }
+    },
+    alerts: {
+      subscribe(request) {
+        return fetchClient.request("POST", "/api/alerts/subscribe", request);
+      }
+    }
+  };
+}
+
+// src/auth/session.ts
+var SESSION_HINT_KEY = "nymbal.auth.session";
+var ACCESS_TOKEN_KEY = "nymbal.auth.accessToken";
+function withStorage(use, fallback) {
+  try {
+    return typeof globalThis.localStorage === "undefined" ? fallback : use(globalThis.localStorage);
+  } catch {
+    return fallback;
+  }
+}
+function hasSessionHint() {
+  return withStorage((storage) => storage.getItem(SESSION_HINT_KEY) === "1", false);
+}
+function markSession() {
+  withStorage((storage) => storage.setItem(SESSION_HINT_KEY, "1"), void 0);
+}
+function forgetSession() {
+  withStorage((storage) => storage.removeItem(SESSION_HINT_KEY), void 0);
+}
+function adoptLegacyToken() {
+  withStorage((storage) => {
+    if (storage.getItem(ACCESS_TOKEN_KEY) === null) return;
+    storage.removeItem(ACCESS_TOKEN_KEY);
+    storage.setItem(SESSION_HINT_KEY, "1");
+  }, void 0);
+}
+function isSessionRefusal(err) {
+  return err instanceof NymbalApiError && (err.status === 401 || err.status === 403);
+}
+async function renewSession(adapter, tokenManager) {
+  try {
+    const result = await adapter.customers.refresh();
+    tokenManager.setTokens(result.accessToken, result.expiresIn);
+  } catch (err) {
+    console.warn("[NymbalClient] token refresh failed", err);
+    tokenManager.clear();
+    if (isSessionRefusal(err)) forgetSession();
+  }
+}
+
+// src/auth/token-manager.ts
+function createTokenManager(options) {
+  const storageMode = options?.storage ?? "memory";
+  const storageKey = options?.storageKey ?? ACCESS_TOKEN_KEY;
+  let memoryToken = null;
+  let refreshTimer = null;
+  let refreshFn = null;
+  function getAccessToken() {
+    if (storageMode === "localStorage" && typeof globalThis.localStorage !== "undefined") {
+      return globalThis.localStorage.getItem(storageKey);
+    }
+    return memoryToken;
+  }
+  function setAccessToken(token) {
+    memoryToken = token;
+    if (storageMode === "localStorage" && typeof globalThis.localStorage !== "undefined") {
+      if (token) {
+        globalThis.localStorage.setItem(storageKey, token);
+      } else {
+        globalThis.localStorage.removeItem(storageKey);
+      }
+    }
+  }
+  function setTokens(accessToken, expiresIn) {
+    setAccessToken(accessToken);
+    markSession();
+    scheduleAutoRefresh(expiresIn);
+  }
+  function clear() {
+    setAccessToken(null);
+    if (refreshTimer !== null) {
+      clearTimeout(refreshTimer);
+      refreshTimer = null;
+    }
+  }
+  function scheduleAutoRefresh(expiresIn) {
+    if (refreshTimer !== null) {
+      clearTimeout(refreshTimer);
+    }
+    const delayMs = Math.max(1e3, expiresIn * 0.8 * 1e3);
+    refreshTimer = setTimeout(async () => {
+      if (!refreshFn) return;
+      try {
+        const result = await refreshFn();
+        if (result) setTokens(result.accessToken, result.expiresIn);
+      } catch (err) {
+        console.error("[TokenManager] auto-refresh failed, clearing session", err);
+        clear();
+      }
+    }, delayMs);
+  }
+  function scheduleRefresh(fn) {
+    refreshFn = fn;
+  }
+  function destroy() {
+    clear();
+    refreshFn = null;
+  }
+  return { getAccessToken, setTokens, clear, scheduleRefresh, destroy };
+}
+
+// src/client.ts
+var STORE_NAMESPACES = [
+  "cart",
+  "product",
+  "productList",
+  "search",
+  "checkout",
+  "auth"
+];
+var FACTORIES_KEY = /* @__PURE__ */ Symbol.for("nymbal.sdk.namespaces");
+function factories() {
+  const holder = globalThis;
+  holder[FACTORIES_KEY] ??= {};
+  return holder[FACTORIES_KEY];
+}
+function defineNamespace(name, factory) {
+  factories()[name] = factory;
+}
+var STORE_BUILT = /* @__PURE__ */ Symbol.for("nymbal.client.onStoreBuilt");
+function isStore(value) {
+  return typeof value === "object" && value !== null && typeof value.subscribe === "function" && typeof value.getState === "function";
+}
+var RESUME_SESSION = /* @__PURE__ */ Symbol.for("nymbal.client.resumeSession");
+function resumeSession(client) {
+  const hook = client[RESUME_SESSION];
+  return typeof hook === "function" ? hook() : Promise.resolve();
+}
+function onStoreBuilt(client, listener) {
+  const hook = client[STORE_BUILT];
+  if (typeof hook === "function") return hook(listener);
+  for (const value of Object.values(client)) {
+    if (isStore(value)) listener(value);
+  }
+  return () => {
+  };
+}
+function createNymbalClient(options) {
+  if (options.tokenStorage !== "localStorage") adoptLegacyToken();
+  const tokenManager = createTokenManager({
+    ...options.tokenStorage !== void 0 && { storage: options.tokenStorage }
+  });
+  let adapter;
+  let fetchClient;
+  const renew = () => renewSession(adapter, tokenManager);
+  if (options.adapter) {
+    adapter = options.adapter;
+  } else {
+    fetchClient = new FetchClient({
+      baseUrl: options.baseUrl,
+      ...options.credentials !== void 0 && { credentials: options.credentials },
+      getAccessToken: () => tokenManager.getAccessToken(),
+      ...options.getCartToken !== void 0 && { getCartToken: options.getCartToken },
+      onUnauthorized: renew
+    });
+    adapter = createNymbalApiAdapter(fetchClient);
+  }
+  const customer = {
+    addresses: {
+      list: () => adapter.customers.listAddresses(),
+      create: (address) => adapter.customers.addAddress(address),
+      remove: (id) => adapter.customers.removeAddress(id)
+    },
+    orders: {
+      list: (opts) => adapter.customers.listOrders(opts),
+      get: (orderNumber, options2) => adapter.customers.getOrder(orderNumber, options2)
+    }
+  };
+  let report = null;
+  const capabilities = {
+    get() {
+      if (report === null) {
+        const reader = adapter.capabilities;
+        report = reader === void 0 ? Promise.reject(new Error("This client\u2019s adapter cannot read the store capabilities.")) : reader.get();
+        report.catch(() => {
+          report = null;
+        });
+      }
+      return report;
+    }
+  };
+  const noGuestOrders = () => Promise.reject(new Error("This client\u2019s adapter cannot open a guest\u2019s order."));
+  const orders = adapter.orders ?? { get: noGuestOrders, requestLink: noGuestOrders };
+  const recentlyViewedOf = () => {
+    const reader = adapter.recentlyViewed;
+    if (reader === void 0) {
+      throw new Error("This client\u2019s adapter cannot record or list recently viewed products.");
+    }
+    return reader;
+  };
+  const recentlyViewed = {
+    async record(productId) {
+      await recentlyViewedOf().record(productId);
+    },
+    async list() {
+      return recentlyViewedOf().list();
+    }
+  };
+  tokenManager.scheduleRefresh(() => fetchClient?.refreshSession() ?? renew());
+  const built = {};
+  const listeners = /* @__PURE__ */ new Set();
+  let destroyed = false;
+  function destroy() {
+    destroyed = true;
+    for (const store of Object.values(built)) store.destroy();
+    tokenManager.destroy();
+  }
+  const storeBuilt = (listener) => {
+    for (const store of Object.values(built)) listener(store);
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const resume = () => tokenManager.getAccessToken() || !hasSessionHint() ? Promise.resolve() : context.restoreSession();
+  const client = Object.defineProperties(
+    { capabilities, recentlyViewed, customer, orders, adapter, destroy },
+    { [STORE_BUILT]: { value: storeBuilt }, [RESUME_SESSION]: { value: resume } }
+  );
+  const context = {
+    adapter,
+    tokenManager,
+    client,
+    restoreSession: () => fetchClient?.restoreSession() ?? renew()
+  };
+  function build(name) {
+    if (destroyed) throw new Error(`client.${name} was read after the client was destroyed`);
+    const factory = factories()[name];
+    if (factory === void 0) {
+      const module = name === "productList" ? "product-list" : name;
+      throw new Error(`client.${name} is not in this client: import '@nymbalhq/sdk/ns/${module}'`);
+    }
+    const store = built[name] = factory(context);
+    for (const listener of listeners) listener(store);
+    return store;
+  }
+  for (const name of STORE_NAMESPACES) {
+    Object.defineProperty(client, name, { get: () => built[name] ?? build(name) });
+  }
+  return client;
+}
+
+export {
+  NymbalApiError,
+  FetchClient,
+  createNymbalApiAdapter,
+  SESSION_HINT_KEY,
+  hasSessionHint,
+  forgetSession,
+  isSessionRefusal,
+  renewSession,
+  createTokenManager,
+  defineNamespace,
+  resumeSession,
+  onStoreBuilt,
+  createNymbalClient
+};
+//# sourceMappingURL=chunk-2EEZZXZX.js.map