@solumflow-app/crm-client 0.1.0 → 0.3.0

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,15 @@ 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.
+     *
+     * A content block (`content_text`, `repeater`, `cta` -- see
+     * `PublicContentText`, `PublicRepeater` and `PublicCta`) that is public but
+     * has nothing in it is `null`, not absent: the site can tell "no content
+     * yet" from "not published". A block's shape is described by the field's own
+     * entry in `GET /attributes` (`PublicProductField`).
      */
     fields: Record<string, unknown>;
 }
@@ -95,11 +82,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 +143,240 @@ 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[];
+}
+/** A label with the address it leads to. The address is http, https, mailto or tel. */
+export interface PublicContentLink {
+    label: string;
+    url: string;
+}
+/** A glyph of the icon library: the set it is in and its name there. */
+export interface PublicContentIcon {
+    set: 'brands' | 'solid' | 'regular';
+    name: string;
+}
+/**
+ * A picture or a download inside a block, ready to use.
+ *
+ * `size` (bytes) and `contentType` are null when storage cannot say; `name` is
+ * the file name to show or to save the download under.
+ */
+export interface PublicContentFile {
+    url: string;
+    name: string;
+    size: number | null;
+    contentType: string | null;
+}
+/** A `content_text` field: sanitised html and optional links beneath it. */
+export interface PublicContentText {
+    html: string;
+    links?: PublicContentLink[];
+}
+/**
+ * One entry of a repeater. The keys besides `id` are the `itemFields` of the
+ * field as `GET /attributes` describes it; an entry holds a key only when it
+ * was filled in.
+ */
+export interface PublicRepeaterItem {
+    id: string;
+    [key: string]: string | PublicContentLink | PublicContentIcon | PublicContentFile | undefined;
+}
+/**
+ * A `repeater` field: a list, an accordion (FAQ), downloads or testimonials,
+ * depending on the field's `display` and `preset`. Keys an item field no
+ * longer has are never in the items.
+ */
+export interface PublicRepeater {
+    items: PublicRepeaterItem[];
+}
+/** A `cta` field: a heading, a line of text and one or two buttons. */
+export interface PublicCta {
+    heading: string;
+    body: string;
+    primary: PublicContentLink;
+    /** Only present when the field offers a second button. */
+    secondary?: PublicContentLink | null;
+}
+/** One entry of a repeater's structure, as `GET /attributes` describes it. */
+export interface PublicRepeaterItemField {
+    key: string;
+    label: string;
+    type: 'text' | 'richtext' | 'url' | 'icon' | 'image' | 'file';
+}
+/**
+ * A custom field of the catalogue as `GET /attributes` lists it.
+ *
+ * `options` is empty unless the field is a choice. The last four keys exist
+ * only on a `repeater`: how to draw it (`display`), the name of the built-in
+ * shape it started as (`preset`, may be absent), the structure of one entry
+ * (`itemFields`) and which entry key names it (`titleKey`, the question of a
+ * FAQ).
+ */
+export interface PublicProductField {
+    slug: string;
+    label: string;
+    type: string;
+    multiple: boolean;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    display?: 'list' | 'accordion';
+    preset?: string;
+    itemFields?: PublicRepeaterItemField[];
+    titleKey?: string;
+}
+/**
+ * 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 +505,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;
+}