@solumflow-app/crm-client 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,8 @@ the parts that bite.
 ```ts
 const { data } = await crm.getProducts();      // cached, may be a minute old
 const product = await crm.getProduct('eiken-tafel'); // cached
+const { data: tree } = await crm.getCategories();    // cached
+const shelf = await crm.getCategory('eettafels');    // cached
 const stock = await crm.getAvailability(product.id); // live, never cached
 ```
 
@@ -39,6 +41,16 @@ 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.
 
+`getCategories` answers flat rows with a `parentId` on each, because a tree is
+the one shape a cursor cannot page through. Build the tree yourself, or ask for
+one level at a time with `{ parent: 'root' }` and `{ parent: id }`.
+
+`getCategory` answers the category, its breadcrumb and the first page of its
+products — the products of its **whole branch**, so a top-level category is not
+an empty page above everything that hangs under it. Page them with `limit` and
+`cursor` on the same call; `nextCursor` sits beside the category, because it
+pages the products and not the category.
+
 Detail lookups answer `null` when there is no such thing, so a slug somebody
 typed wrong is an ordinary outcome:
 
@@ -52,6 +64,84 @@ Everything else — a rejected key, a missing permission, a rate limit — throw
 `CrmApiError`. That difference is deliberate: if a bad key also produced `null`,
 a misconfigured site would render "not found" on every page for ever.
 
+## Addresses
+
+Your site owns its URLs; this package has no say in them and no way to check
+them. So this section is the one piece of advice in this file that you have to
+apply yourself, and it is here because the moment to read it is while you are
+laying out your routes.
+
+**One product, one address.** Put products at `/products/<slug>` — one flat
+segment — and not at `/<category>/<product>`.
+
+The reason is not tidiness. A product may sit in more than one category; that
+is the whole point of the tree. Nest the product under its categories and a gas
+fire filed under both "Fires" and "Gas" has two addresses serving identical
+content, three if somebody adds a third shelf. A search engine then has to pick
+which of them is the real one, and it will not ask you: whichever it picks is
+the one that collects the rankings, and any links you or anybody else built to
+the other two point at a page it has decided is a copy. Then somebody re-files
+the product, and every address it had 404s at once. This is the failure mode
+WordPress shops with nested product permalinks spend years undoing, and it is
+cheap to avoid and expensive to reverse.
+
+**Categories do get their own path**, because a category here is a page rather
+than a filter — its own text, its own share card, its own place to land from a
+search. `/<category-path>/` or `/categories/<slug>`, whichever suits your site;
+what matters is that the address belongs to the category and never changes when
+a product moves.
+
+**Canonical every page to itself**, including page two of a category. A paged
+listing that canonicals back to page one tells a crawler that the products on
+page two live on a page they are not on.
+
+### `path`, and using one breadcrumb
+
+Every category read carries `path`: the road from the top down, **ending with
+the category itself**, so there is nothing to append. It is on `getCategories`
+as well as on `getCategory` precisely so that you never build a second one —
+render the visible trail and your `BreadcrumbList` structured data from this
+one array. Two sources agree until somebody moves a category in the CRM, and
+then the trail a visitor reads and the one a crawler reads say different
+things, which is read as a fault rather than as a difference.
+
+A step whose `slug` is `null` is an ancestor that has no page of its own yet.
+Print its name; do not link it.
+
+### `isPrimary`, and products in more than one place
+
+`getProduct` answers a `categories` array, each entry carrying its own full
+`path`, and **at most one of them has `isPrimary: true`**. That is the one whose
+path the product's breadcrumb should follow — the seller chose it, in the CRM,
+for exactly this.
+
+The array may also be **empty**, and that is an ordinary product rather than a
+broken one: not everything a shop sells is filed somewhere. Draw no breadcrumb
+at all in that case, rather than an empty bar. The canonical is unaffected
+either way — under the rule above it is the product's own flat address, which is
+where it lived all along.
+
+The array may also carry **no** primary, and that happens for a reason worth
+knowing: the seller did mark one, but that category is not published — still a
+draft, or scheduled for a date that has not arrived — so it is not in your
+answer at all. Nothing is wrong and nothing is being hidden from you; the shelf
+simply has no page yet.
+
+The list arrives sorted, the marked one first and the rest alphabetically by
+their whole path, so `categories[0]` is a stable choice when there is no primary
+and the same on every render. What you must not do is pick a different one each
+time.
+
+### `updatedAt`, and your sitemap
+
+Every category carries `updatedAt`, which is what `lastmod` wants. It moves when
+the *category* changes: its name, text, address, or where it hangs. It does not
+move when a product is published onto its shelf — so if you want a category page
+recrawled when its contents change, take the products on it into account too.
+
+Categories that are not published are not in the answers at all, so a sitemap
+built from `getCategories` cannot accidentally list a page that is not there.
+
 ## Two kinds of key
 
 | Prefix | Where it may live | What it may do |
@@ -302,6 +392,8 @@ revalidation hooks.
 | --- | --- |
 | `crm:products` | every product read, listing and detail alike |
 | `crm:product:<id or slug>` | `getProduct`, under the key you asked with |
+| `crm:categories` | every category read |
+| `crm:category:<id or slug>` | `getCategory`, under the key you asked with |
 | `crm:events` | every event read |
 | `crm:event:<id or slug>` | `getEvent` |
 
@@ -311,6 +403,11 @@ 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.
 
+`getCategory` carries `crm:products` too, and a `category.changed` delivery
+clears both collections. A category page is mostly a list of products: a product
+published into a shelf has to reach it, and a `product.changed` delivery names
+only the product.
+
 Exported as functions, so you can clear them yourself:
 
 ```ts
@@ -338,6 +435,53 @@ 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.
 
+## Placing forms, booking pages, chat and tracking on your site
+
+With a `crms_` key carrying `website:manage`, the client lists what an account
+has set up for a website, each with its link and the HTML snippet the app's own
+screens hand out:
+
+```ts
+const { data: forms } = await crm.getForms();
+const pages = await crm.getBookingPages();
+const { data: widgets } = await crm.getChatWidgets();
+const tracking = await crm.getSiteTracking(); // null until it is set up
+```
+
+Two writes make a site work: `upsertChatWidget(slug, { name, status,
+addAllowedOrigins })` makes or publishes a chat widget and lets it run on a
+site, and `updateSiteTracking({ addAllowedHosts })` sets tracking up and
+counts visits from a host. Both add and remove sites rather than replace the
+list. Mind the difference: a chat widget with no sites runs on any site, while
+tracking with no hosts counts nothing. Forms are made in the app's form
+builder, never through the API.
+
+On a React 19 site, `@solumflow-app/crm-client/react` draws the same things
+without pasting HTML:
+
+```tsx
+import {
+  CrmBooking,
+  CrmChatWidget,
+  CrmEmbedProvider,
+  CrmForm,
+  CrmSiteTracking,
+} from '@solumflow-app/crm-client/react';
+
+<CrmEmbedProvider appOrigin="https://app.example.com">
+  <CrmForm formId={form.id} title={form.name} />
+  <CrmBooking url={page.url} title={page.name} />
+  <CrmChatWidget widgetId={widget.id} />
+  <CrmSiteTracking publicKey={tracking.publicKey} />
+</CrmEmbedProvider>
+```
+
+`CrmForm` draws its own frame rather than leaving it to the embed script, which
+looks for forms only once when it loads: in an app that navigates without
+reloading, a form shown later would otherwise stay empty. Put `CrmChatWidget`
+and `CrmSiteTracking` in the layout, once. React loads each script once per
+page, however many components ask for it.
+
 ## What is deliberately not here
 
 - **No product URL.** An event is sold on a page the CRM hosts and carries a
@@ -353,6 +497,8 @@ catalogue and have decided that showing one stale price per page is acceptable.
 
 Node 20 or newer. `next` is an optional peer dependency, needed only by
 `createRevalidateRoute` when you let it reach for `revalidateTag` itself.
+`react` 19 or newer is an optional peer dependency, needed only by
+`@solumflow-app/crm-client/react`.
 
 ## Licence
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ContactInput, ContactResult, EventAvailability, EventDetail, EventList, FormSubmissionInput, FormSubmissionResult, OrderInput, OrderResult, ProductDetail, ProductList, RequestInput, RequestResult, StockStatus } from './types';
+import type { CatalogArchiveResult, CatalogCategoryInput, CatalogCategoryResult, CatalogField, CatalogFieldInput, CatalogFieldResult, CatalogProductInput, CatalogProductResult, CategoryList, ChatWidgetInput, ChatWidgetList, ChatWidgetResult, CategoryPage, ContactInput, ContactResult, EventAvailability, EventDetail, EventList, FormSubmissionInput, FormList, FormSubmissionResult, OrderInput, OrderResult, ProductDetail, ProductList, RequestInput, PlacementBookingPage, PlacementSiteTracking, RequestResult, SiteTrackingInput, SiteTrackingResult, StockStatus } from './types';
 /**
  * The fetch options this package sets that are not in the web standard.
  *
@@ -49,8 +49,28 @@ export interface ListOptions {
     cursor?: string | null;
 }
 export interface ProductListOptions extends ListOptions {
-    /** A category id. Passing something that is not a uuid is refused, loudly. */
+    /**
+     * A category id, and it means that category's whole branch.
+     *
+     * Passing something that is not a uuid is refused, loudly.
+     */
     category?: string;
+    /**
+     * One catalogue, by the slug of its product object: `product`, or one the
+     * seller made. Left out, every catalogue is listed; each product says which
+     * it is in (`object`).
+     */
+    object?: string;
+}
+export interface CategoryListOptions extends ListOptions {
+    /**
+     * One level of the tree instead of all of it.
+     *
+     * `'root'` asks for the top level; a category id asks for its children.
+     * Leaving it out returns every published category, which is what a shop
+     * building a menu in one go wants.
+     */
+    parent?: string | 'root';
 }
 export interface EventListOptions extends ListOptions {
     /** ISO timestamps. Both ends are optional and both are inclusive. */
@@ -71,6 +91,9 @@ export interface WriteOptions {
 export interface CrmClient {
     getProducts(options?: ProductListOptions): Promise<ProductList>;
     getProduct(slugOrId: string): Promise<ProductDetail | null>;
+    getCategories(options?: CategoryListOptions): Promise<CategoryList>;
+    /** The category, its breadcrumb, and the first page of its products. */
+    getCategory(slugOrId: string, options?: ListOptions): Promise<CategoryPage | null>;
     /** Live. Never cached, at any layer. */
     getAvailability(slugOrId: string): Promise<StockStatus | null>;
     getEvents(options?: EventListOptions): Promise<EventList>;
@@ -81,6 +104,36 @@ export interface CrmClient {
     upsertContact(input: ContactInput, options?: WriteOptions): Promise<ContactResult>;
     submitRequest(input: RequestInput, options?: WriteOptions): Promise<RequestResult>;
     submitForm(formId: string, input: FormSubmissionInput, options?: WriteOptions): Promise<FormSubmissionResult>;
+    /**
+     * Make or change one product, found by the id it has in your own system.
+     * Needs a `crms_` key with `catalog:write`. Sending the same body again
+     * changes nothing and answers `created: false`.
+     */
+    upsertProduct(externalRef: string, input: CatalogProductInput, options?: WriteOptions): Promise<CatalogProductResult>;
+    /** Take a product and its variants out of the catalogue. Archived, never deleted. */
+    archiveProduct(externalRef: string, source: string, options?: WriteOptions): Promise<CatalogArchiveResult>;
+    /** Make or change one category, by its address. */
+    upsertCategory(slug: string, input: CatalogCategoryInput, options?: WriteOptions): Promise<CatalogCategoryResult>;
+    /** Make or change one field of the catalogue, by its slug. */
+    upsertField(slug: string, input: CatalogFieldInput, options?: WriteOptions): Promise<CatalogFieldResult>;
+    /** The fields the catalogue publishes, with their choices: what a filter is built from. */
+    getFields(): Promise<CatalogField[]>;
+    /**
+     * The account's published forms, each with its link and the snippet that
+     * places it on a page. Needs a `crms_` key with `website:manage`. Forms are
+     * made in the app's builder; a draft is not listed. Live, never cached.
+     */
+    getForms(options?: ListOptions): Promise<FormList>;
+    /** The account's chat widgets, with the sites each may run on. Live. */
+    getChatWidgets(options?: ListOptions): Promise<ChatWidgetList>;
+    /** Make or change one chat widget, by its address. */
+    upsertChatWidget(slug: string, input: ChatWidgetInput, options?: WriteOptions): Promise<ChatWidgetResult>;
+    /** The website tracking script, or null when tracking was never set up. Live. */
+    getSiteTracking(): Promise<PlacementSiteTracking | null>;
+    /** Set tracking up when needed, and change its hosts or consent signal. */
+    updateSiteTracking(input: SiteTrackingInput, options?: WriteOptions): Promise<SiteTrackingResult>;
+    /** Every page a visitor can book on, with its link and, where there is one, its widget. Live. */
+    getBookingPages(): Promise<PlacementBookingPage[]>;
 }
 /**
  * A client for one account's public API.