@solumflow-app/crm-client 0.1.0

package/dist/generated/api-types.d.ts

@@ -0,0 +1,265 @@
+/** What a key is allowed to reach. A key carries one or more of these. */
+export type ApiScope = 'catalog:read' | 'events:read' | 'orders:write' | 'contacts:write' | 'forms:write';
+export declare const ALL_API_SCOPES: readonly ApiScope[];
+/** Everything an endpoint can be told about. A delivery names one. */
+export type ApiWebhookEvent = 'product.changed' | 'product.deleted' | 'event.changed' | 'order.status_changed';
+export declare const ALL_API_WEBHOOK_EVENTS: readonly ApiWebhookEvent[];
+/** The `error.code` of a refusal. Match on this, never on the message -- the message is written for a person reading a log and may be reworded. */
+export type ApiErrorCode = 'unauthorized' | 'forbidden' | 'feature_unavailable' | 'not_found' | 'invalid_request' | 'idempotency_key_reused' | 'request_in_progress' | 'rate_limited' | 'internal_error';
+export declare const ALL_API_ERROR_CODES: readonly ApiErrorCode[];
+/**
+ * One product as a stranger's website sees it.
+ *
+ * These interfaces are the public API's contract, not internal convenience
+ * types. They are served cross-origin to pages nobody here controls, and a
+ * customer's shop reads these exact keys — so a field removed or renamed breaks
+ * a site that will not be redeployed. Add fields; do not repurpose them.
+ *
+ * What is deliberately absent is as much the contract as what is here.
+ *
+ * - **`sku`** is the number this business uses to find the thing in its own
+ *   stockroom. It says how many suppliers there are, which one a line came
+ *   from, and often what was paid. `gtin` is the number printed on the box and
+ *   is offered instead, in the detail: that one is meant to be public, and a
+ *   shop needs it for a product feed.
+ * - **The stock count** never leaves. `inStock` answers the only question a
+ *   visitor has, and the number itself is a business fact a competitor would
+ *   like and a cached answer would get wrong within the minute.
+ * - **`unit_price_cents` raw** is not it either; see `priceFromCents`.
+ * - **Non-public custom fields.** `fields` carries only attributes a member
+ *   marked `is_public`, which defaults to off. A field called "purchase price"
+ *   stays home unless somebody says otherwise, once, per field.
+ *
+ * And one field that an event has and a product does not: **`url`**. An event
+ * is sold on a page this system hosts, so its listing can hand out a link. A
+ * product is sold on the customer's own site — that is the entire reason this
+ * API exists — and this system does not know what they called their product
+ * page. A guessed link is worse than none.
+ */
+export interface PublicProductListItem {
+    id: string;
+    /** Always present: a product without an address cannot be published. */
+    slug: string;
+    name: string;
+    productType: 'digital' | 'physical';
+    /**
+     * The storage path, not a URL. The route turns it into a public URL, because
+     * only the route knows the origin its own storage is served from.
+     */
+    imagePath: string | null;
+    /**
+     * The cheapest way in, over the active price options — not the default one.
+     * A card that says "from €12" next to a product whose entry price is €12 and
+     * whose default is the €40 yearly plan is answering the question the visitor
+     * actually asked.
+     *
+     * Never null, unlike the same field on an event. An event without a ticket
+     * tier on sale genuinely has no price; a product always has `unit_price_cents`
+     * on its own row, so when no separate price option is active that column is
+     * the answer — including when it is `0`, which is a real price for something
+     * given away.
+     */
+    priceFromCents: number;
+    /** The struck-through price beside it, when the seller set one. */
+    compareAtCents: number | null;
+    currency: string;
+    /**
+     * Whether a visitor can buy it right now — never how many are left.
+     *
+     * True whenever the seller does not track stock at all, which is the common
+     * case and the honest answer for anything made to order. When they do track
+     * it, this counts what is on the shelf minus what other people already hold
+     * in a checkout, and it stays true for a seller who accepts backorders.
+     */
+    inStock: boolean;
+    /**
+     * The custom fields this account invented, keyed by the slug they chose, and
+     * only the ones marked public. An empty object when none are.
+     */
+    fields: Record<string, unknown>;
+}
+/**
+ * The same product on its own page, where more may be shown.
+ *
+ * The detail answers for things the listing hides — an unlisted product, one
+ * reachable by anyone holding the link — for the same reason the events detail
+ * answers for a cancelled evening: somebody was sent here on purpose, and a 404
+ * would be a lie. What it still refuses is anything unpublished.
+ */
+export interface PublicProductDetail extends PublicProductListItem {
+    /** The one-line text that lands on a quote or an invoice row. */
+    description: string | null;
+    /** The long story, as sanitised HTML. Written by the seller, for this page. */
+    longDescription: string | null;
+    /** The barcode number: printed on the box, wanted by every product feed. */
+    gtin: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    images: PublicProductImage[];
+    prices: PublicProductPrice[];
+    categories: PublicProductCategory[];
+    /** What the seller linked this to — a companion, a refill, a bigger model. */
+    related: PublicProductSummary[];
+}
+export interface PublicProductImage {
+    /** A path, turned into a URL by the route. Same reason as `imagePath`. */
+    path: string;
+    alt: string | null;
+}
+/**
+ * One way to buy the thing.
+ *
+ * `stripe_price_id` and `stripe_account_id` are absent and must stay absent:
+ * they name objects in the seller's payment account, and a checkout is started
+ * through this system's own order route, never by a stranger quoting an id.
+ */
+export interface PublicProductPrice {
+    id: string;
+    kind: 'one_off' | 'recurring' | 'installment';
+    label: string | null;
+    amountCents: number;
+    /** What the whole thing costs when paid in parts; null for the other kinds. */
+    totalCents: number | null;
+    installmentCount: number | null;
+    recurringInterval: 'day' | 'week' | 'month' | 'year' | null;
+    recurringIntervalCount: number | null;
+    compareAtCents: number | null;
+    trialPeriodDays: number | null;
+    isDefault: boolean;
+}
+export interface PublicProductCategory {
+    id: string;
+    name: string;
+}
+export interface PublicProductSummary {
+    id: string;
+    slug: string;
+    name: string;
+}
+/**
+ * One event as a stranger's website sees it.
+ *
+ * This interface is the public API's contract, not an internal convenience
+ * type. It is served cross-origin to pages nobody here controls, and a widget
+ * on a customer's homepage reads these exact keys — so a field removed or
+ * renamed breaks a site that will not be redeployed. Add fields; do not
+ * repurpose them.
+ *
+ * What is deliberately absent is as much the contract as what is here: no
+ * description (a paragraph no card renders), no joining link (that is
+ * admission), no counts of who bought what, and nothing an organiser uses to
+ * manage the event.
+ */
+export interface PublicEventListItem {
+    id: string;
+    slug: string;
+    title: string;
+    subtitle: string | null;
+    startsAt: string;
+    endsAt: string | null;
+    timezone: string;
+    locationName: string | null;
+    /**
+     * The storage path, not a URL. The route turns it into a public URL, because
+     * only the route knows the origin its own storage is served from.
+     */
+    coverImagePath: string | null;
+    /** Null when nothing is on sale — never 0, which is a real price. */
+    priceFromCents: number | null;
+    currency: string | null;
+    soldOut: boolean;
+    /** Null when the event has no ceiling to count down from. */
+    seatsLeft: number | null;
+    /** Path on the hosted site, so a widget can link straight to checkout. */
+    url: string;
+    /**
+     * The custom fields this account invented, keyed by the slug they chose, and
+     * only the ones marked public. An empty object when none are, which is every
+     * account until somebody turns one on.
+     *
+     * Added rather than repurposed, which is the rule this interface states at
+     * the top: a widget written before this field existed keeps working, because
+     * it simply never reads the key.
+     */
+    fields: Record<string, unknown>;
+}
+/**
+ * One event as the public API hands it out, on its own page.
+ *
+ * Not the same thing as `PublicEventView`, which feeds the detail page this
+ * system hosts — and the difference is the reason this type exists rather than
+ * the other one being reused. That view carries `online_url`: the link you join
+ * the evening by. On a page we host, behind a ticket, that is correct. Through
+ * an API that answers any holder of a read key, it is a free seat.
+ *
+ * It also carries `account_id`, which is ours and not the caller's business.
+ *
+ * So this is a separate, narrower projection, and everything in
+ * `PublicEventListItem` about adding rather than repurposing fields applies
+ * here too.
+ */
+export interface PublicEventDetailItem extends PublicEventListItem {
+    /** The organiser's own text for the evening. */
+    description: string | null;
+    /**
+     * `on_sale`, `closed` or `cancelled` — never `draft`, which does not answer
+     * at all. A ticket holder has to be able to read that the evening is off, so
+     * this route replies for the last two where the listing withholds them.
+     */
+    status: 'on_sale' | 'closed' | 'cancelled';
+    doorsOpenAt: string | null;
+    salesStartAt: string | null;
+    salesEndAt: string | null;
+    /** The postal address, as the organiser entered it. */
+    address: unknown;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    ticketTypes: PublicEventTicketType[];
+    /** Custom fields the account marked public, keyed by their own slug. */
+    fields: Record<string, unknown>;
+}
+/**
+ * One way in, as a stranger's page may show it.
+ *
+ * `reserved_count` and `sold_count` are absent: how many were sold is the
+ * organiser's figure, and `seatsLeft` already answers the only question a
+ * visitor has. The capacity behind it stays home for the same reason a stock
+ * count does.
+ */
+export interface PublicEventTicketType {
+    id: string;
+    name: string;
+    description: string | null;
+    priceCents: number;
+    currency: string;
+    taxPercentage: number | null;
+    minPerOrder: number | null;
+    maxPerOrder: number | null;
+    salesStartAt: string | null;
+    salesEndAt: string | null;
+    /** Null when this tier has no ceiling to count down from. */
+    seatsLeft: number | null;
+    soldOut: boolean;
+    onSale: boolean;
+}
+/**
+ * The body of one delivery.
+ *
+ * IDS AND NOTHING ELSE, and the three reasons are worth keeping together. A
+ * message that arrives late still leads to the right state, because the
+ * receiver fetches the current row rather than trusting a snapshot from twenty
+ * minutes ago. A message can never hand out something the receiving key was
+ * not allowed to read, because it hands out nothing. And five hundred changes
+ * fit in a body of a few kilobytes instead of a few megabytes.
+ *
+ * `truncated` means the batch stopped collecting at its ceiling and `ids` is
+ * therefore incomplete: the receiver should refetch the whole collection. It
+ * is always present rather than only when true, so a receiver that reads it
+ * cannot mistake "absent" for "false" in the one direction that matters.
+ */
+export interface ApiWebhookPayload {
+    type: ApiWebhookEvent;
+    occurredAt: string;
+    ids: string[];
+    truncated: boolean;
+}

package/dist/index.cjs

@@ -0,0 +1,381 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ALL_API_ERROR_CODES: () => ALL_API_ERROR_CODES,
+  ALL_API_SCOPES: () => ALL_API_SCOPES,
+  ALL_API_WEBHOOK_EVENTS: () => ALL_API_WEBHOOK_EVENTS,
+  CrmApiError: () => CrmApiError,
+  createClient: () => createClient,
+  eventTag: () => eventTag,
+  eventsTag: () => eventsTag,
+  productTag: () => productTag,
+  productsTag: () => productsTag,
+  tagsForDelivery: () => tagsForDelivery
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var CrmApiError = class extends Error {
+  constructor(input) {
+    super(input.message);
+    this.name = "CrmApiError";
+    this.code = input.code;
+    this.status = input.status;
+    this.fields = input.fields ?? [];
+    this.requestUrl = input.requestUrl;
+  }
+  /**
+   * Whether trying the same request again could plausibly work.
+   *
+   * A rate limit clears and a server error may be a blip; a rejected key and a
+   * malformed body will be refused just as firmly the second time. Write
+   * requests should be retried with the *same* idempotency key, which this
+   * client fills in for you, so a retry after a timeout cannot become a second
+   * order.
+   */
+  get retryable() {
+    return this.code === "rate_limited" || this.code === "internal_error";
+  }
+};
+
+// src/refusal.ts
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+function refusalOf(status, body, requestUrl) {
+  const structured = body?.error;
+  if (structured && typeof structured === "object" && structured.code) {
+    return new CrmApiError({
+      code: structured.code,
+      message: structured.message ?? structured.code,
+      status,
+      fields: structured.fields ?? [],
+      requestUrl
+    });
+  }
+  const plain = body?.error;
+  return new CrmApiError({
+    code: codeForStatus(status),
+    message: typeof plain === "string" ? plain : `The request failed with ${status}.`,
+    status,
+    requestUrl
+  });
+}
+function codeForStatus(status) {
+  switch (status) {
+    case 400:
+      return "invalid_request";
+    case 401:
+      return "unauthorized";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 409:
+      return "request_in_progress";
+    case 429:
+      return "rate_limited";
+    default:
+      return "internal_error";
+  }
+}
+
+// src/tags.ts
+var PREFIX = "crm";
+function productsTag() {
+  return `${PREFIX}:products`;
+}
+function productTag(slugOrId) {
+  return `${PREFIX}:product:${slugOrId}`;
+}
+function eventsTag() {
+  return `${PREFIX}:events`;
+}
+function eventTag(idOrSlug) {
+  return `${PREFIX}:event:${idOrSlug}`;
+}
+function tagsForDelivery(input) {
+  const collection = input.type.startsWith("product.") ? productsTag() : input.type.startsWith("event.") ? eventsTag() : null;
+  if (collection === null) {
+    return [];
+  }
+  if (input.truncated) {
+    return [collection];
+  }
+  const item = input.type.startsWith("product.") ? productTag : eventTag;
+  return [collection, ...input.ids.map((id) => item(id))];
+}
+
+// src/client.ts
+var KEY_FORM = /^crm[ps]_[A-Za-z0-9_-]{43}$/;
+var SECRET_PREFIX = "crms_";
+var BASE_PATH = "/api/public/v1";
+var DEFAULT_REVALIDATE = 60;
+function createClient(options) {
+  const apiKey = options.apiKey?.trim() ?? "";
+  if (!KEY_FORM.test(apiKey)) {
+    throw new Error(
+      "crm-client: the API key is not in the expected form. It starts with `crmp_` or `crms_` and is 48 characters long \u2014 a truncated paste looks exactly like a revoked key once it reaches the server."
+    );
+  }
+  if (apiKey.startsWith(SECRET_PREFIX) && inSomethingTheUserCanRead()) {
+    throw new Error(
+      "crm-client: a `crms_` key may not be used in a browser. It can write orders and read contacts, and anything a browser holds is public \u2014 including a service worker or a web worker, which is why this is refused there too. Read from a server component or a route handler, or issue a `crmp_` key for the parts of the catalogue a page reads directly."
+    );
+  }
+  const base = options.baseUrl?.replace(/\/+$/, "") ?? "";
+  if (!/^https?:\/\/[^/]+$/.test(base)) {
+    throw new Error(
+      `crm-client: baseUrl should be an origin and nothing more, such as "https://app.example.com". Received "${options.baseUrl}".`
+    );
+  }
+  const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+  const revalidate = options.revalidate ?? DEFAULT_REVALIDATE;
+  async function send(path, init, unwrap, notFoundIsNull) {
+    const url = `${base}${BASE_PATH}${path}`;
+    const response = await doFetch(url, {
+      ...init,
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${apiKey}`,
+        ...init.headers
+      }
+    });
+    const body = await readJson(response);
+    if (!response.ok) {
+      const refusal = refusalOf(response.status, body, url);
+      if (notFoundIsNull && refusal.code === "not_found") {
+        return null;
+      }
+      throw refusal;
+    }
+    const answer = unwrap(body);
+    if (answer === void 0 || answer === null) {
+      throw new CrmApiError({
+        code: "internal_error",
+        message: "The API answered successfully with a body this client did not recognise. Either something between here and it replaced the answer, or this package is older than the route it called.",
+        status: response.status,
+        requestUrl: url
+      });
+    }
+    return answer;
+  }
+  function cached(tags) {
+    return { method: "GET", next: { tags, revalidate } };
+  }
+  const live = { method: "GET", cache: "no-store" };
+  function write(body, options2) {
+    return {
+      method: "POST",
+      cache: "no-store",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": options2?.idempotencyKey ?? newIdempotencyKey()
+      },
+      body: JSON.stringify(body)
+    };
+  }
+  return {
+    async getProducts(listOptions) {
+      const query = new URLSearchParams();
+      if (listOptions?.limit !== void 0) {
+        query.set("limit", `${listOptions.limit}`);
+      }
+      if (listOptions?.cursor) {
+        query.set("cursor", listOptions.cursor);
+      }
+      if (listOptions?.category) {
+        query.set("category", listOptions.category);
+      }
+      const result = await send(
+        `/products${suffix(query)}`,
+        cached([productsTag()]),
+        (body) => listOrNothing(body, "data"),
+        false
+      );
+      return result;
+    },
+    getProduct(slugOrId) {
+      return send(
+        `/products/${encodeURIComponent(slugOrId)}`,
+        cached([productsTag(), productTag(slugOrId)]),
+        (body) => dataOf(body),
+        true
+      );
+    },
+    getAvailability(slugOrId) {
+      return send(
+        `/products/${encodeURIComponent(slugOrId)}/availability`,
+        live,
+        (body) => dataOf(body),
+        true
+      );
+    },
+    async getEvents(listOptions) {
+      const query = new URLSearchParams();
+      if (listOptions?.limit !== void 0) {
+        query.set("limit", `${listOptions.limit}`);
+      }
+      if (listOptions?.cursor) {
+        query.set("cursor", listOptions.cursor);
+      }
+      if (listOptions?.from) {
+        query.set("from", listOptions.from);
+      }
+      if (listOptions?.to) {
+        query.set("to", listOptions.to);
+      }
+      const result = await send(
+        `/events${suffix(query)}`,
+        cached([eventsTag()]),
+        (body) => listOrNothing(body, "events"),
+        false
+      );
+      return result;
+    },
+    getEvent(idOrSlug) {
+      return send(
+        `/events/${encodeURIComponent(idOrSlug)}`,
+        cached([eventsTag(), eventTag(idOrSlug)]),
+        (body) => dataOf(body),
+        true
+      );
+    },
+    getEventAvailability(eventId) {
+      return send(
+        `/events/${encodeURIComponent(eventId)}/availability`,
+        live,
+        (body) => body,
+        true
+      );
+    },
+    async submitOrder(input, writeOptions) {
+      const result = await send(
+        "/orders",
+        write(input, writeOptions),
+        (body) => dataOf(body),
+        false
+      );
+      return result;
+    },
+    async upsertContact(input, writeOptions) {
+      const result = await send(
+        "/contacts",
+        write(input, writeOptions),
+        (body) => dataOf(body),
+        false
+      );
+      return result;
+    },
+    async submitRequest(input, writeOptions) {
+      const result = await send(
+        "/requests",
+        write(input, writeOptions),
+        (body) => dataOf(body),
+        false
+      );
+      return result;
+    },
+    async submitForm(formId, input, writeOptions) {
+      const result = await send(
+        `/forms/${encodeURIComponent(formId)}/submissions`,
+        write(input, writeOptions),
+        (body) => dataOf(body),
+        false
+      );
+      return result;
+    }
+  };
+}
+function suffix(query) {
+  const rendered = query.toString();
+  return rendered ? `?${rendered}` : "";
+}
+function dataOf(body) {
+  return body?.data;
+}
+function listOrNothing(body, key) {
+  const listing = body;
+  return Array.isArray(listing?.[key]) ? listing : void 0;
+}
+function newIdempotencyKey() {
+  const source = globalThis.crypto;
+  if (typeof source?.randomUUID === "function") {
+    return source.randomUUID();
+  }
+  if (typeof source?.getRandomValues === "function") {
+    const bytes = source.getRandomValues(new Uint8Array(16));
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+}
+function inSomethingTheUserCanRead() {
+  if (typeof window !== "undefined") {
+    return true;
+  }
+  const scope = globalThis;
+  return typeof scope.importScripts === "function";
+}
+
+// src/generated/api-types.ts
+var ALL_API_SCOPES = [
+  "catalog:read",
+  "events:read",
+  "orders:write",
+  "contacts:write",
+  "forms:write"
+];
+var ALL_API_WEBHOOK_EVENTS = [
+  "product.changed",
+  "product.deleted",
+  "event.changed",
+  "order.status_changed"
+];
+var ALL_API_ERROR_CODES = [
+  "unauthorized",
+  "forbidden",
+  "feature_unavailable",
+  "not_found",
+  "invalid_request",
+  "idempotency_key_reused",
+  "request_in_progress",
+  "rate_limited",
+  "internal_error"
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_API_ERROR_CODES,
+  ALL_API_SCOPES,
+  ALL_API_WEBHOOK_EVENTS,
+  CrmApiError,
+  createClient,
+  eventTag,
+  eventsTag,
+  productTag,
+  productsTag,
+  tagsForDelivery
+});
+//# sourceMappingURL=index.cjs.map