@solumflow-app/crm-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ascensie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# @solumflow-app/crm-client
+
+Read a CRM catalogue and send orders back to it, from your own website.
+
+```ts
+// lib/crm.ts
+import { createClient } from '@solumflow-app/crm-client';
+
+export const crm = createClient({
+  apiKey: process.env.CRM_API_KEY!,
+  baseUrl: process.env.CRM_BASE_URL!, // https://app.example.com — origin only
+});
+```
+
+```tsx
+// app/shop/page.tsx
+const { data } = await crm.getProducts({ limit: 24 });
+```
+
+That is the whole of it for a shop that lists products. The rest of this file is
+the parts that bite.
+
+---
+
+## The two kinds of reading function, and why the names differ
+
+```ts
+const { data } = await crm.getProducts();      // cached, may be a minute old
+const product = await crm.getProduct('eiken-tafel'); // cached
+const stock = await crm.getAvailability(product.id); // live, never cached
+```
+
+`getProducts` and `getProduct` are cached at the edge and filed under tags the
+revalidation route below knows how to clear. `getAvailability` is not cached
+anywhere and never will be.
+
+Reach for the live one for anything a visitor would notice was wrong. Stock is
+the example: a cached "in stock" is the first thing to go stale and the most
+expensive when it does. Nothing in the type system will warn you — the split is
+in the name because that is the only place it could be.
+
+Detail lookups answer `null` when there is no such thing, so a slug somebody
+typed wrong is an ordinary outcome:
+
+```tsx
+const product = await crm.getProduct(params.slug);
+
+if (!product) notFound();
+```
+
+Everything else — a rejected key, a missing permission, a rate limit — throws a
+`CrmApiError`. That difference is deliberate: if a bad key also produced `null`,
+a misconfigured site would render "not found" on every page for ever.
+
+## Two kinds of key
+
+| Prefix | Where it may live | What it may do |
+| --- | --- | --- |
+| `crmp_` | anywhere, including a browser bundle | read the catalogue |
+| `crms_` | a server, and nowhere else | read and write |
+
+A `crms_` key can create orders and resolve contacts. This client throws on
+construction if it finds one in a browser, so that ends up as an error on the
+first render rather than as a key in a JavaScript bundle anyone can open.
+
+Issue keys in the CRM under **Settings → Integrations → API keys**. The value is
+shown once.
+
+## Keeping a cached shop from showing yesterday's prices
+
+Two steps.
+
+**1. Add the route.** One line, and the signature check comes with it:
+
+```ts
+// app/api/crm/revalidate/route.ts
+import { createRevalidateRoute } from '@solumflow-app/crm-client/webhooks';
+
+export const POST = createRevalidateRoute({
+  signingKey: process.env.CRM_WEBHOOK_KEY!,
+});
+```
+
+**2. Register the endpoint** in the CRM under **Settings → Integrations →
+Webhooks**: its URL, the events it wants, and the signing key it shows you once.
+
+That is it. A change to a product clears `crm:products` and `crm:product:<id>`,
+and the next request to a page built from either fetches fresh.
+
+Some things worth knowing about what arrives:
+
+- **A delivery carries ids and nothing else.** No product data. That is on
+  purpose — a message that arrives late still leads to the right state, because
+  your site fetches the current row rather than trusting a snapshot.
+- **The same delivery can arrive twice.** Retries reuse the `webhook-id` header,
+  so that is the thing to remember if you do something in `onEvent` that is not
+  safe to repeat.
+- **Deliveries are not ordered.** Always write current state, never a difference.
+
+If you want to do something beyond clearing tags — an order changing status is
+the usual one — `onEvent` is handed every verified delivery:
+
+```ts
+export const POST = createRevalidateRoute({
+  signingKey: process.env.CRM_WEBHOOK_KEY!,
+  onEvent: async ({ payload, messageId }) => {
+    if (payload.type === 'order.status_changed') {
+      await noteOrderChanged(messageId, payload.ids);
+    }
+  },
+});
+```
+
+### Checking a signature yourself
+
+If you would rather write the route, at least do not write the check:
+
+```ts
+import { verifyWebhook } from '@solumflow-app/crm-client/webhooks';
+
+const body = await request.text(); // the raw bytes, before any parsing
+
+const verdict = verifyWebhook({
+  signingKey: process.env.CRM_WEBHOOK_KEY!,
+  headers: {
+    'webhook-id': request.headers.get('webhook-id') ?? undefined,
+    'webhook-timestamp': request.headers.get('webhook-timestamp') ?? undefined,
+    'webhook-signature': request.headers.get('webhook-signature') ?? undefined,
+  },
+  payload: body,
+});
+```
+
+**Read the body as text first.** `JSON.parse` followed by `JSON.stringify`
+changes the bytes, and the signature is over the bytes. Parsing first gives you
+`bad_signature` on every delivery and sends you looking at your key.
+
+### Two answers a receiver should get right
+
+| Verdict | Answer | Why |
+| --- | --- | --- |
+| `bad_signature`, `missing_headers`, `malformed_key` | **401** | The sender never retries a 401 and parks the delivery immediately. Correct: a rotated key will be just as wrong in thirty seconds. |
+| `stale_timestamp` | **400** | Every attempt is signed afresh, so a delivery that queued behind a slow one gets through next time. A 401 here would bury it and make a slow queue look like a key problem. |
+
+## Writing back
+
+```ts
+const order = await crm.submitOrder({
+  buyer: { email: 'koper@example.com', firstName: 'Ada' },
+  lines: [{ productId, quantity: 2 }],
+  address: { line1: 'Dorpsstraat 1', postalCode: '1234 AB', city: 'Utrecht', countryCode: 'NL' },
+});
+
+// hand order.payment.clientSecret to Stripe, on order.payment.stripeAccount
+```
+
+There is no amount in that call 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.
+
+Also available: `upsertContact` (a newsletter sign-up, a back-in-stock notice),
+`submitRequest` (a question or a quote request, no amount) and `submitForm`.
+
+### Retrying safely
+
+Every write carries an `Idempotency-Key`, generated for you. **If you retry, send
+the key you used the first time:**
+
+```ts
+const key = crypto.randomUUID();
+
+try {
+  return await crm.submitOrder(input, { idempotencyKey: key });
+} catch (error) {
+  if (error instanceof CrmApiError && error.retryable) {
+    return await crm.submitOrder(input, { idempotencyKey: key }); // same key
+  }
+  throw error;
+}
+```
+
+A site that timed out does not know whether the order arrived. Sending it again
+under a *new* key is how one customer gets charged twice.
+
+## When something is refused
+
+```ts
+import { CrmApiError } from '@solumflow-app/crm-client';
+
+try {
+  await crm.submitOrder(input);
+} catch (error) {
+  if (error instanceof CrmApiError) {
+    error.code;      // 'invalid_request' | 'unauthorized' | …
+    error.fields;    // [{ path: 'buyer.email', message: 'Required' }]
+    error.retryable; // true for a rate limit or a server error
+  }
+}
+```
+
+Match on `code`, never on `message` — the message is written for somebody
+reading a log and gets reworded.
+
+Three codes say less than you might want, on purpose:
+
+- **`unauthorized`** means the key was not accepted and will not say whether it
+  is missing, mistyped, revoked or expired. The alternative is an endpoint that
+  tells a stranger whether a key they guessed exists. If you are sure the key is
+  right, check that you pasted all 48 characters.
+- **`forbidden`** covers both "this key does not carry that permission" and "this
+  is a browser-safe key and you asked it to write".
+- **`not_found`** is also the answer for something that exists but belongs to
+  somebody else.
+
+## Mirroring the catalogue into your own CMS
+
+If your site keeps its own copy of the products — for editorial fields, for
+search, for a page builder — `@solumflow-app/crm-client/mirror` owns the awkward half
+and leaves you the write:
+
+```ts
+import { createCatalogueMirror } from '@solumflow-app/crm-client/mirror';
+import { getPayload } from 'payload';
+import config from '@payload-config';
+
+const payload = await getPayload({ config });
+
+export const mirror = createCatalogueMirror({
+  client: crm,
+  target: {
+    upsert: async ({ id, product }) => {
+      const existing = await payload.find({
+        collection: 'products',
+        where: { crmId: { equals: id } },
+        limit: 1,
+      });
+
+      const data = {
+        crmId: id,
+        title: product.name,
+        slug: product.slug,
+        priceInEUR: product.priceFromCents,
+      };
+
+      if (existing.docs[0]) {
+        await payload.update({ collection: 'products', id: existing.docs[0].id, data });
+      } else {
+        await payload.create({ collection: 'products', data });
+      }
+    },
+    remove: async ({ id }) => {
+      await payload.delete({
+        collection: 'products',
+        where: { crmId: { equals: id } },
+      });
+    },
+  },
+});
+```
+
+Then hand it your deliveries:
+
+```ts
+export const POST = createRevalidateRoute({
+  signingKey: process.env.CRM_WEBHOOK_KEY!,
+  onEvent: ({ payload }) => mirror.apply(payload),
+});
+```
+
+Why the mapping is yours to write: the local collection's shape is not something
+a package could guess. A Payload shop built on `@payloadcms/plugin-ecommerce`
+stores `title`, `priceInEUR` and a `gallery` of uploads; this catalogue answers
+`name`, `priceFromCents` and `images` of URLs. The next shop names them
+differently again. What *is* the same everywhere is everything around it, and
+that is what the mirror does:
+
+- A product that has stopped answering is **removed**, not skipped. Moving
+  something back to draft deletes nothing, so it arrives as `product.changed`
+  for an id that then refuses to answer.
+- A **truncated** delivery means the id list is a fragment, and the mirror walks
+  the whole catalogue instead of acting on part of it.
+- `mirror.syncAll()` is there for a first import and for a scheduled repair.
+  Supply `listMirroredIds` if you also want it to take out what the catalogue no
+  longer has; without it, a resync adds and updates but never removes.
+- **Check `report.failed`.** An id that could not be fetched — a rate limit, a
+  five-hundred — is reported rather than thrown, so the rest of the batch still
+  lands. An empty `failed` is the only outcome that means the mirror is now
+  correct; anything else wants a retry, and the ids to retry are in it.
+  A `syncAll` that could not read everything **removes nothing at all**, because
+  "what the catalogue no longer has" is a subtraction and a hole in it takes out
+  live products.
+
+One Payload-specific note: `payload.update`/`payload.delete` with a `where`
+answer `{ docs, errors }` rather than throwing, so a row that fails is in
+`errors` and easy to miss. And if you do a bulk import, set
+`req.context.disableRevalidate` or every row will fire your collection's own
+revalidation hooks.
+
+## Cache tags
+
+| Tag | Carried by |
+| --- | --- |
+| `crm:products` | every product read, listing and detail alike |
+| `crm:product:<id or slug>` | `getProduct`, under the key you asked with |
+| `crm:events` | every event read |
+| `crm:event:<id or slug>` | `getEvent` |
+
+Detail reads carry the collection tag as well as their own, and that is not belt
+and braces. A delivery names ids; a product page is usually fetched by *slug*;
+nothing on this side can turn one into the other. Without the collection tag a
+slug-fetched page would never update — and would keep working while showing the
+old price, which is exactly the failure this package exists to prevent.
+
+Exported as functions, so you can clear them yourself:
+
+```ts
+import { productTag, productsTag } from '@solumflow-app/crm-client';
+
+revalidateTag(productTag(id), { expire: 0 });
+```
+
+## Options
+
+```ts
+createClient({
+  apiKey,
+  baseUrl,
+  revalidate: 60,  // seconds a cached answer may be served; `false` = only on a webhook
+  fetch,           // your own, for instrumentation or tests
+});
+```
+
+`revalidate: false` is right for a shop whose revalidation route is wired up and
+reachable, and wrong for one where it is not — then nothing ever expires at all.
+
+`createRevalidateRoute` takes a `profile` too. It defaults to `{ expire: 0 }`,
+which expires the entry outright so the next visitor waits and never sees the
+old answer. Pass `'max'` for stale-while-revalidate if you have a large
+catalogue and have decided that showing one stale price per page is acceptable.
+
+## What is deliberately not here
+
+- **No product URL.** An event is sold on a page the CRM hosts and carries a
+  link; a product is sold on *your* site, and the CRM does not know what you
+  called that page. A guessed link is worse than none.
+- **No `sku` and no stock count.** The first says who supplies a business and
+  often what it paid; the second is a figure a competitor would like. `gtin` is
+  offered instead, on the detail, because that one is printed on the box.
+- **No non-public custom fields.** `fields` carries only attributes somebody
+  marked public in the CRM, one at a time, and that switch is off by default.
+
+## Requirements
+
+Node 20 or newer. `next` is an optional peer dependency, needed only by
+`createRevalidateRoute` when you let it reach for `revalidateTag` itself.
+
+## Licence
+
+MIT. The licence covers this package only, not the CRM it talks to.

package/dist/client.d.ts

@@ -0,0 +1,102 @@
+import type { ContactInput, ContactResult, EventAvailability, EventDetail, EventList, FormSubmissionInput, FormSubmissionResult, OrderInput, OrderResult, ProductDetail, ProductList, RequestInput, RequestResult, StockStatus } from './types';
+/**
+ * The fetch options this package sets that are not in the web standard.
+ *
+ * `next` is read by Next.js and ignored by every other runtime, which is
+ * exactly the behaviour wanted: the tags do nothing outside a framework that
+ * caches, and nothing breaks in one that does not.
+ */
+type CachedInit = RequestInit & {
+    next?: {
+        tags?: string[];
+        revalidate?: number | false;
+    };
+};
+export type FetchLike = (input: string, init?: CachedInit) => Promise<Response>;
+export interface CrmClientOptions {
+    /**
+     * The key, whole.
+     *
+     * A `crmp_` key may be read by anyone who views source and may only read; a
+     * `crms_` key may write and must never leave a server. This client refuses a
+     * `crms_` key outright when it finds itself in a browser — see the note on
+     * `createClient`.
+     */
+    apiKey: string;
+    /**
+     * Where the CRM lives: an origin, with no path on it.
+     *
+     * `https://app.example.com`, not `https://app.example.com/api/public/v1`.
+     * The version lives in this package so that a shop upgrading the package is
+     * the thing that moves it, rather than a string in someone's environment
+     * file that nobody remembers to change.
+     */
+    baseUrl: string;
+    /**
+     * How long a cached answer may be served before it is refetched, in seconds.
+     *
+     * Defaults to a minute. `false` means never on a timer — only when a webhook
+     * clears the tag. That is the right setting for a shop whose revalidation
+     * route is wired up and reachable, and the wrong one for a shop where it is
+     * not, because then nothing ever expires at all.
+     */
+    revalidate?: number | false;
+    /** For tests and for runtimes with their own instrumented fetch. */
+    fetch?: FetchLike;
+}
+export interface ListOptions {
+    limit?: number;
+    cursor?: string | null;
+}
+export interface ProductListOptions extends ListOptions {
+    /** A category id. Passing something that is not a uuid is refused, loudly. */
+    category?: string;
+}
+export interface EventListOptions extends ListOptions {
+    /** ISO timestamps. Both ends are optional and both are inclusive. */
+    from?: string;
+    to?: string;
+}
+export interface WriteOptions {
+    /**
+     * The key that makes a retry safe.
+     *
+     * Generated per call when you leave it out, which is right for a first
+     * attempt and wrong for a retry: a website that timed out does not know
+     * whether the order arrived, and sending it again under a *new* key is how
+     * one customer gets charged twice. Keep the key you used and resend with it.
+     */
+    idempotencyKey?: string;
+}
+export interface CrmClient {
+    getProducts(options?: ProductListOptions): Promise<ProductList>;
+    getProduct(slugOrId: string): Promise<ProductDetail | null>;
+    /** Live. Never cached, at any layer. */
+    getAvailability(slugOrId: string): Promise<StockStatus | null>;
+    getEvents(options?: EventListOptions): Promise<EventList>;
+    getEvent(idOrSlug: string): Promise<EventDetail | null>;
+    /** Live. Never cached, at any layer. */
+    getEventAvailability(eventId: string): Promise<EventAvailability | null>;
+    submitOrder(input: OrderInput, options?: WriteOptions): Promise<OrderResult>;
+    upsertContact(input: ContactInput, options?: WriteOptions): Promise<ContactResult>;
+    submitRequest(input: RequestInput, options?: WriteOptions): Promise<RequestResult>;
+    submitForm(formId: string, input: FormSubmissionInput, options?: WriteOptions): Promise<FormSubmissionResult>;
+}
+/**
+ * A client for one account's public API.
+ *
+ * Two layers, and the names are the whole warning. `getProducts` and
+ * `getProduct` are cached at the edge and filed under tags the shipped
+ * revalidation route knows how to clear. `getAvailability` is not cached
+ * anywhere and never will be — a stock figure in a cached answer is the number
+ * that lies first and lies worst, and a developer who reaches for `getProduct`
+ * to show "in stock" gets no warning from the type system, so the split has to
+ * be in the name.
+ *
+ * The browser check is not decoration either. A `crms_` key can create orders
+ * and read contacts; pasted into a client component it ends up in a JavaScript
+ * bundle that anybody can open. Throwing at construction turns that into a
+ * build-time failure on the first render instead of a quiet leak.
+ */
+export declare function createClient(options: CrmClientOptions): CrmClient;
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+import type { ApiErrorCode } from './generated/api-types';
+/**
+ * A refusal from the API, with the machine-readable reason kept.
+ *
+ * Match on `code`, never on `message`. The code is a closed set that this
+ * package generates from the server's own list; the message is written for
+ * somebody reading a log and gets reworded.
+ *
+ * Three of the codes are deliberately vaguer than they could be, and knowing
+ * that saves an afternoon:
+ *
+ * - `unauthorized` means the key was not accepted, and says nothing about
+ *   which of "missing", "mistyped", "revoked" or "expired" applies. That is on
+ *   purpose — the alternative is an endpoint that tells a stranger whether a
+ *   key they guessed exists.
+ * - `forbidden` covers both "this key does not carry that permission" and "this
+ *   is a browser-safe key and you asked it to write", for the same reason.
+ * - `not_found` is also the answer for something that exists but belongs to
+ *   somebody else. A shop cannot tell the two apart, and should not be able to.
+ */
+export declare class CrmApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    readonly fields: {
+        path: string;
+        message: string;
+    }[];
+    /** Present when the API refused before the request reached a handler. */
+    readonly requestUrl: string;
+    constructor(input: {
+        code: ApiErrorCode;
+        message: string;
+        status: number;
+        fields?: {
+            path: string;
+            message: string;
+        }[];
+        requestUrl: string;
+    });
+    /**
+     * 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(): boolean;
+}