@minipim/sdk 0.1.0 → 0.3.0

package/dist/openapi.d.ts

@@ -2,7 +2,7 @@
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
  */
-export interface paths {
+interface paths {
     "/healthz": {
         parameters: {
             query?: never;
@@ -1176,7 +1176,7 @@ export interface paths {
                     brand?: string;
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
                     sortDir?: "asc" | "desc";
                     limit?: number;
                     offset?: number;
@@ -1342,7 +1342,7 @@ export interface paths {
                     brand?: string;
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
                     sortDir?: "asc" | "desc";
                     locale?: string;
                     channel?: string;
@@ -1725,6 +1725,9 @@ export interface paths {
                                 missing: {
                                     code: string;
                                     locale: string | null;
+                                    label?: string;
+                                    variantsMissing?: number;
+                                    variantsTotal?: number;
                                 }[];
                             }[];
                         };
@@ -2139,6 +2142,36 @@ export interface paths {
                         }[];
                     };
                 };
+                /** @description Default Response */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
             };
         };
         put?: never;
@@ -3223,10 +3256,16 @@ export interface paths {
          *     To get a single category's full ancestor path, walk `parentId` upwards
          *     client-side, or hit `GET /v1/categories/{id}` which returns the same row
          *     shape with the resolved path included in `path`.
+         *
+         *     Returns the full tree by default. `?limit=` / `?offset=` are supported
+         *     for large taxonomies (ordered by `position`); omit them to get everything.
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    limit?: number;
+                    offset?: number;
+                };
                 header?: never;
                 path?: never;
                 cookie?: never;
@@ -5848,7 +5887,7 @@ export interface paths {
         put?: never;
         /**
          * Trigger a sync (pull / push / both)
-         * @description Synchronous in v1 — runs in-request and returns after completion. Larger syncs will move to a background worker; the call site stays the same (returns a sync record id immediately, status fills in async).
+         * @description Asynchronous: returns the sync record immediately with status `running`; the work continues in the background. Poll `GET /v1/connectors/{id}/syncs` for the terminal status (`completed`/`partial`/`failed`) and stats. Pulls download media binaries and routinely take minutes — running in-request exceeded proxy timeouts, which severed responses mid-sync and invited retry double-pulls. Caveat: a server restart mid-sync leaves the row `running` forever; a BullMQ worker will make this durable later.
          */
         post: {
             parameters: {
@@ -6359,6 +6398,146 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/connectors/{id}/deliveries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Recent outbound webhook deliveries for a connector
+         * @description Last 50 delivery attempts (event name, HTTP status, ok, error) for push connectors that POST events to a destination (e.g. headless). Answers "did any events actually arrive?" without grepping receiver logs.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** Format: uuid */
+                            id: string;
+                            eventName: string;
+                            status: number | null;
+                            ok: boolean;
+                            error: string | null;
+                            /** Format: date-time */
+                            createdAt: string;
+                        }[];
+                    };
+                };
+                /** @description Default Response */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/connectors/{id}/webhooks/test": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Send a signed test event to the connector destination
+         * @description Delivers a synthetic `webhook.test` event (HMAC-signed like any real delivery) so integrators can verify endpoint wiring without mutating catalog data. Returns the delivery outcome and logs it like any other.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            ok: boolean;
+                            status: number | null;
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Default Response */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/connectors/{id}/webhooks/enable": {
         parameters: {
             query?: never;
@@ -6848,8 +7027,8 @@ export interface paths {
         trace?: never;
     };
 }
-export type webhooks = Record<string, never>;
-export interface components {
+type webhooks = Record<string, never>;
+interface components {
     schemas: never;
     responses: never;
     parameters: never;
@@ -6857,6 +7036,7 @@ export interface components {
     headers: never;
     pathItems: never;
 }
-export type $defs = Record<string, never>;
-export type operations = Record<string, never>;
-//# sourceMappingURL=openapi.d.ts.map
+type $defs = Record<string, never>;
+type operations = Record<string, never>;
+
+export type { $defs, components, operations, paths, webhooks };

package/dist/openapi.js

@@ -1,6 +0,0 @@
-/**
- * This file was auto-generated by openapi-typescript.
- * Do not make direct changes to the file.
- */
-export {};
-//# sourceMappingURL=openapi.js.map

package/dist/webhook-edge.cjs

@@ -0,0 +1,68 @@
+"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/webhook-edge.ts
+var webhook_edge_exports = {};
+__export(webhook_edge_exports, {
+  verifyMinipimWebhookEdge: () => verifyMinipimWebhookEdge
+});
+module.exports = __toCommonJS(webhook_edge_exports);
+
+// src/webhook-shared.ts
+function decodeHex(s) {
+  if (s.length % 2 !== 0) return new Uint8Array(0);
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return new Uint8Array(0);
+    out[i] = byte;
+  }
+  return out;
+}
+function stripPrefix(sig) {
+  return sig.startsWith("sha256=") ? sig.slice(7) : sig;
+}
+function timingSafeEqualBytes(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return diff === 0;
+}
+
+// src/webhook-edge.ts
+async function verifyMinipimWebhookEdge(opts) {
+  const enc = new TextEncoder();
+  const keyData = enc.encode(opts.secret);
+  const bodyData = typeof opts.rawBody === "string" ? enc.encode(opts.rawBody) : new Uint8Array(opts.rawBody);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBuf = await crypto.subtle.sign("HMAC", key, bodyData);
+  const expected = new Uint8Array(sigBuf);
+  const got = decodeHex(stripPrefix(opts.signature));
+  return timingSafeEqualBytes(expected, got);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  verifyMinipimWebhookEdge
+});

package/dist/webhook-edge.d.cts

@@ -0,0 +1,26 @@
+import { V as VerifyWebhookOptions } from './webhook-shared-CjMkFYVb.cjs';
+
+/**
+ * Edge / browser webhook signature verification, via WebCrypto. Use in
+ * Cloudflare Workers, Vercel Edge Runtime, Deno, or browsers. Async because
+ * `crypto.subtle` is async. For Node use `@minipim/sdk/webhook` (synchronous).
+ *
+ * This entry point imports no `node:` modules, so it's safe in any Edge
+ * bundle.
+ */
+
+/**
+ * Verify a MiniPim webhook signature in an Edge/WebCrypto runtime. Same
+ * contract as the Node `verifyMinipimWebhook` but async.
+ *
+ * @example
+ * ```ts
+ * import { verifyMinipimWebhookEdge } from '@minipim/sdk/webhook-edge';
+ *
+ * const ok = await verifyMinipimWebhookEdge({ rawBody, signature, secret });
+ * if (!ok) return new Response('invalid signature', { status: 401 });
+ * ```
+ */
+declare function verifyMinipimWebhookEdge(opts: VerifyWebhookOptions): Promise<boolean>;
+
+export { VerifyWebhookOptions, verifyMinipimWebhookEdge };

package/dist/webhook-edge.d.ts

@@ -0,0 +1,26 @@
+import { V as VerifyWebhookOptions } from './webhook-shared-CjMkFYVb.js';
+
+/**
+ * Edge / browser webhook signature verification, via WebCrypto. Use in
+ * Cloudflare Workers, Vercel Edge Runtime, Deno, or browsers. Async because
+ * `crypto.subtle` is async. For Node use `@minipim/sdk/webhook` (synchronous).
+ *
+ * This entry point imports no `node:` modules, so it's safe in any Edge
+ * bundle.
+ */
+
+/**
+ * Verify a MiniPim webhook signature in an Edge/WebCrypto runtime. Same
+ * contract as the Node `verifyMinipimWebhook` but async.
+ *
+ * @example
+ * ```ts
+ * import { verifyMinipimWebhookEdge } from '@minipim/sdk/webhook-edge';
+ *
+ * const ok = await verifyMinipimWebhookEdge({ rawBody, signature, secret });
+ * if (!ok) return new Response('invalid signature', { status: 401 });
+ * ```
+ */
+declare function verifyMinipimWebhookEdge(opts: VerifyWebhookOptions): Promise<boolean>;
+
+export { VerifyWebhookOptions, verifyMinipimWebhookEdge };

package/dist/webhook-edge.js

@@ -0,0 +1,41 @@
+// src/webhook-shared.ts
+function decodeHex(s) {
+  if (s.length % 2 !== 0) return new Uint8Array(0);
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return new Uint8Array(0);
+    out[i] = byte;
+  }
+  return out;
+}
+function stripPrefix(sig) {
+  return sig.startsWith("sha256=") ? sig.slice(7) : sig;
+}
+function timingSafeEqualBytes(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return diff === 0;
+}
+
+// src/webhook-edge.ts
+async function verifyMinipimWebhookEdge(opts) {
+  const enc = new TextEncoder();
+  const keyData = enc.encode(opts.secret);
+  const bodyData = typeof opts.rawBody === "string" ? enc.encode(opts.rawBody) : new Uint8Array(opts.rawBody);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBuf = await crypto.subtle.sign("HMAC", key, bodyData);
+  const expected = new Uint8Array(sigBuf);
+  const got = decodeHex(stripPrefix(opts.signature));
+  return timingSafeEqualBytes(expected, got);
+}
+export {
+  verifyMinipimWebhookEdge
+};

package/dist/webhook-shared-CjMkFYVb.d.cts

@@ -0,0 +1,25 @@
+/**
+ * Pure helpers shared by the Node and Edge webhook verifiers. Deliberately
+ * free of `node:crypto` and WebCrypto so importing this file drags neither
+ * runtime's crypto into a bundle.
+ */
+interface VerifyWebhookOptions {
+    /**
+     * The **raw** request body — bytes or a string. **Not** the parsed JSON.
+     * Re-stringifying the parsed body reorders keys / changes whitespace and
+     * the HMAC will not match.
+     *
+     * Next.js route handler: `const raw = await req.text()`.
+     * Express: `express.raw({ type: 'application/json' })`, then `req.body`.
+     */
+    rawBody: string | Uint8Array;
+    /**
+     * Value of the `X-MiniPim-Signature-256` header — `sha256=<hex>`. Pass it
+     * verbatim; the verifier strips the prefix.
+     */
+    signature: string;
+    /** The secret configured on the headless connector. */
+    secret: string;
+}
+
+export type { VerifyWebhookOptions as V };

package/dist/webhook-shared-CjMkFYVb.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure helpers shared by the Node and Edge webhook verifiers. Deliberately
+ * free of `node:crypto` and WebCrypto so importing this file drags neither
+ * runtime's crypto into a bundle.
+ */
+interface VerifyWebhookOptions {
+    /**
+     * The **raw** request body — bytes or a string. **Not** the parsed JSON.
+     * Re-stringifying the parsed body reorders keys / changes whitespace and
+     * the HMAC will not match.
+     *
+     * Next.js route handler: `const raw = await req.text()`.
+     * Express: `express.raw({ type: 'application/json' })`, then `req.body`.
+     */
+    rawBody: string | Uint8Array;
+    /**
+     * Value of the `X-MiniPim-Signature-256` header — `sha256=<hex>`. Pass it
+     * verbatim; the verifier strips the prefix.
+     */
+    signature: string;
+    /** The secret configured on the headless connector. */
+    secret: string;
+}
+
+export type { VerifyWebhookOptions as V };

package/dist/webhook.cjs

@@ -0,0 +1,53 @@
+"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/webhook.ts
+var webhook_exports = {};
+__export(webhook_exports, {
+  verifyMinipimWebhook: () => verifyMinipimWebhook
+});
+module.exports = __toCommonJS(webhook_exports);
+var import_node_crypto = require("crypto");
+
+// src/webhook-shared.ts
+function decodeHex(s) {
+  if (s.length % 2 !== 0) return new Uint8Array(0);
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return new Uint8Array(0);
+    out[i] = byte;
+  }
+  return out;
+}
+function stripPrefix(sig) {
+  return sig.startsWith("sha256=") ? sig.slice(7) : sig;
+}
+
+// src/webhook.ts
+function verifyMinipimWebhook(opts) {
+  const expected = (0, import_node_crypto.createHmac)("sha256", opts.secret).update(opts.rawBody).digest();
+  const got = decodeHex(stripPrefix(opts.signature));
+  if (got.length !== expected.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(expected, got);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  verifyMinipimWebhook
+});

package/dist/webhook.d.cts

@@ -0,0 +1,26 @@
+import { V as VerifyWebhookOptions } from './webhook-shared-CjMkFYVb.cjs';
+
+/**
+ * Verify a MiniPim webhook signature in Node. Returns `true` only when the
+ * signature is valid; returns `false` on any problem (wrong signature,
+ * malformed header, length mismatch). Constant-time comparison.
+ *
+ * @example
+ * ```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') ?? '';
+ *   if (!verifyMinipimWebhook({ rawBody: raw, signature: sig, secret })) {
+ *     return new Response('invalid signature', { status: 401 });
+ *   }
+ *   const event = JSON.parse(raw);
+ *   // ...handle event, respond 2xx
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ */
+declare function verifyMinipimWebhook(opts: VerifyWebhookOptions): boolean;
+
+export { VerifyWebhookOptions, verifyMinipimWebhook };

package/dist/webhook.d.ts

@@ -1,44 +1,14 @@
+import { V as VerifyWebhookOptions } from './webhook-shared-CjMkFYVb.js';
+
 /**
- * Webhook signature verification helpers.
- *
- * MiniPim's headless connector POSTs events to a configured URL with an
- * `X-MiniPim-Signature-256` header containing `sha256=<hex>` — the HMAC of
- * the raw request body keyed by the connector's secret. Verifying it
- * correctly is the #1 thing webhook consumers get wrong, so the SDK ships a
- * reference implementation.
- *
- * Two variants exported:
- *  - `verifyMinipimWebhook`     — sync, Node `crypto`. Use in any Node
- *                                 server (Express, Fastify, Next App Router
- *                                 route handlers).
- *  - `verifyMinipimWebhookEdge` — async, WebCrypto subtle. For Cloudflare
- *                                 Workers, Vercel Edge, Deno, browsers.
- */
-export interface VerifyWebhookOptions {
-    /**
-     * The **raw** request body — bytes or a string. **Not** the parsed JSON.
-     * If you re-stringify the parsed body, whitespace and key ordering will
-     * differ from the original, and the HMAC will not match.
-     *
-     * In Next.js route handlers: `const rawBody = await req.text()`.
-     * In Express: register `express.raw({ type: 'application/json' })` and
-     * read `req.body` (it'll be a Buffer).
-     */
-    rawBody: string | Uint8Array;
-    /**
-     * Value of the `X-MiniPim-Signature-256` header. Format:
-     * `sha256=<hex>` — pass it verbatim. The function strips the prefix.
-     */
-    signature: string;
-    /** The secret you configured on the headless connector. */
-    secret: string;
-}
-/**
- * Verify a MiniPim webhook signature in a Node environment.
+ * Verify a MiniPim webhook signature in Node. Returns `true` only when the
+ * signature is valid; returns `false` on any problem (wrong signature,
+ * malformed header, length mismatch). Constant-time comparison.
  *
  * @example
  * ```ts
- * // Next.js App Router route handler
+ * 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') ?? '';
@@ -46,21 +16,11 @@ export interface VerifyWebhookOptions {
  *     return new Response('invalid signature', { status: 401 });
  *   }
  *   const event = JSON.parse(raw);
- *   // ... handle event
+ *   // ...handle event, respond 2xx
  *   return Response.json({ ok: true });
  * }
  * ```
- *
- * Returns `false` on any verification problem (wrong signature, malformed
- * header, length mismatch). Constant-time comparison — safe against timing
- * attacks. Throws only if `node:crypto` is unavailable; if you're on Edge,
- * use `verifyMinipimWebhookEdge` instead.
- */
-export declare function verifyMinipimWebhook(opts: VerifyWebhookOptions): Promise<boolean>;
-/**
- * Edge / browser variant using WebCrypto. Same shape as
- * {@link verifyMinipimWebhook}; use this in Cloudflare Workers, Vercel
- * Edge Runtime, Deno, or browsers.
  */
-export declare function verifyMinipimWebhookEdge(opts: VerifyWebhookOptions): Promise<boolean>;
-//# sourceMappingURL=webhook.d.ts.map
+declare function verifyMinipimWebhook(opts: VerifyWebhookOptions): boolean;
+
+export { VerifyWebhookOptions, verifyMinipimWebhook };