@minipim/sdk 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# @minipim/sdk
+
+Typed TypeScript client for the [MiniPim](https://github.com/Epic-Design-Labs/minipim) API. Generated from the OpenAPI spec at `/docs/json` and wrapped with `openapi-fetch` plus a webhook-signature helper.
+
+## Install
+
+```bash
+pnpm add @minipim/sdk
+```
+
+Requires Node 18+ (for native `fetch`) or a fetch polyfill.
+
+## Quick start
+
+```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!,
+});
+
+// List products
+const { data, error } = await pim.GET('/v1/products', {
+  params: { query: { limit: 50, sortBy: 'name', sortDir: 'asc' } },
+});
+if (error) throw new Error(error.error.message);
+console.log(`got ${data.data.length} products, hasMore: ${data.hasMore}`);
+
+// Single product with locale + channel resolution
+const product = await pim.GET('/v1/products/{id}', {
+  params: {
+    path: { id: '0b8c5d3a-…' },
+    query: { locale: 'en_US', channel: 'headless-main' },
+  },
+});
+console.log(product.data?.resolvedAttributes);
+```
+
+## Authentication
+
+API keys (recommended for service-to-service):
+
+```ts
+const pim = createMinipimClient({
+  baseUrl: 'https://api.minipim.com',
+  organizationId: '<your-org-uuid>',
+  apiKey: 'pim_xxxxxxxxxxxx',
+});
+```
+
+Issue keys in the admin UI at `/api-keys`. `x-organization-id` is required separately — API keys identify the principal, not the tenant.
+
+Dev mode (header auth) — only when the deployment is started with `PIM_AUTH=header`:
+
+```ts
+const pim = createMinipimClient({
+  baseUrl: 'http://localhost:4100',
+  organizationId: '00000000-0000-0000-0000-000000000001',
+  userId: 'dev-test',
+});
+```
+
+## Webhooks
+
+The headless connector POSTs events to your URL with an HMAC-SHA256 signature in `X-MiniPim-Signature-256`. Verify against the **raw** body — re-stringified JSON breaks the signature.
+
+### Next.js App Router
+
+```ts
+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({
+    rawBody: raw,
+    signature: sig,
+    secret: process.env.MINIPIM_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response('invalid signature', { status: 401 });
+
+  const event = JSON.parse(raw);
+  // event.name = 'product.updated' | 'category.deleted' | ...
+  // event.entity_id, event.payload, etc.
+  // Handle + return 2xx — non-2xx is silently dropped in v1 (no retries yet).
+  return Response.json({ ok: true });
+}
+```
+
+### Edge / Cloudflare Workers / Vercel Edge
+
+```ts
+import { verifyMinipimWebhookEdge } from '@minipim/sdk/webhook';
+
+const ok = await verifyMinipimWebhookEdge({ rawBody, signature, secret });
+```
+
+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.
+
+## Pagination
+
+Every list endpoint returns `{ data, limit, offset, hasMore, total? }`. Iterate via `hasMore`:
+
+```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;
+  }
+}
+```
+
+Pass `withTotal: true` if you need `data.total` — adds one `COUNT(*)` query, so leave it off on hot reads.
+
+## Reconciliation after downtime
+
+`?updatedSince=<iso8601>` filters the product list to rows modified after a timestamp. Pair with `hasMore` to walk the changeset back to current state:
+
+```ts
+async function catchUp(since: string) {
+  for await (const p of allProducts({ updatedSince: since })) {
+    await ingest(p);
+  }
+}
+```
+
+## TypeScript reference
+
+```ts
+import type { paths, components, operations } from '@minipim/sdk';
+type Product = components['schemas']['ProductSelect'];
+```
+
+The generated `paths`, `components`, and `operations` cover the full surface at `/docs/json`. Use them to type DTOs, request handlers, etc.
+
+## Related
+
+- [Narrative integration guide](https://github.com/Epic-Design-Labs/minipim/blob/main/docs/DEVELOPERS.md) — auth, pagination, locale/channel resolution, webhook contract, common integration shapes.
+- [Swagger UI](https://api.minipim.com/docs) — interactive endpoint reference, try-it-out enabled.
+- [OpenAPI spec](https://api.minipim.com/docs/json) — raw JSON, what this SDK is generated from.
+
+## License
+
+Apache-2.0.

package/dist/client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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/.
+ */
+import { type Client } from 'openapi-fetch';
+import type { paths } from './openapi.js';
+export 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;
+}
+export 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);
+ * ```
+ */
+export declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAqB,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,0BAA0B,GAC/B,aAAa,CAaf"}

package/dist/client.js

@@ -0,0 +1,43 @@
+/**
+ * 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/.
+ */
+import createClient from 'openapi-fetch';
+/**
+ * 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);
+ * ```
+ */
+export 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 createClient({
+        baseUrl: opts.baseUrl.replace(/\/$/, ''),
+        fetch: opts.fetch,
+        headers,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,YAA6B,MAAM,eAAe,CAAC;AAyC1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAgC;IAEhC,MAAM,OAAO,GAA2B;QACtC,mBAAmB,EAAE,IAAI,CAAC,cAAc;QACxC,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;KACxB,CAAC;IACF,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;IACpE,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IAExD,OAAO,YAAY,CAAQ;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACxC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @minipim/sdk — typed TypeScript client for the MiniPim API.
+ *
+ * See https://github.com/Epic-Design-Labs/minipim/blob/main/packages/sdk/README.md
+ * for examples; the canonical narrative integration guide lives at
+ * https://github.com/Epic-Design-Labs/minipim/blob/main/docs/DEVELOPERS.md.
+ */
+export { createMinipimClient, type CreateMinipimClientOptions, type MinipimClient, } from './client.js';
+export { verifyMinipimWebhook, verifyMinipimWebhookEdge, type VerifyWebhookOptions, } from './webhook.js';
+export type { paths, components, operations } from './openapi.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AAItB,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @minipim/sdk — typed TypeScript client for the MiniPim API.
+ *
+ * See https://github.com/Epic-Design-Labs/minipim/blob/main/packages/sdk/README.md
+ * for examples; the canonical narrative integration guide lives at
+ * https://github.com/Epic-Design-Labs/minipim/blob/main/docs/DEVELOPERS.md.
+ */
+export { createMinipimClient, } from './client.js';
+export { verifyMinipimWebhook, verifyMinipimWebhookEdge, } from './webhook.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,GAGpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GAEzB,MAAM,cAAc,CAAC"}