@solumflow-app/crm-client 0.1.0 → 0.2.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.

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

@@ -1,47 +1,27 @@
 /** 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 type ApiScope = 'catalog:read' | 'catalog:write' | 'events:read' | 'orders:write' | 'contacts:write' | 'forms:write' | 'website:manage';
 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 type ApiWebhookEvent = 'product.changed' | 'product.deleted' | 'category.changed' | '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 type ApiErrorCode = 'unauthorized' | 'forbidden' | 'feature_unavailable' | 'not_found' | 'invalid_request' | 'conflict' | '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.
- */
+/** What a product is, for the one question the answer changes: does anything get shipped. Whether it repeats is a property of its price, not of this. */
+export type ProductType = 'digital' | 'physical' | 'service';
+export declare const ALL_PRODUCT_TYPES: readonly ProductType[];
 export interface PublicProductListItem {
     id: string;
+    /**
+     * Which catalogue the product is in, by the slug the seller gave it:
+     * `product` for the catalogue every account has, something like `courses`
+     * for one of its own. The listing takes the same word as `?object=`.
+     */
+    object: string;
     /** Always present: a product without an address cannot be published. */
     slug: string;
     name: string;
-    productType: 'digital' | 'physical';
+    productType: ProductType;
     /**
      * 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.
@@ -73,8 +53,9 @@ export interface PublicProductListItem {
      */
     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.
+     * The custom fields this account invented for this product's catalogue,
+     * keyed by the slug they chose, and only the ones marked public there. An
+     * empty object when none are.
      */
     fields: Record<string, unknown>;
 }
@@ -95,11 +76,40 @@ export interface PublicProductDetail extends PublicProductListItem {
     gtin: string | null;
     metaTitle: string | null;
     metaDescription: string | null;
+    /**
+     * What a link to this product should show when somebody shares it, with
+     * every fallback already applied.
+     *
+     * Resolved here rather than left to the site, and `metaTitle` beside it is
+     * why: a site given both would have to decide which wins when one is empty,
+     * and every site would decide slightly differently. The screen that edits
+     * these shows a preview, and that preview and this field are the same
+     * function -- so what a seller saw is what a stranger gets.
+     */
+    social: {
+        title: string;
+        description: string | null;
+        /** A path, turned into a URL by the route. Same reason as `imagePath`. */
+        imagePath: string | null;
+    };
     images: PublicProductImage[];
     prices: PublicProductPrice[];
     categories: PublicProductCategory[];
     /** What the seller linked this to — a companion, a refill, a bigger model. */
     related: PublicProductSummary[];
+    /**
+     * The fields this product's variants differ along — a width, a colour —
+     * each with the values somebody can choose, in the field's own order.
+     * Empty for a product sold as one thing.
+     */
+    variantAxes: PublicProductVariantAxis[];
+    /**
+     * One entry per variant still on sale, in the seller's order. A shop
+     * orders a variant by its `id` or by the `id` of one of its prices.
+     * Pictures are the variant's own; a variant without any shows the
+     * product's.
+     */
+    variants: PublicProductVariant[];
 }
 export interface PublicProductImage {
     /** A path, turned into a URL by the route. Same reason as `imagePath`. */
@@ -127,14 +137,159 @@ export interface PublicProductPrice {
     trialPeriodDays: number | null;
     isDefault: boolean;
 }
+/**
+ * One category this product sits in, as a page a visitor could land on.
+ *
+ * It used to be a record of an object the account invented, linked through
+ * `crm_record_links`, and it carried a name and nothing else. It is now a real
+ * category: a page with an address, a place in a tree, and one of them marked
+ * as the one this product belongs to most.
+ *
+ * `slug` is nullable even though only published categories are listed here,
+ * and that is not belt-and-braces: it keeps the type honest against the day a
+ * caller asks for the categories of something that is not on sale yet.
+ *
+ * `path` runs from the top down and **ends with this category itself**, so a
+ * breadcrumb is the array as given, with no element to append. A step whose
+ * `slug` is null is a step to print rather than to link -- an ancestor that is
+ * still a draft is not a page anybody can open.
+ */
 export interface PublicProductCategory {
     id: string;
     name: string;
+    slug: string | null;
+    /** Root first, this category last. Never empty. */
+    path: PublicCategoryStep[];
+    /** The one that carries the breadcrumb and the structured data. */
+    isPrimary: boolean;
+}
+/** One step on the way down to a category. */
+export interface PublicCategoryStep {
+    id: string;
+    name: string;
+    /** Null when this step has no page of its own yet: print it, do not link it. */
+    slug: string | null;
 }
 export interface PublicProductSummary {
+    id: string;
+    /** The catalogue it is in, the same word a listing item carries. */
+    object: string;
+    slug: string;
+    name: string;
+}
+export interface PublicProductVariantAxis {
+    slug: string;
+    label: string;
+    values: string[];
+}
+export interface PublicProductVariant {
+    id: string;
+    /** The value per axis, keyed by the axis slug. */
+    options: Record<string, string>;
+    /** The cheapest active price of this variant, as on the product. */
+    priceFromCents: number;
+    inStock: boolean;
+    prices: PublicProductPrice[];
+    images: PublicProductImage[];
+}
+/**
+ * One category as a stranger's website sees it.
+ *
+ * The same contract rules as `public-product-item.ts`: these keys are read by
+ * shops nobody here redeploys, so fields may be added and must not be renamed
+ * or repurposed.
+ *
+ * What is deliberately absent:
+ *
+ * - **`active`.** It says whether a member still files products under this
+ *   category, which is a fact about their catalogue rather than about the
+ *   page. A shop that read it would hide a page that is plainly published.
+ * - **`sortOrder`.** The order is the order of the array. A number would
+ *   invite a shop to sort by it across pages, where it does not mean what it
+ *   looks like -- it is unique only among siblings.
+ * - **Anything that counts drafts.** `productCount` is what a visitor would
+ *   find, counted the same way the product list selects. A number larger than
+ *   the page it heads is a promise the page then breaks.
+ */
+export interface PublicCategoryListItem {
+    id: string;
+    /** Always present: a category without an address is not published. */
+    slug: string;
+    name: string;
+    /** Where it hangs, so a shop can build the tree from a flat page. */
+    parentId: string | null;
+    description: 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.
+     */
+    imagePath: string | null;
+    /**
+     * The way down from the top, ending with this category.
+     *
+     * Here as well as on the detail, and not left to a shop to assemble from
+     * `parentId`. `?parent=<id>` answers one level, so a menu that unfolds has
+     * no ancestors to build from -- and a shop that stitched a breadcrumb
+     * together itself here while reading `path` on the detail page would have
+     * two sources for one road. They agree until somebody moves a category, and
+     * then the visible trail and the `BreadcrumbList` beside it say different
+     * things, which is the one contradiction a search engine reads as a fault.
+     *
+     * A step whose `slug` is null is an ancestor with no page of its own yet --
+     * print it, do not link it.
+     */
+    path: PublicCategoryStep[];
+    /** Public products on this category's page, its whole branch included. */
+    productCount: number;
+    /**
+     * When this category last changed, for `lastmod` in a shop's sitemap.
+     *
+     * It is the moment the *category* was edited: its text, its address, its
+     * place in the tree. A product moving onto its shelf does not move it, so a
+     * shop that wants its category pages recrawled when the contents change has
+     * to take the products into account as well.
+     *
+     * **Not the same kind of fact as `publishedAt`, which is deliberately absent
+     * here.** A publication moment may lie in the future, and then it is a plan:
+     * it tells a stranger when a shop intends to launch something. This one is
+     * always in the past and says only that the page they can already see was
+     * touched -- which is exactly what a sitemap publishes anyway.
+     */
+    updatedAt: string;
+}
+export interface PublicCategoryDetail {
     id: string;
     slug: string;
     name: string;
+    parentId: string | null;
+    description: string | null;
+    imagePath: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    /**
+     * What a link to this page looks like when somebody shares it.
+     *
+     * Filled in by the same function the seller previewed it with, so what they
+     * saw is what a stranger gets.
+     */
+    social: {
+        title: string;
+        description: string | null;
+        /** A path, turned into a URL by the route. Same reason as `imagePath`. */
+        imagePath: string | null;
+    };
+    /**
+     * The way down from the top, ending with this category.
+     *
+     * The breadcrumb, as given. A step whose `slug` is null is an ancestor with
+     * no page of its own yet -- print it, do not link it.
+     */
+    path: PublicCategoryStep[];
+    productCount: number;
+    /** When the category itself last changed. Same meaning as on the listing. */
+    updatedAt: string;
+    /** The first page of them; `nextCursor` beside the answer carries the rest. */
+    products: PublicProductListItem[];
 }
 /**
  * One event as a stranger's website sees it.
@@ -263,3 +418,60 @@ export interface ApiWebhookPayload {
     ids: string[];
     truncated: boolean;
 }
+/** A published form, ready to be placed on a page. */
+export interface PlacementForm {
+    id: string;
+    slug: string;
+    name: string;
+    /** The form on a page of its own, for a plain link. */
+    url: string;
+    /** An empty `div` naming the form and the script that fills it. */
+    embed: string;
+}
+/** A chat widget and what it takes to put it on a site. */
+export interface PlacementChatWidget {
+    id: string;
+    slug: string;
+    name: string;
+    status: 'draft' | 'published' | 'archived';
+    /**
+     * The sites the widget may run on. A site not listed here gets an empty
+     * corner, with the reason only in the browser's console.
+     */
+    allowedOrigins: string[];
+    /** The script tag, or null while the widget is not published. */
+    embed: string | null;
+}
+/** The website tracking script of the account. */
+export interface PlacementSiteTracking {
+    /** Public by design: it is in the page source of every tracked site. */
+    publicKey: string;
+    /** The hosts the script reports from; visits from any other are dropped. */
+    allowedHosts: string[];
+    /**
+     * The consent the script waits for before it does anything:
+     * `ad_storage`, `analytics_storage`, `personalization_storage`, or
+     * `api_only` (it waits until the page says so itself).
+     */
+    consentSignal: 'ad_storage' | 'analytics_storage' | 'personalization_storage' | 'api_only';
+    lastReceivedAt: string | null;
+    embed: string;
+}
+/** A page a visitor can book on. */
+export interface PlacementBookingPage {
+    /**
+     * `services`: every service the account offers online. `category` and
+     * `service`: narrowed to one. `calendar`: an appointment calendar of its own.
+     */
+    kind: 'services' | 'category' | 'service' | 'calendar';
+    /** The category, service or calendar; null for `services`. */
+    id: string | null;
+    name: string;
+    /** The page's address. Built on the id where there is one, so a rename does not break it. */
+    url: string;
+    /**
+     * An iframe plus the script that sizes it, or null for a `calendar`, which
+     * has no embeddable widget yet: link to `url` instead.
+     */
+    embed: string | null;
+}