@solumflow-app/crm-client 0.1.0

package/dist/mirror.cjs

@@ -0,0 +1,127 @@
+"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/mirror.ts
+var mirror_exports = {};
+__export(mirror_exports, {
+  createCatalogueMirror: () => createCatalogueMirror
+});
+module.exports = __toCommonJS(mirror_exports);
+var DEFAULT_PAGE_SIZE = 50;
+var PRODUCT_CEILING = 1e5;
+function createCatalogueMirror(options) {
+  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+  async function pull(ids) {
+    const upserted = [];
+    const removed = [];
+    const failed = [];
+    for (const id of ids) {
+      let product;
+      try {
+        product = await options.client.getProduct(id);
+      } catch {
+        failed.push(id);
+        continue;
+      }
+      if (product === null) {
+        await options.target.remove({ id });
+        removed.push(id);
+        continue;
+      }
+      await options.target.upsert({ id, product });
+      upserted.push(id);
+    }
+    return { upserted, removed, failed };
+  }
+  async function syncAll() {
+    const seen = [];
+    const positions = /* @__PURE__ */ new Set();
+    let cursor = null;
+    do {
+      const page = await options.client.getProducts({
+        limit: pageSize,
+        cursor
+      });
+      for (const item of page.data) {
+        seen.push(item.id);
+      }
+      cursor = page.nextCursor;
+      if (cursor !== null) {
+        if (positions.has(cursor)) {
+          throw new Error(
+            "crm-client: the catalogue handed back a cursor it had already given, so the walk is not advancing. Nothing was removed."
+          );
+        }
+        positions.add(cursor);
+      }
+      if (seen.length > PRODUCT_CEILING) {
+        throw new Error(
+          `crm-client: more than ${PRODUCT_CEILING} products were walked without reaching the end of the catalogue. Nothing was removed.`
+        );
+      }
+    } while (cursor);
+    const pulled = await pull(seen);
+    const removed = [...pulled.removed];
+    const held = pulled.failed.length ? void 0 : await options.target.listMirroredIds?.();
+    if (held) {
+      const present = new Set(seen);
+      for (const id of held) {
+        if (!present.has(id)) {
+          await options.target.remove({ id });
+          removed.push(id);
+        }
+      }
+    }
+    return {
+      upserted: pulled.upserted,
+      removed,
+      failed: pulled.failed,
+      resynchronised: true
+    };
+  }
+  return {
+    syncAll,
+    async apply(payload) {
+      if (!payload.type.startsWith("product.")) {
+        return { upserted: [], removed: [], failed: [], resynchronised: false };
+      }
+      if (payload.truncated === true) {
+        return syncAll();
+      }
+      if (payload.type === "product.deleted") {
+        for (const id of payload.ids) {
+          await options.target.remove({ id });
+        }
+        return {
+          upserted: [],
+          removed: [...payload.ids],
+          failed: [],
+          resynchronised: false
+        };
+      }
+      const pulled = await pull(payload.ids);
+      return { ...pulled, resynchronised: false };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCatalogueMirror
+});
+//# sourceMappingURL=mirror.cjs.map

package/dist/mirror.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mirror.ts"],"sourcesContent":["import type { CrmClient } from './client';\nimport type { ApiWebhookPayload, ProductDetail } from './types';\n\nconst DEFAULT_PAGE_SIZE = 50;\n/**\n * Where a walk stops believing itself.\n *\n * Not a limit on how large a catalogue may be -- it is set far past any real\n * one on purpose. Reaching it means the listing is not ending, which is a fault\n * and not a big shop, and the difference decides what happens: a fault throws.\n */\nconst PRODUCT_CEILING = 100_000;\n\n/**\n * Where a mirrored catalogue is kept, in whatever vocabulary that store uses.\n *\n * This is the one part a site has to write, and it is deliberately the only\n * part. The shape of the local collection is not a detail this package could\n * guess: a Payload shop built on the ecommerce plugin stores `title`,\n * `priceInEUR` and a `gallery` of uploads, the catalogue here answers `name`,\n * `priceFromCents` and `images` of URLs, and no mapping between the two is\n * general — the next shop names them differently again, or keeps only three of\n * them, or has no images at all.\n *\n * What *is* general is everything around it, and that is what this file owns:\n * which ids a delivery actually changed, what to do when the id list came back\n * truncated, and the fact that a product which has stopped answering has to be\n * removed rather than skipped.\n */\nexport interface MirrorTarget {\n  /** Write it, whatever \"it\" looks like locally. Called once per product. */\n  upsert(input: { id: string; product: ProductDetail }): void | Promise<void>;\n  /**\n   * Take it out of the mirror.\n   *\n   * Called for a `product.deleted` delivery and, just as importantly, for a\n   * product that no longer answers — a seller who moved something back to draft\n   * produces no deletion event, because nothing was deleted.\n   */\n  remove(input: { id: string }): void | Promise<void>;\n  /**\n   * Every id currently held in the mirror.\n   *\n   * Only consulted on a full resynchronisation, and only to work out what to\n   * take away. Leave it out and a resync will add and update but never remove,\n   * which is a reasonable choice for a store where deletions are handled by\n   * hand — and a bad surprise if you expected otherwise, hence this note.\n   */\n  listMirroredIds?(): string[] | Promise<string[]>;\n}\n\nexport interface MirrorReport {\n  /** Ids written. */\n  upserted: string[];\n  /** Ids taken out. */\n  removed: string[];\n  /**\n   * Ids that could not be fetched, and are therefore neither.\n   *\n   * A rate limit, a five-hundred, a key revoked mid-run. They are reported\n   * rather than thrown so that the rest of the batch still lands — but an empty\n   * array is the only outcome that means \"this mirror is now correct\". Anything\n   * else wants a retry, and the ids to retry are right here.\n   */\n  failed: string[];\n  /** True when the whole catalogue was walked instead of the named ids. */\n  resynchronised: boolean;\n}\n\nexport interface CatalogueMirrorOptions {\n  client: CrmClient;\n  target: MirrorTarget;\n  /** How many products to ask for per page during a resync. */\n  pageSize?: number;\n}\n\nexport interface CatalogueMirror {\n  /** Act on one verified delivery. Events about other subjects do nothing. */\n  apply(payload: ApiWebhookPayload): Promise<MirrorReport>;\n  /** Walk the whole catalogue. Safe to run on a schedule or by hand. */\n  syncAll(): Promise<MirrorReport>;\n}\n\n/**\n * Keeps a local copy of the catalogue in step with the one over the wire.\n *\n * A delivery names ids and nothing else, on purpose, so this is where the\n * fetching happens — and that turns out to be the right place for three\n * decisions that are easy to get subtly wrong:\n *\n * - **A product that answers `null` is removed, not skipped.** The only events\n *   are \"changed\" and \"deleted\", and moving something back to draft is neither:\n *   it produces a `product.changed` for an id that then refuses to answer. A\n *   mirror that skips it keeps an unpublished product on the shop's shelves.\n * - **`truncated` means walk everything.** It is set when a burst of changes\n *   overflowed the batch, so the id list is a fragment and acting on only those\n *   ids would leave the rest quietly stale. The flag is read as `=== true`\n *   rather than for truthiness, because an older sender that omits it must not\n *   be read as \"the list is complete\".\n * - **Deliveries arrive more than once and out of order.** Both operations here\n *   are write-the-current-state rather than apply-a-difference, so a repeat\n *   costs a fetch and changes nothing, and a late message still lands on the\n *   present truth rather than on a stale snapshot.\n */\nexport function createCatalogueMirror(\n  options: CatalogueMirrorOptions,\n): CatalogueMirror {\n  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;\n\n  /**\n   * Fetches each id and writes what it finds, and does not let one bad id take\n   * the rest of the batch with it.\n   *\n   * `getProduct` answers `null` for something that is gone and throws for\n   * everything else — a rate limit, a five-hundred, a key that was revoked\n   * between two calls. Letting that throw escape would abort the loop partway\n   * with the ids already written thrown away, and the caller would learn only\n   * that \"it failed\": not which items landed, and not which one was the poison.\n   * A retry then starts from the top and starves everything after the bad id\n   * again, on every attempt, until the underlying fault clears.\n   *\n   * So a failure is collected rather than thrown, and it travels in the report.\n   * What the caller does about it is theirs to decide — but they can only\n   * decide if they are told.\n   */\n  async function pull(ids: readonly string[]) {\n    const upserted: string[] = [];\n    const removed: string[] = [];\n    const failed: string[] = [];\n\n    for (const id of ids) {\n      let product: ProductDetail | null;\n\n      try {\n        product = await options.client.getProduct(id);\n      } catch {\n        failed.push(id);\n\n        continue;\n      }\n\n      if (product === null) {\n        await options.target.remove({ id });\n        removed.push(id);\n\n        continue;\n      }\n\n      await options.target.upsert({ id, product });\n      upserted.push(id);\n    }\n\n    return { upserted, removed, failed };\n  }\n\n  /**\n   * Walks the whole catalogue, and refuses to pretend it did when it did not.\n   *\n   * The two guards below both stop the loop, and it matters a great deal that\n   * they stop it by throwing. A partial walk that returned normally would go on\n   * to the removal step with an incomplete `seen`, and take out every product\n   * past the point it stopped — reported as a successful resynchronisation. On\n   * a large catalogue that is most of a shop, deleted quietly, by the routine\n   * whose job is to keep it correct.\n   *\n   * A repeated cursor is the precise signature of the thing the ceiling was\n   * really there for: a listing that hands back the same position for ever.\n   * The ceiling stays as well, for the case where the cursor advances and the\n   * end never comes, and it is set where no real catalogue reaches it — it says\n   * \"something is wrong\", not \"this shop is too big\".\n   */\n  async function syncAll(): Promise<MirrorReport> {\n    const seen: string[] = [];\n    const positions = new Set<string>();\n\n    let cursor: string | null = null;\n\n    do {\n      const page = await options.client.getProducts({\n        limit: pageSize,\n        cursor,\n      });\n\n      for (const item of page.data) {\n        seen.push(item.id);\n      }\n\n      cursor = page.nextCursor;\n\n      if (cursor !== null) {\n        if (positions.has(cursor)) {\n          throw new Error(\n            'crm-client: the catalogue handed back a cursor it had already ' +\n              'given, so the walk is not advancing. Nothing was removed.',\n          );\n        }\n\n        positions.add(cursor);\n      }\n\n      if (seen.length > PRODUCT_CEILING) {\n        throw new Error(\n          `crm-client: more than ${PRODUCT_CEILING} products were walked ` +\n            'without reaching the end of the catalogue. Nothing was removed.',\n        );\n      }\n    } while (cursor);\n\n    const pulled = await pull(seen);\n    const removed = [...pulled.removed];\n\n    /*\n     * The removal step is skipped entirely when anything failed to fetch, for\n     * the same reason an unfinished walk throws: \"what the catalogue no longer\n     * has\" is worked out by subtracting what was seen from what is held, and a\n     * subtraction with a hole in the first set takes out live products. A\n     * mirror that is behind is a nuisance; a mirror that deleted half a shop\n     * because of a rate limit is not.\n     */\n    const held = pulled.failed.length\n      ? undefined\n      : await options.target.listMirroredIds?.();\n\n    if (held) {\n      const present = new Set(seen);\n\n      for (const id of held) {\n        if (!present.has(id)) {\n          await options.target.remove({ id });\n          removed.push(id);\n        }\n      }\n    }\n\n    return {\n      upserted: pulled.upserted,\n      removed,\n      failed: pulled.failed,\n      resynchronised: true,\n    };\n  }\n\n  return {\n    syncAll,\n\n    async apply(payload) {\n      if (!payload.type.startsWith('product.')) {\n        return { upserted: [], removed: [], failed: [], resynchronised: false };\n      }\n\n      if (payload.truncated === true) {\n        return syncAll();\n      }\n\n      if (payload.type === 'product.deleted') {\n        for (const id of payload.ids) {\n          await options.target.remove({ id });\n        }\n\n        /*\n         * Removed without fetching, and that is deliberate rather than an\n         * oversight of the \"always write current state\" rule the rest of this\n         * file follows. `product.deleted` fires on a real row deletion and ids\n         * are uuids, so the id in this message can never name something live\n         * again -- a fetch here could only ever answer `null` and then remove\n         * it anyway, at the cost of a request per id. Archiving something takes\n         * the other path: it is an update, so it arrives as `product.changed`,\n         * stops answering, and is removed by `pull` above.\n         */\n        return {\n          upserted: [],\n          removed: [...payload.ids],\n          failed: [],\n          resynchronised: false,\n        };\n      }\n\n      const pulled = await pull(payload.ids);\n\n      return { ...pulled, resynchronised: false };\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/mirror.d.ts

@@ -0,0 +1,95 @@
+import type { CrmClient } from './client';
+import type { ApiWebhookPayload, ProductDetail } from './types';
+/**
+ * Where a mirrored catalogue is kept, in whatever vocabulary that store uses.
+ *
+ * This is the one part a site has to write, and it is deliberately the only
+ * part. The shape of the local collection is not a detail this package could
+ * guess: a Payload shop built on the ecommerce plugin stores `title`,
+ * `priceInEUR` and a `gallery` of uploads, the catalogue here answers `name`,
+ * `priceFromCents` and `images` of URLs, and no mapping between the two is
+ * general — the next shop names them differently again, or keeps only three of
+ * them, or has no images at all.
+ *
+ * What *is* general is everything around it, and that is what this file owns:
+ * which ids a delivery actually changed, what to do when the id list came back
+ * truncated, and the fact that a product which has stopped answering has to be
+ * removed rather than skipped.
+ */
+export interface MirrorTarget {
+    /** Write it, whatever "it" looks like locally. Called once per product. */
+    upsert(input: {
+        id: string;
+        product: ProductDetail;
+    }): void | Promise<void>;
+    /**
+     * Take it out of the mirror.
+     *
+     * Called for a `product.deleted` delivery and, just as importantly, for a
+     * product that no longer answers — a seller who moved something back to draft
+     * produces no deletion event, because nothing was deleted.
+     */
+    remove(input: {
+        id: string;
+    }): void | Promise<void>;
+    /**
+     * Every id currently held in the mirror.
+     *
+     * Only consulted on a full resynchronisation, and only to work out what to
+     * take away. Leave it out and a resync will add and update but never remove,
+     * which is a reasonable choice for a store where deletions are handled by
+     * hand — and a bad surprise if you expected otherwise, hence this note.
+     */
+    listMirroredIds?(): string[] | Promise<string[]>;
+}
+export interface MirrorReport {
+    /** Ids written. */
+    upserted: string[];
+    /** Ids taken out. */
+    removed: string[];
+    /**
+     * Ids that could not be fetched, and are therefore neither.
+     *
+     * A rate limit, a five-hundred, a key revoked mid-run. They are reported
+     * rather than thrown so that the rest of the batch still lands — but an empty
+     * array is the only outcome that means "this mirror is now correct". Anything
+     * else wants a retry, and the ids to retry are right here.
+     */
+    failed: string[];
+    /** True when the whole catalogue was walked instead of the named ids. */
+    resynchronised: boolean;
+}
+export interface CatalogueMirrorOptions {
+    client: CrmClient;
+    target: MirrorTarget;
+    /** How many products to ask for per page during a resync. */
+    pageSize?: number;
+}
+export interface CatalogueMirror {
+    /** Act on one verified delivery. Events about other subjects do nothing. */
+    apply(payload: ApiWebhookPayload): Promise<MirrorReport>;
+    /** Walk the whole catalogue. Safe to run on a schedule or by hand. */
+    syncAll(): Promise<MirrorReport>;
+}
+/**
+ * Keeps a local copy of the catalogue in step with the one over the wire.
+ *
+ * A delivery names ids and nothing else, on purpose, so this is where the
+ * fetching happens — and that turns out to be the right place for three
+ * decisions that are easy to get subtly wrong:
+ *
+ * - **A product that answers `null` is removed, not skipped.** The only events
+ *   are "changed" and "deleted", and moving something back to draft is neither:
+ *   it produces a `product.changed` for an id that then refuses to answer. A
+ *   mirror that skips it keeps an unpublished product on the shop's shelves.
+ * - **`truncated` means walk everything.** It is set when a burst of changes
+ *   overflowed the batch, so the id list is a fragment and acting on only those
+ *   ids would leave the rest quietly stale. The flag is read as `=== true`
+ *   rather than for truthiness, because an older sender that omits it must not
+ *   be read as "the list is complete".
+ * - **Deliveries arrive more than once and out of order.** Both operations here
+ *   are write-the-current-state rather than apply-a-difference, so a repeat
+ *   costs a fetch and changes nothing, and a late message still lands on the
+ *   present truth rather than on a stale snapshot.
+ */
+export declare function createCatalogueMirror(options: CatalogueMirrorOptions): CatalogueMirror;

package/dist/mirror.js

@@ -0,0 +1,102 @@
+// src/mirror.ts
+var DEFAULT_PAGE_SIZE = 50;
+var PRODUCT_CEILING = 1e5;
+function createCatalogueMirror(options) {
+  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+  async function pull(ids) {
+    const upserted = [];
+    const removed = [];
+    const failed = [];
+    for (const id of ids) {
+      let product;
+      try {
+        product = await options.client.getProduct(id);
+      } catch {
+        failed.push(id);
+        continue;
+      }
+      if (product === null) {
+        await options.target.remove({ id });
+        removed.push(id);
+        continue;
+      }
+      await options.target.upsert({ id, product });
+      upserted.push(id);
+    }
+    return { upserted, removed, failed };
+  }
+  async function syncAll() {
+    const seen = [];
+    const positions = /* @__PURE__ */ new Set();
+    let cursor = null;
+    do {
+      const page = await options.client.getProducts({
+        limit: pageSize,
+        cursor
+      });
+      for (const item of page.data) {
+        seen.push(item.id);
+      }
+      cursor = page.nextCursor;
+      if (cursor !== null) {
+        if (positions.has(cursor)) {
+          throw new Error(
+            "crm-client: the catalogue handed back a cursor it had already given, so the walk is not advancing. Nothing was removed."
+          );
+        }
+        positions.add(cursor);
+      }
+      if (seen.length > PRODUCT_CEILING) {
+        throw new Error(
+          `crm-client: more than ${PRODUCT_CEILING} products were walked without reaching the end of the catalogue. Nothing was removed.`
+        );
+      }
+    } while (cursor);
+    const pulled = await pull(seen);
+    const removed = [...pulled.removed];
+    const held = pulled.failed.length ? void 0 : await options.target.listMirroredIds?.();
+    if (held) {
+      const present = new Set(seen);
+      for (const id of held) {
+        if (!present.has(id)) {
+          await options.target.remove({ id });
+          removed.push(id);
+        }
+      }
+    }
+    return {
+      upserted: pulled.upserted,
+      removed,
+      failed: pulled.failed,
+      resynchronised: true
+    };
+  }
+  return {
+    syncAll,
+    async apply(payload) {
+      if (!payload.type.startsWith("product.")) {
+        return { upserted: [], removed: [], failed: [], resynchronised: false };
+      }
+      if (payload.truncated === true) {
+        return syncAll();
+      }
+      if (payload.type === "product.deleted") {
+        for (const id of payload.ids) {
+          await options.target.remove({ id });
+        }
+        return {
+          upserted: [],
+          removed: [...payload.ids],
+          failed: [],
+          resynchronised: false
+        };
+      }
+      const pulled = await pull(payload.ids);
+      return { ...pulled, resynchronised: false };
+    }
+  };
+}
+export {
+  createCatalogueMirror
+};
+//# sourceMappingURL=mirror.js.map

package/dist/mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mirror.ts"],"sourcesContent":["import type { CrmClient } from './client';\nimport type { ApiWebhookPayload, ProductDetail } from './types';\n\nconst DEFAULT_PAGE_SIZE = 50;\n/**\n * Where a walk stops believing itself.\n *\n * Not a limit on how large a catalogue may be -- it is set far past any real\n * one on purpose. Reaching it means the listing is not ending, which is a fault\n * and not a big shop, and the difference decides what happens: a fault throws.\n */\nconst PRODUCT_CEILING = 100_000;\n\n/**\n * Where a mirrored catalogue is kept, in whatever vocabulary that store uses.\n *\n * This is the one part a site has to write, and it is deliberately the only\n * part. The shape of the local collection is not a detail this package could\n * guess: a Payload shop built on the ecommerce plugin stores `title`,\n * `priceInEUR` and a `gallery` of uploads, the catalogue here answers `name`,\n * `priceFromCents` and `images` of URLs, and no mapping between the two is\n * general — the next shop names them differently again, or keeps only three of\n * them, or has no images at all.\n *\n * What *is* general is everything around it, and that is what this file owns:\n * which ids a delivery actually changed, what to do when the id list came back\n * truncated, and the fact that a product which has stopped answering has to be\n * removed rather than skipped.\n */\nexport interface MirrorTarget {\n  /** Write it, whatever \"it\" looks like locally. Called once per product. */\n  upsert(input: { id: string; product: ProductDetail }): void | Promise<void>;\n  /**\n   * Take it out of the mirror.\n   *\n   * Called for a `product.deleted` delivery and, just as importantly, for a\n   * product that no longer answers — a seller who moved something back to draft\n   * produces no deletion event, because nothing was deleted.\n   */\n  remove(input: { id: string }): void | Promise<void>;\n  /**\n   * Every id currently held in the mirror.\n   *\n   * Only consulted on a full resynchronisation, and only to work out what to\n   * take away. Leave it out and a resync will add and update but never remove,\n   * which is a reasonable choice for a store where deletions are handled by\n   * hand — and a bad surprise if you expected otherwise, hence this note.\n   */\n  listMirroredIds?(): string[] | Promise<string[]>;\n}\n\nexport interface MirrorReport {\n  /** Ids written. */\n  upserted: string[];\n  /** Ids taken out. */\n  removed: string[];\n  /**\n   * Ids that could not be fetched, and are therefore neither.\n   *\n   * A rate limit, a five-hundred, a key revoked mid-run. They are reported\n   * rather than thrown so that the rest of the batch still lands — but an empty\n   * array is the only outcome that means \"this mirror is now correct\". Anything\n   * else wants a retry, and the ids to retry are right here.\n   */\n  failed: string[];\n  /** True when the whole catalogue was walked instead of the named ids. */\n  resynchronised: boolean;\n}\n\nexport interface CatalogueMirrorOptions {\n  client: CrmClient;\n  target: MirrorTarget;\n  /** How many products to ask for per page during a resync. */\n  pageSize?: number;\n}\n\nexport interface CatalogueMirror {\n  /** Act on one verified delivery. Events about other subjects do nothing. */\n  apply(payload: ApiWebhookPayload): Promise<MirrorReport>;\n  /** Walk the whole catalogue. Safe to run on a schedule or by hand. */\n  syncAll(): Promise<MirrorReport>;\n}\n\n/**\n * Keeps a local copy of the catalogue in step with the one over the wire.\n *\n * A delivery names ids and nothing else, on purpose, so this is where the\n * fetching happens — and that turns out to be the right place for three\n * decisions that are easy to get subtly wrong:\n *\n * - **A product that answers `null` is removed, not skipped.** The only events\n *   are \"changed\" and \"deleted\", and moving something back to draft is neither:\n *   it produces a `product.changed` for an id that then refuses to answer. A\n *   mirror that skips it keeps an unpublished product on the shop's shelves.\n * - **`truncated` means walk everything.** It is set when a burst of changes\n *   overflowed the batch, so the id list is a fragment and acting on only those\n *   ids would leave the rest quietly stale. The flag is read as `=== true`\n *   rather than for truthiness, because an older sender that omits it must not\n *   be read as \"the list is complete\".\n * - **Deliveries arrive more than once and out of order.** Both operations here\n *   are write-the-current-state rather than apply-a-difference, so a repeat\n *   costs a fetch and changes nothing, and a late message still lands on the\n *   present truth rather than on a stale snapshot.\n */\nexport function createCatalogueMirror(\n  options: CatalogueMirrorOptions,\n): CatalogueMirror {\n  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;\n\n  /**\n   * Fetches each id and writes what it finds, and does not let one bad id take\n   * the rest of the batch with it.\n   *\n   * `getProduct` answers `null` for something that is gone and throws for\n   * everything else — a rate limit, a five-hundred, a key that was revoked\n   * between two calls. Letting that throw escape would abort the loop partway\n   * with the ids already written thrown away, and the caller would learn only\n   * that \"it failed\": not which items landed, and not which one was the poison.\n   * A retry then starts from the top and starves everything after the bad id\n   * again, on every attempt, until the underlying fault clears.\n   *\n   * So a failure is collected rather than thrown, and it travels in the report.\n   * What the caller does about it is theirs to decide — but they can only\n   * decide if they are told.\n   */\n  async function pull(ids: readonly string[]) {\n    const upserted: string[] = [];\n    const removed: string[] = [];\n    const failed: string[] = [];\n\n    for (const id of ids) {\n      let product: ProductDetail | null;\n\n      try {\n        product = await options.client.getProduct(id);\n      } catch {\n        failed.push(id);\n\n        continue;\n      }\n\n      if (product === null) {\n        await options.target.remove({ id });\n        removed.push(id);\n\n        continue;\n      }\n\n      await options.target.upsert({ id, product });\n      upserted.push(id);\n    }\n\n    return { upserted, removed, failed };\n  }\n\n  /**\n   * Walks the whole catalogue, and refuses to pretend it did when it did not.\n   *\n   * The two guards below both stop the loop, and it matters a great deal that\n   * they stop it by throwing. A partial walk that returned normally would go on\n   * to the removal step with an incomplete `seen`, and take out every product\n   * past the point it stopped — reported as a successful resynchronisation. On\n   * a large catalogue that is most of a shop, deleted quietly, by the routine\n   * whose job is to keep it correct.\n   *\n   * A repeated cursor is the precise signature of the thing the ceiling was\n   * really there for: a listing that hands back the same position for ever.\n   * The ceiling stays as well, for the case where the cursor advances and the\n   * end never comes, and it is set where no real catalogue reaches it — it says\n   * \"something is wrong\", not \"this shop is too big\".\n   */\n  async function syncAll(): Promise<MirrorReport> {\n    const seen: string[] = [];\n    const positions = new Set<string>();\n\n    let cursor: string | null = null;\n\n    do {\n      const page = await options.client.getProducts({\n        limit: pageSize,\n        cursor,\n      });\n\n      for (const item of page.data) {\n        seen.push(item.id);\n      }\n\n      cursor = page.nextCursor;\n\n      if (cursor !== null) {\n        if (positions.has(cursor)) {\n          throw new Error(\n            'crm-client: the catalogue handed back a cursor it had already ' +\n              'given, so the walk is not advancing. Nothing was removed.',\n          );\n        }\n\n        positions.add(cursor);\n      }\n\n      if (seen.length > PRODUCT_CEILING) {\n        throw new Error(\n          `crm-client: more than ${PRODUCT_CEILING} products were walked ` +\n            'without reaching the end of the catalogue. Nothing was removed.',\n        );\n      }\n    } while (cursor);\n\n    const pulled = await pull(seen);\n    const removed = [...pulled.removed];\n\n    /*\n     * The removal step is skipped entirely when anything failed to fetch, for\n     * the same reason an unfinished walk throws: \"what the catalogue no longer\n     * has\" is worked out by subtracting what was seen from what is held, and a\n     * subtraction with a hole in the first set takes out live products. A\n     * mirror that is behind is a nuisance; a mirror that deleted half a shop\n     * because of a rate limit is not.\n     */\n    const held = pulled.failed.length\n      ? undefined\n      : await options.target.listMirroredIds?.();\n\n    if (held) {\n      const present = new Set(seen);\n\n      for (const id of held) {\n        if (!present.has(id)) {\n          await options.target.remove({ id });\n          removed.push(id);\n        }\n      }\n    }\n\n    return {\n      upserted: pulled.upserted,\n      removed,\n      failed: pulled.failed,\n      resynchronised: true,\n    };\n  }\n\n  return {\n    syncAll,\n\n    async apply(payload) {\n      if (!payload.type.startsWith('product.')) {\n        return { upserted: [], removed: [], failed: [], resynchronised: false };\n      }\n\n      if (payload.truncated === true) {\n        return syncAll();\n      }\n\n      if (payload.type === 'product.deleted') {\n        for (const id of payload.ids) {\n          await options.target.remove({ id });\n        }\n\n        /*\n         * Removed without fetching, and that is deliberate rather than an\n         * oversight of the \"always write current state\" rule the rest of this\n         * file follows. `product.deleted` fires on a real row deletion and ids\n         * are uuids, so the id in this message can never name something live\n         * again -- a fetch here could only ever answer `null` and then remove\n         * it anyway, at the cost of a request per id. Archiving something takes\n         * the other path: it is an update, so it arrives as `product.changed`,\n         * stops answering, and is removed by `pull` above.\n         */\n        return {\n          upserted: [],\n          removed: [...payload.ids],\n          failed: [],\n          resynchronised: false,\n        };\n      }\n\n      const pulled = await pull(payload.ids);\n\n      return { ...pulled, resynchronised: false };\n    },\n  };\n}\n"],"mappings":";AAGA,IAAM,oBAAoB;AAQ1B,IAAM,kBAAkB;AA6FjB,SAAS,sBACd,SACiB;AACjB,QAAM,WAAW,QAAQ,YAAY;AAkBrC,iBAAe,KAAK,KAAwB;AAC1C,UAAM,WAAqB,CAAC;AAC5B,UAAM,UAAoB,CAAC;AAC3B,UAAM,SAAmB,CAAC;AAE1B,eAAW,MAAM,KAAK;AACpB,UAAI;AAEJ,UAAI;AACF,kBAAU,MAAM,QAAQ,OAAO,WAAW,EAAE;AAAA,MAC9C,QAAQ;AACN,eAAO,KAAK,EAAE;AAEd;AAAA,MACF;AAEA,UAAI,YAAY,MAAM;AACpB,cAAM,QAAQ,OAAO,OAAO,EAAE,GAAG,CAAC;AAClC,gBAAQ,KAAK,EAAE;AAEf;AAAA,MACF;AAEA,YAAM,QAAQ,OAAO,OAAO,EAAE,IAAI,QAAQ,CAAC;AAC3C,eAAS,KAAK,EAAE;AAAA,IAClB;AAEA,WAAO,EAAE,UAAU,SAAS,OAAO;AAAA,EACrC;AAkBA,iBAAe,UAAiC;AAC9C,UAAM,OAAiB,CAAC;AACxB,UAAM,YAAY,oBAAI,IAAY;AAElC,QAAI,SAAwB;AAE5B,OAAG;AACD,YAAM,OAAO,MAAM,QAAQ,OAAO,YAAY;AAAA,QAC5C,OAAO;AAAA,QACP;AAAA,MACF,CAAC;AAED,iBAAW,QAAQ,KAAK,MAAM;AAC5B,aAAK,KAAK,KAAK,EAAE;AAAA,MACnB;AAEA,eAAS,KAAK;AAEd,UAAI,WAAW,MAAM;AACnB,YAAI,UAAU,IAAI,MAAM,GAAG;AACzB,gBAAM,IAAI;AAAA,YACR;AAAA,UAEF;AAAA,QACF;AAEA,kBAAU,IAAI,MAAM;AAAA,MACtB;AAEA,UAAI,KAAK,SAAS,iBAAiB;AACjC,cAAM,IAAI;AAAA,UACR,yBAAyB,eAAe;AAAA,QAE1C;AAAA,MACF;AAAA,IACF,SAAS;AAET,UAAM,SAAS,MAAM,KAAK,IAAI;AAC9B,UAAM,UAAU,CAAC,GAAG,OAAO,OAAO;AAUlC,UAAM,OAAO,OAAO,OAAO,SACvB,SACA,MAAM,QAAQ,OAAO,kBAAkB;AAE3C,QAAI,MAAM;AACR,YAAM,UAAU,IAAI,IAAI,IAAI;AAE5B,iBAAW,MAAM,MAAM;AACrB,YAAI,CAAC,QAAQ,IAAI,EAAE,GAAG;AACpB,gBAAM,QAAQ,OAAO,OAAO,EAAE,GAAG,CAAC;AAClC,kBAAQ,KAAK,EAAE;AAAA,QACjB;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,MACL,UAAU,OAAO;AAAA,MACjB;AAAA,MACA,QAAQ,OAAO;AAAA,MACf,gBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IAEA,MAAM,MAAM,SAAS;AACnB,UAAI,CAAC,QAAQ,KAAK,WAAW,UAAU,GAAG;AACxC,eAAO,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC,GAAG,QAAQ,CAAC,GAAG,gBAAgB,MAAM;AAAA,MACxE;AAEA,UAAI,QAAQ,cAAc,MAAM;AAC9B,eAAO,QAAQ;AAAA,MACjB;AAEA,UAAI,QAAQ,SAAS,mBAAmB;AACtC,mBAAW,MAAM,QAAQ,KAAK;AAC5B,gBAAM,QAAQ,OAAO,OAAO,EAAE,GAAG,CAAC;AAAA,QACpC;AAYA,eAAO;AAAA,UACL,UAAU,CAAC;AAAA,UACX,SAAS,CAAC,GAAG,QAAQ,GAAG;AAAA,UACxB,QAAQ,CAAC;AAAA,UACT,gBAAgB;AAAA,QAClB;AAAA,MACF;AAEA,YAAM,SAAS,MAAM,KAAK,QAAQ,GAAG;AAErC,aAAO,EAAE,GAAG,QAAQ,gBAAgB,MAAM;AAAA,IAC5C;AAAA,EACF;AACF;","names":[]}

package/dist/refusal.d.ts

@@ -0,0 +1,18 @@
+import { CrmApiError } from './errors';
+export declare function readJson(response: Response): Promise<unknown>;
+/**
+ * A refusal, whatever shape it arrived in.
+ *
+ * Almost everything answers `{ error: { code, message } }`, and then the code
+ * is taken at its word — it is a closed set this package generates from the
+ * server's own list, so a code that does not appear here means the two have
+ * drifted and a build somewhere should already have gone red.
+ *
+ * The events listing is the exception: it answers `{ error: "..." }`, because
+ * it predates the shared error helper and is read by script tags on sites
+ * nobody here can redeploy. For that one the status code is all there is, and
+ * the one place it cannot be precise is 403, where "your key lacks this scope"
+ * and "that module is switched off for this account" share a number. It is
+ * reported as `forbidden`, the one of the two a developer can act on.
+ */
+export declare function refusalOf(status: number, body: unknown, requestUrl: string): CrmApiError;

package/dist/tags.d.ts

@@ -0,0 +1,18 @@
+/** Everything that lists products. Cleared by every catalogue delivery. */
+export declare function productsTag(): string;
+/** One product, by whichever key it was fetched with. */
+export declare function productTag(slugOrId: string): string;
+export declare function eventsTag(): string;
+export declare function eventTag(idOrSlug: string): string;
+/**
+ * What a delivery of this type should clear.
+ *
+ * `truncated` means the batch stopped collecting and `ids` is incomplete, so
+ * the only honest answer is the whole collection — which the collection tag
+ * already is. The per-item tags are added on top when the list can be trusted.
+ */
+export declare function tagsForDelivery(input: {
+    type: string;
+    ids: readonly string[];
+    truncated: boolean;
+}): string[];

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+import type { ApiErrorCode, PublicEventDetailItem, PublicEventListItem, PublicProductDetail, PublicProductImage, PublicProductListItem } from './generated/api-types';
+export type { ApiErrorCode, ApiScope, ApiWebhookEvent, ApiWebhookPayload, PublicProductCategory, PublicProductPrice, PublicProductSummary, } from './generated/api-types';
+export { ALL_API_ERROR_CODES, ALL_API_SCOPES, ALL_API_WEBHOOK_EVENTS, } from './generated/api-types';
+/**
+ * The difference between what the projection holds and what goes over the wire.
+ *
+ * The services store a storage *path* for every image, because only the route
+ * knows which origin its own storage is served from — so the route swaps the
+ * path for a finished URL on the way out. These three types are that swap,
+ * written as a subtraction from the generated shape rather than as a fresh
+ * list, so a field added to the projection lands here without anybody noticing
+ * it had to.
+ */
+export interface ProductListItem extends Omit<PublicProductListItem, 'imagePath'> {
+    /** Ready to put in an `<img>`; null when the seller uploaded no picture. */
+    imageUrl: string | null;
+}
+export interface ProductDetail extends Omit<PublicProductDetail, 'imagePath' | 'images'> {
+    imageUrl: string | null;
+    images: ProductImage[];
+}
+export interface ProductImage extends Omit<PublicProductImage, 'path'> {
+    url: string;
+}
+export interface EventListItem extends Omit<PublicEventListItem, 'coverImagePath'> {
+    coverImageUrl: string | null;
+}
+export interface EventDetail extends Omit<PublicEventDetailItem, 'coverImagePath' | 'url'> {
+    coverImageUrl: string | null;
+    /** Null when the event has no page on the hosted site to point at. */
+    url: string | null;
+}
+/** What a listing answers: a page of items and the way to ask for the next. */
+export interface ProductList {
+    data: ProductListItem[];
+    /** Null on the last page. Pass it back as `cursor` for the one after this. */
+    nextCursor: string | null;
+}
+/**
+ * The events listing, which does not have the shape of the others.
+ *
+ * It answered `{ account, events, nextCursor }` years before this API had a key
+ * or a convention, and script tags on sites nobody here can redeploy read those
+ * exact names. Renaming them to match would break every one of them at once, so
+ * the older shape stays and this type says so out loud rather than hiding the
+ * difference behind a translation.
+ */
+export interface EventList {
+    account: {
+        name: string;
+        slug: string;
+    } | null;
+    events: EventListItem[];
+    nextCursor: string | null;
+}
+/** Whether a visitor can buy it right now. Never how many are left. */
+export interface StockStatus {
+    id: string;
+    slug: string;
+    inStock: boolean;
+}
+/** Seats, live. `remaining` is null when the evening has no ceiling. */
+export interface EventAvailability {
+    eventId: string;
+    remaining: number | null;
+    soldOut: boolean;
+    ticketTypes: {
+        id: string;
+        remaining: number | null;
+        soldOut: boolean;
+    }[];
+}
+export interface OrderBuyer {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    company?: string;
+    vatNumber?: string;
+}
+export interface OrderAddress {
+    line1?: string;
+    line2?: string;
+    postalCode?: string;
+    city?: string;
+    /** Two letters, ISO 3166-1 alpha-2. */
+    countryCode?: string;
+}
+/**
+ * One thing being bought.
+ *
+ * Name either the product or one of its price options, and a quantity. There is
+ * deliberately no amount here and none is accepted: the total is worked out on
+ * the server from the seller's own price rows. A shop where the browser may
+ * state the price is a shop where the customer types it.
+ */
+export interface OrderLine {
+    productId?: string;
+    priceId?: string;
+    quantity?: number;
+}
+export interface OrderInput {
+    buyer: OrderBuyer;
+    lines: OrderLine[];
+    address?: OrderAddress;
+}
+export interface OrderResult {
+    id: string;
+    number: string;
+    status: string;
+    currency: string;
+    subtotalCents: number;
+    taxCents: number;
+    totalCents: number;
+    contactId: string;
+    /**
+     * What to hand the payment sheet.
+     *
+     * `stripeAccount` is the seller's own connected account — the shop's checkout
+     * has to be initialised against it, or the intent will not be found.
+     */
+    payment: {
+        kind: string;
+        clientSecret: string;
+        stripeAccount: string;
+        amountCents: number;
+    };
+}
+export interface ContactInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    company?: string;
+}
+export interface ContactResult {
+    id: string;
+    /** False when the address matched somebody already known. */
+    created: boolean;
+}
+export interface RequestInput {
+    contact: ContactInput;
+    message: string;
+    productId?: string;
+    source?: string;
+}
+export interface RequestResult {
+    id: string;
+    contactId: string;
+    contactCreated: boolean;
+}
+export interface FormSubmissionInput {
+    fields: Record<string, unknown>;
+    sourceUrl?: string;
+}
+export interface FormSubmissionResult {
+    id: string | null;
+    duplicate: boolean;
+    status: string | null;
+    contactId: string | null;
+}
+/** The body of every refusal. `fields` is present only on a schema complaint. */
+export interface ApiErrorBody {
+    error: {
+        code: ApiErrorCode;
+        message: string;
+        fields?: {
+            path: string;
+            message: string;
+        }[];
+    };
+}