@minipim/sdk 0.2.0 → 0.3.1

package/README.md

@@ -8,7 +8,7 @@ Typed TypeScript client for the [MiniPim](https://github.com/Epic-Design-Labs/mi
 pnpm add @minipim/sdk
 ```
 
-Requires Node 18+ (for native `fetch`) or a fetch polyfill. **ESM-only** (`"type": "module"`) — no CommonJS build; use `import`, not `require`. The root entry imports no `node:` modules, so `createMinipimClient` and the attribute/pagination helpers are safe in Edge runtimes.
+Requires Node 18+ (for native `fetch`) or a fetch polyfill. Ships **both ESM and CommonJS** builds (v0.3.0+) — `import` and `require` both work, including in CJS test tooling. The root entry imports no `node:` modules, so `createMinipimClient` and the attribute/pagination helpers are safe in Edge runtimes.
 
 `baseUrl` is the **origin** (`https://api.minipim.com`); every endpoint path already includes `/v1/...`, so you pass `pim.GET('/v1/products')`, not a pre-joined URL.
 
@@ -128,6 +128,8 @@ const all = await collectAll<Product>(pim, '/v1/products');
 
 `paginate` manages `limit`/`offset`, honors the server's `hasMore`, and defaults to the 200-row max page size (override with `pageSize`). Pass `withTotal: true` in `query` if you need `total` — it adds one `COUNT(*)`, so leave it off on hot reads.
 
+Endpoints that return a **plain array** instead of the envelope (`/v1/categories` without `?limit=`, `/v1/attributes`, `/v1/products/{id}/variants`) are handled too (v0.3.0+): the array is treated as the one-and-only page, so `collectAll` works uniformly across every list endpoint.
+
 ## Attribute helpers
 
 Attribute values are `unknown` and keyed by `(locale, channel)`. List responses return the raw `{ code: [{ locale, channel, value }] }` shape (only product *detail* with `?locale=&channel=` returns a flat `resolvedAttributes`). The SDK ships the flatten + coercion helpers so you don't reimplement them:

package/dist/attributes.cjs

@@ -0,0 +1,80 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/attributes.ts
+var attributes_exports = {};
+__export(attributes_exports, {
+  asMeasurement: () => asMeasurement,
+  asMoney: () => asMoney,
+  flattenAttributes: () => flattenAttributes,
+  formatMoney: () => formatMoney,
+  getAttribute: () => getAttribute
+});
+module.exports = __toCommonJS(attributes_exports);
+function getAttribute(attributes, code, opts = {}) {
+  const records = attributes[code];
+  if (!records || records.length === 0) return void 0;
+  const locale = opts.locale ?? null;
+  const channel = opts.channel ?? null;
+  const layers = [
+    [locale, channel],
+    [locale, null],
+    [null, channel],
+    [null, null]
+  ];
+  for (const [l, c] of layers) {
+    const hit = records.find((r) => r.locale === l && r.channel === c);
+    if (hit) return hit.value;
+  }
+  return void 0;
+}
+function flattenAttributes(attributes, opts = {}) {
+  const out = {};
+  for (const code of Object.keys(attributes)) {
+    const v = getAttribute(attributes, code, opts);
+    if (v !== void 0) out[code] = v;
+  }
+  return out;
+}
+function asMoney(value) {
+  if (value && typeof value === "object" && typeof value.amount_cents === "number" && typeof value.currency === "string") {
+    return value;
+  }
+  return null;
+}
+function asMeasurement(value) {
+  if (value && typeof value === "object" && typeof value.amount === "number" && typeof value.unit === "string") {
+    return value;
+  }
+  return null;
+}
+function formatMoney(money, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency
+  }).format(money.amount_cents / 100);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asMeasurement,
+  asMoney,
+  flattenAttributes,
+  formatMoney,
+  getAttribute
+});

package/dist/attributes.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Attribute helpers. MiniPim stores attribute values keyed by
+ * `(locale, channel)` — list responses always return the raw
+ * `{ code: [{ locale, channel, value }] }` shape (only product *detail*
+ * with `?locale=&channel=` returns a flat `resolvedAttributes`). So every
+ * consumer ends up writing the same flatten + money/measurement coercions.
+ * These are those helpers, typed.
+ */
+interface AttributeValueRecord {
+    locale: string | null;
+    channel: string | null;
+    value: unknown;
+}
+type AttributesPayload = Record<string, AttributeValueRecord[]>;
+interface Money {
+    amount_cents: number;
+    currency: string;
+}
+interface Measurement {
+    amount: number;
+    unit: string;
+}
+interface ResolveOptions {
+    locale?: string | null;
+    channel?: string | null;
+}
+/**
+ * Resolve a single attribute code to its value for a (locale, channel).
+ * Fallback order mirrors the server: exact `(locale, channel)` →
+ * `(locale, null)` → `(null, channel)` → `(null, null)`. Returns
+ * `undefined` when nothing matches.
+ */
+declare function getAttribute(attributes: AttributesPayload, code: string, opts?: ResolveOptions): unknown;
+/**
+ * Flatten an entire attribute payload to a `{ code: value }` map for a
+ * (locale, channel) — the client-side equivalent of the server's
+ * `resolvedAttributes`, for use on list responses where the server doesn't
+ * flatten. Codes with no matching value are omitted.
+ */
+declare function flattenAttributes(attributes: AttributesPayload, opts?: ResolveOptions): Record<string, unknown>;
+/** Narrow an attribute value to Money, or null if it isn't money-shaped. */
+declare function asMoney(value: unknown): Money | null;
+/** Narrow an attribute value to Measurement, or null if it isn't measurement-shaped. */
+declare function asMeasurement(value: unknown): Measurement | null;
+/** Format integer-cents Money as a localized currency string. */
+declare function formatMoney(money: Money, locale?: string): string;
+
+export { type AttributeValueRecord, type AttributesPayload, type Measurement, type Money, type ResolveOptions, asMeasurement, asMoney, flattenAttributes, formatMoney, getAttribute };

package/dist/attributes.d.ts

@@ -6,21 +6,21 @@
  * consumer ends up writing the same flatten + money/measurement coercions.
  * These are those helpers, typed.
  */
-export interface AttributeValueRecord {
+interface AttributeValueRecord {
     locale: string | null;
     channel: string | null;
     value: unknown;
 }
-export type AttributesPayload = Record<string, AttributeValueRecord[]>;
-export interface Money {
+type AttributesPayload = Record<string, AttributeValueRecord[]>;
+interface Money {
     amount_cents: number;
     currency: string;
 }
-export interface Measurement {
+interface Measurement {
     amount: number;
     unit: string;
 }
-export interface ResolveOptions {
+interface ResolveOptions {
     locale?: string | null;
     channel?: string | null;
 }
@@ -30,18 +30,19 @@ export interface ResolveOptions {
  * `(locale, null)` → `(null, channel)` → `(null, null)`. Returns
  * `undefined` when nothing matches.
  */
-export declare function getAttribute(attributes: AttributesPayload, code: string, opts?: ResolveOptions): unknown;
+declare function getAttribute(attributes: AttributesPayload, code: string, opts?: ResolveOptions): unknown;
 /**
  * Flatten an entire attribute payload to a `{ code: value }` map for a
  * (locale, channel) — the client-side equivalent of the server's
  * `resolvedAttributes`, for use on list responses where the server doesn't
  * flatten. Codes with no matching value are omitted.
  */
-export declare function flattenAttributes(attributes: AttributesPayload, opts?: ResolveOptions): Record<string, unknown>;
+declare function flattenAttributes(attributes: AttributesPayload, opts?: ResolveOptions): Record<string, unknown>;
 /** Narrow an attribute value to Money, or null if it isn't money-shaped. */
-export declare function asMoney(value: unknown): Money | null;
+declare function asMoney(value: unknown): Money | null;
 /** Narrow an attribute value to Measurement, or null if it isn't measurement-shaped. */
-export declare function asMeasurement(value: unknown): Measurement | null;
+declare function asMeasurement(value: unknown): Measurement | null;
 /** Format integer-cents Money as a localized currency string. */
-export declare function formatMoney(money: Money, locale?: string): string;
-//# sourceMappingURL=attributes.d.ts.map
+declare function formatMoney(money: Money, locale?: string): string;
+
+export { type AttributeValueRecord, type AttributesPayload, type Measurement, type Money, type ResolveOptions, asMeasurement, asMoney, flattenAttributes, formatMoney, getAttribute };

package/dist/attributes.js

@@ -1,76 +1,51 @@
-/**
- * Attribute helpers. MiniPim stores attribute values keyed by
- * `(locale, channel)` — list responses always return the raw
- * `{ code: [{ locale, channel, value }] }` shape (only product *detail*
- * with `?locale=&channel=` returns a flat `resolvedAttributes`). So every
- * consumer ends up writing the same flatten + money/measurement coercions.
- * These are those helpers, typed.
- */
-/**
- * Resolve a single attribute code to its value for a (locale, channel).
- * Fallback order mirrors the server: exact `(locale, channel)` →
- * `(locale, null)` → `(null, channel)` → `(null, null)`. Returns
- * `undefined` when nothing matches.
- */
-export function getAttribute(attributes, code, opts = {}) {
-    const records = attributes[code];
-    if (!records || records.length === 0)
-        return undefined;
-    const locale = opts.locale ?? null;
-    const channel = opts.channel ?? null;
-    const layers = [
-        [locale, channel],
-        [locale, null],
-        [null, channel],
-        [null, null],
-    ];
-    for (const [l, c] of layers) {
-        const hit = records.find((r) => r.locale === l && r.channel === c);
-        if (hit)
-            return hit.value;
-    }
-    return undefined;
+// src/attributes.ts
+function getAttribute(attributes, code, opts = {}) {
+  const records = attributes[code];
+  if (!records || records.length === 0) return void 0;
+  const locale = opts.locale ?? null;
+  const channel = opts.channel ?? null;
+  const layers = [
+    [locale, channel],
+    [locale, null],
+    [null, channel],
+    [null, null]
+  ];
+  for (const [l, c] of layers) {
+    const hit = records.find((r) => r.locale === l && r.channel === c);
+    if (hit) return hit.value;
+  }
+  return void 0;
 }
-/**
- * Flatten an entire attribute payload to a `{ code: value }` map for a
- * (locale, channel) — the client-side equivalent of the server's
- * `resolvedAttributes`, for use on list responses where the server doesn't
- * flatten. Codes with no matching value are omitted.
- */
-export function flattenAttributes(attributes, opts = {}) {
-    const out = {};
-    for (const code of Object.keys(attributes)) {
-        const v = getAttribute(attributes, code, opts);
-        if (v !== undefined)
-            out[code] = v;
-    }
-    return out;
+function flattenAttributes(attributes, opts = {}) {
+  const out = {};
+  for (const code of Object.keys(attributes)) {
+    const v = getAttribute(attributes, code, opts);
+    if (v !== void 0) out[code] = v;
+  }
+  return out;
 }
-/** Narrow an attribute value to Money, or null if it isn't money-shaped. */
-export function asMoney(value) {
-    if (value &&
-        typeof value === 'object' &&
-        typeof value.amount_cents === 'number' &&
-        typeof value.currency === 'string') {
-        return value;
-    }
-    return null;
+function asMoney(value) {
+  if (value && typeof value === "object" && typeof value.amount_cents === "number" && typeof value.currency === "string") {
+    return value;
+  }
+  return null;
 }
-/** Narrow an attribute value to Measurement, or null if it isn't measurement-shaped. */
-export function asMeasurement(value) {
-    if (value &&
-        typeof value === 'object' &&
-        typeof value.amount === 'number' &&
-        typeof value.unit === 'string') {
-        return value;
-    }
-    return null;
+function asMeasurement(value) {
+  if (value && typeof value === "object" && typeof value.amount === "number" && typeof value.unit === "string") {
+    return value;
+  }
+  return null;
 }
-/** Format integer-cents Money as a localized currency string. */
-export function formatMoney(money, locale = 'en-US') {
-    return new Intl.NumberFormat(locale, {
-        style: 'currency',
-        currency: money.currency,
-    }).format(money.amount_cents / 100);
+function formatMoney(money, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency
+  }).format(money.amount_cents / 100);
 }
-//# sourceMappingURL=attributes.js.map
+export {
+  asMeasurement,
+  asMoney,
+  flattenAttributes,
+  formatMoney,
+  getAttribute
+};

package/dist/index.cjs

@@ -0,0 +1,163 @@
+"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 src_exports = {};
+__export(src_exports, {
+  asMeasurement: () => asMeasurement,
+  asMoney: () => asMoney,
+  collectAll: () => collectAll,
+  createMinipimClient: () => createMinipimClient,
+  flattenAttributes: () => flattenAttributes,
+  formatMoney: () => formatMoney,
+  getAttribute: () => getAttribute,
+  getErrorMessage: () => getErrorMessage,
+  isMinipimError: () => isMinipimError,
+  paginate: () => paginate
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client.ts
+var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
+function createMinipimClient(opts) {
+  const headers = {
+    "x-organization-id": opts.organizationId,
+    ...opts.headers ?? {}
+  };
+  if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
+  if (opts.userId) headers["x-pim-user-id"] = opts.userId;
+  return (0, import_openapi_fetch.default)({
+    baseUrl: opts.baseUrl.replace(/\/$/, ""),
+    fetch: opts.fetch,
+    headers
+  });
+}
+
+// src/paginate.ts
+async function* paginate(client, path, opts = {}) {
+  const pageSize = opts.pageSize ?? 200;
+  let offset = 0;
+  for (; ; ) {
+    const get = client.GET;
+    const { data, error, response } = await get(path, {
+      params: { query: { ...opts.query ?? {}, limit: pageSize, offset } }
+    });
+    if (error || !data) {
+      throw new Error(
+        `paginate ${path} failed at offset ${offset} (HTTP ${response?.status})`
+      );
+    }
+    if (Array.isArray(data)) {
+      for (const item of data) yield item;
+      return;
+    }
+    if (!Array.isArray(data.data)) {
+      throw new Error(
+        `paginate ${path}: response is neither a list envelope nor an array \u2014 this endpoint may not be paginatable`
+      );
+    }
+    for (const item of data.data) yield item;
+    const more = data.hasMore ?? data.data.length === pageSize;
+    if (!more || data.data.length === 0) return;
+    offset += pageSize;
+  }
+}
+async function collectAll(client, path, opts = {}) {
+  const out = [];
+  for await (const item of paginate(client, path, opts)) out.push(item);
+  return out;
+}
+
+// src/errors.ts
+function isMinipimError(value) {
+  if (!value || typeof value !== "object") return false;
+  const e = value.error;
+  return !!e && typeof e === "object" && typeof e.code === "string" && typeof e.message === "string";
+}
+function getErrorMessage(error, fallback = "request failed") {
+  return isMinipimError(error) ? error.error.message : fallback;
+}
+
+// src/attributes.ts
+function getAttribute(attributes, code, opts = {}) {
+  const records = attributes[code];
+  if (!records || records.length === 0) return void 0;
+  const locale = opts.locale ?? null;
+  const channel = opts.channel ?? null;
+  const layers = [
+    [locale, channel],
+    [locale, null],
+    [null, channel],
+    [null, null]
+  ];
+  for (const [l, c] of layers) {
+    const hit = records.find((r) => r.locale === l && r.channel === c);
+    if (hit) return hit.value;
+  }
+  return void 0;
+}
+function flattenAttributes(attributes, opts = {}) {
+  const out = {};
+  for (const code of Object.keys(attributes)) {
+    const v = getAttribute(attributes, code, opts);
+    if (v !== void 0) out[code] = v;
+  }
+  return out;
+}
+function asMoney(value) {
+  if (value && typeof value === "object" && typeof value.amount_cents === "number" && typeof value.currency === "string") {
+    return value;
+  }
+  return null;
+}
+function asMeasurement(value) {
+  if (value && typeof value === "object" && typeof value.amount === "number" && typeof value.unit === "string") {
+    return value;
+  }
+  return null;
+}
+function formatMoney(money, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency
+  }).format(money.amount_cents / 100);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asMeasurement,
+  asMoney,
+  collectAll,
+  createMinipimClient,
+  flattenAttributes,
+  formatMoney,
+  getAttribute,
+  getErrorMessage,
+  isMinipimError,
+  paginate
+});

package/dist/index.d.cts

@@ -0,0 +1,132 @@
+import { Client } from 'openapi-fetch';
+import { paths } from './openapi.cjs';
+export { components, operations } from './openapi.cjs';
+export { AttributeValueRecord, AttributesPayload, Measurement, Money, ResolveOptions, asMeasurement, asMoney, flattenAttributes, formatMoney, getAttribute } from './attributes.cjs';
+
+/**
+ * Thin wrapper around `openapi-fetch` that pre-binds the tenancy header and
+ * (optionally) an API key. Returns the standard openapi-fetch client, so all
+ * its features (request interceptors, raw response access, etc.) work as
+ * documented at https://openapi-ts.dev/openapi-fetch/.
+ */
+
+interface CreateMinipimClientOptions {
+    /**
+     * Base URL of the MiniPim API, e.g. `https://api.minipim.com`. Required.
+     * Trailing slashes are normalized.
+     */
+    baseUrl: string;
+    /**
+     * Tenant the client speaks for. Required — every authenticated endpoint
+     * needs `x-organization-id`. API keys identify the principal, not the
+     * tenant.
+     */
+    organizationId: string;
+    /**
+     * Bearer API key (e.g. `pim_abc123…`). Issue one in the admin under
+     * /api-keys. If you're running in dev with `PIM_AUTH=header`, omit this
+     * and set `userId` instead.
+     */
+    apiKey?: string;
+    /**
+     * Dev-only header (`x-pim-user-id`). Only set when the deployment is in
+     * `header` auth mode. Ignored in `jwt` / `clerk` deployments.
+     */
+    userId?: string;
+    /**
+     * Extra headers merged onto every request — useful for tracing IDs,
+     * feature flags, etc. Don't put auth here; use `apiKey`/`userId` so the
+     * names stay consistent.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override `fetch` — pass a polyfill in Node <18 or a wrapped fetch that
+     * adds timeouts, retries, telemetry. Defaults to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+}
+type MinipimClient = Client<paths>;
+/**
+ * Create a typed MiniPim client.
+ *
+ * @example
+ * ```ts
+ * import { createMinipimClient } from '@minipim/sdk';
+ *
+ * const pim = createMinipimClient({
+ *   baseUrl: 'https://api.minipim.com',
+ *   organizationId: '00000000-0000-0000-0000-000000000001',
+ *   apiKey: process.env.MINIPIM_API_KEY!,
+ * });
+ *
+ * const { data, error } = await pim.GET('/v1/products', {
+ *   params: { query: { limit: 50, categoryId: '…' } },
+ * });
+ * if (error) throw new Error(error.error.message);
+ * console.log(data.hasMore, data.data.length);
+ * ```
+ */
+declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimClient;
+
+/**
+ * Generic pagination helper. Every MiniPim list endpoint returns
+ * `{ data, limit, offset, hasMore }`; this walks the pages so consumers
+ * don't hand-roll the `hasMore` loop. Yields one item at a time.
+ *
+ * Typed loosely on purpose — openapi-fetch's per-path generics don't
+ * compose into a single reusable signature without a lot of conditional-
+ * type machinery, and the envelope shape is uniform across list endpoints.
+ * The item type is yours to specify via the generic.
+ */
+
+interface PaginateOptions {
+    /** Query params (filters, sort, withTotal, etc). `limit`/`offset` are managed for you. */
+    query?: Record<string, unknown>;
+    /** Page size. Default 200 (the API max). */
+    pageSize?: number;
+}
+/**
+ * Async-iterate every item across all pages of a MiniPim list endpoint.
+ *
+ * @example
+ * ```ts
+ * import { paginate } from '@minipim/sdk';
+ * for await (const product of paginate<Product>(pim, '/v1/products', {
+ *   query: { status: 'active' },
+ * })) {
+ *   await ingest(product);
+ * }
+ * ```
+ */
+declare function paginate<T = unknown>(client: MinipimClient, path: string, opts?: PaginateOptions): AsyncGenerator<T, void, unknown>;
+/** Collect every page into an array. Convenience around {@link paginate}. */
+declare function collectAll<T = unknown>(client: MinipimClient, path: string, opts?: PaginateOptions): Promise<T[]>;
+
+/**
+ * Error envelope + type guard. Every MiniPim 4xx/5xx returns
+ * `{ error: { code, message, details? } }`. openapi-fetch types `res.error`
+ * as a union across a path's declared error responses, which is awkward to
+ * narrow to `.error.message`. This guard collapses that to a single shape.
+ */
+interface MinipimError {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** True when `value` is a MiniPim `{ error: { code, message } }` envelope. */
+declare function isMinipimError(value: unknown): value is MinipimError;
+/**
+ * Pull a human-readable message out of an openapi-fetch `error` value,
+ * whatever its declared union shape. Falls back to `fallback`.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await pim.GET('/v1/products');
+ * if (error) throw new Error(getErrorMessage(error, 'request failed'));
+ * ```
+ */
+declare function getErrorMessage(error: unknown, fallback?: string): string;
+
+export { type CreateMinipimClientOptions, type MinipimClient, type MinipimError, type PaginateOptions, collectAll, createMinipimClient, getErrorMessage, isMinipimError, paginate, paths };