@minipim/sdk 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,15 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+This project is licensed under the GNU Affero General Public License v3.0.
+The full text of the license is available at:
+  https://www.gnu.org/licenses/agpl-3.0.txt
+
+Copyright (c) 2026 Epic Design Labs
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -8,7 +8,9 @@ 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.
+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.
 
 ## Quick start
 
@@ -74,7 +76,8 @@ import { verifyMinipimWebhook } from '@minipim/sdk/webhook';
 export async function POST(req: Request) {
   const raw = await req.text();
   const sig = req.headers.get('x-minipim-signature-256') ?? '';
-  const ok = await verifyMinipimWebhook({
+  // Node verifier is synchronous — no await.
+  const ok = verifyMinipimWebhook({
     rawBody: raw,
     signature: sig,
     secret: process.env.MINIPIM_WEBHOOK_SECRET!,
@@ -92,36 +95,76 @@ export async function POST(req: Request) {
 ### Edge / Cloudflare Workers / Vercel Edge
 
 ```ts
-import { verifyMinipimWebhookEdge } from '@minipim/sdk/webhook';
+import { verifyMinipimWebhookEdge } from '@minipim/sdk/webhook-edge';
 
 const ok = await verifyMinipimWebhookEdge({ rawBody, signature, secret });
+if (!ok) return new Response('invalid signature', { status: 401 });
 ```
 
 Both functions:
 - Constant-time comparison (safe against timing attacks).
 - Return `false` on malformed signatures (don't throw).
-- Same interface; the only difference is which crypto API they use under the hood.
+
+**Node verifier is synchronous; Edge verifier is async.** The Node one (`@minipim/sdk/webhook`) returns `boolean` — use it directly in `if (!verifyMinipimWebhook(...))`. The Edge one (`@minipim/sdk/webhook-edge`) returns `Promise<boolean>` — you must `await` it. They live on separate entry points so the Node `node:crypto` import never lands in an Edge bundle.
 
 ## Pagination
 
-Every list endpoint returns `{ data, limit, offset, hasMore, total? }`. Iterate via `hasMore`:
+Don't hand-roll the `hasMore` loop — the SDK ships `paginate`, a generic async iterator over any list endpoint:
 
 ```ts
-async function* allProducts() {
-  let offset = 0;
-  for (;;) {
-    const { data, error } = await pim.GET('/v1/products', {
-      params: { query: { limit: 200, offset } },
-    });
-    if (error) throw new Error(error.error.message);
-    for (const p of data.data) yield p;
-    if (!data.hasMore) return;
-    offset += 200;
-  }
+import { paginate, collectAll } from '@minipim/sdk';
+import type { components } from '@minipim/sdk';
+
+type Product = components['schemas']['ProductSelect'];
+
+// stream
+for await (const p of paginate<Product>(pim, '/v1/products', { query: { status: 'active' } })) {
+  await ingest(p);
 }
+
+// or collect everything
+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:
+
+```ts
+import {
+  flattenAttributes, getAttribute, asMoney, asMeasurement, formatMoney,
+} from '@minipim/sdk';
+
+// resolve one code for a (locale, channel), with server-matching fallback
+const desc = getAttribute(product.attributes, 'description', { locale: 'en_US', channel: 'headless-main' });
+
+// flatten the whole bag (client-side equivalent of resolvedAttributes, for lists)
+const flat = flattenAttributes(product.attributes, { locale: 'en_US', channel: 'headless-main' });
+
+// coerce money / measurement shapes
+const price = asMoney(getAttribute(product.attributes, 'price'));      // { amount_cents, currency } | null
+if (price) console.log(formatMoney(price));                            // "$18.99"
+const weight = asMeasurement(getAttribute(product.attributes, 'weight')); // { amount, unit } | null
 ```
 
-Pass `withTotal: true` if you need `data.total` — adds one `COUNT(*)` query, so leave it off on hot reads.
+Also available at the `@minipim/sdk/attributes` subpath.
+
+## Error handling
+
+`res.error` is a per-path union that's awkward to narrow. Use the shared guard:
+
+```ts
+import { isMinipimError, getErrorMessage } from '@minipim/sdk';
+
+const { data, error } = await pim.GET('/v1/products/{id}', { params: { path: { id } } });
+if (error) {
+  throw new Error(getErrorMessage(error, 'fetch failed'));   // pulls error.error.message
+}
+```
 
 ## Reconciliation after downtime
 

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

@@ -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.js

@@ -0,0 +1,51 @@
+// 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);
+}
+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 };