@holaboss/client 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode } from 'react';
 
 /** A file the employee produced (image/video/audio/other). In-turn artifacts (a turn's
@@ -61,6 +61,9 @@ type HolaMessage = {
 type HolaSubscribeHandlers = {
     onMessage: (message: HolaMessage) => void;
     onError?: (error: HolaError) => void;
+    /** A poll completed cleanly. Fires every successful cycle (even with no new messages) so a
+     *  consumer can clear a stale error — the receive channel retries, so one blip is not an outage. */
+    onHealthy?: () => void;
 };
 type HolaSubscribeOptions = {
     /** Resume from this cursor; omit to read the thread from the start. */
@@ -97,9 +100,6 @@ type HolaTransport = {
      *  async artifact. Returns an unsubscribe. Optional: a transport with no receive channel omits
      *  it (callers guard on its presence). */
     subscribe?(handlers: HolaSubscribeHandlers, options?: HolaSubscribeOptions): () => void;
-    /** "Talk to a person": ask for a human to take over this conversation. The AI pauses until a
-     *  teammate replies or hands back; the person's messages arrive via `subscribe`. Optional. */
-    requestHuman?(): Promise<void>;
 };
 
 type ApiTransportConfig = {
@@ -108,10 +108,19 @@ type ApiTransportConfig = {
     /** End-user access token for the Authorization header. A string, or a getter so a
      *  refreshed token is used per request. */
     token: string | (() => string | Promise<string>);
+    /**
+     * Which of the customer's projects this conversation is about.
+     *
+     * Omit for the general thread — the one running conversation with the company,
+     * and where everything that predates per-project threads still lives. The
+     * server checks the project belongs to this customer before it trusts it, so
+     * naming someone else's is a 404 rather than a way into their thread.
+     */
+    project?: string;
 };
 /** The Bearer-authed transport for the signed-in end-user PORTAL (`/api/v1/end-user/*`). Same
  *  client surface as the anonymous widget transport — the token (not a path param) resolves the
- *  customer and their one lifelong thread. The portal is buffered (no SSE) and one-thread-per-user,
+ *  customer; an optional `project` picks which of their threads. The portal is buffered (no SSE) and one-thread-per-user,
  *  so `sendMessage` returns just the reply and everything out-of-turn — the AI's turns, a human's
  *  reply, an async artifact (video) — arrives via `subscribe`. */
 declare const createApiTransport: (config: ApiTransportConfig) => HolaTransport;
@@ -122,7 +131,7 @@ declare const useArtifactUrl: (dataBase64: string, mimeType: string) => string;
 
 /** A minimal, dependency-free chat surface for the employee. Drop it inside a
  *  `<HolaProvider>`. For custom UI, use `useChat(client)` directly. */
-declare const Chat: () => react_jsx_runtime.JSX.Element;
+declare const Chat: () => react.JSX.Element;
 
 type WidgetTransportConfig = {
     /** API origin that fronts the Holaboss employee endpoint, e.g. "https://api.holaos.ai". */
@@ -149,13 +158,6 @@ type CreateHolaClientOptions = WidgetTransportConfig | {
  *  agnostic — the current transport is an internal detail, not the SDK's identity. */
 declare const createHolaClient: (options: CreateHolaClientOptions) => HolaClient;
 
-/** Extract a streamed text delta from a raw pi turn event, or null. */
-declare const textDeltaOf: (event: unknown) => string | null;
-/** Extract a streamed reasoning delta from a raw pi turn event, or null. */
-declare const thinkingDeltaOf: (event: unknown) => string | null;
-/** Extract a tool-execution start/end from a raw pi turn event, or null. */
-declare const toolEventOf: (event: unknown) => HolaToolEvent | null;
-
 /** A column, as the company defined it. */
 type PortalField = {
     key: string;
@@ -174,11 +176,22 @@ type PortalTable = {
     writable_fields: string[];
     row_count: number;
 };
+/** Who last wrote a row. `employee` is the company's AI employee, `org_member` its
+ *  staff, `end_user` this customer. Null on rows written before the platform
+ *  recorded it — unknown rather than assumed. */
+type PortalRowAuthor = {
+    kind: "org_member" | "employee" | "end_user";
+    id: string | null;
+};
 type PortalRow = {
     rowId: string;
     data: Record<string, unknown>;
     createdAt: string;
     updatedAt: string;
+    /** Bumped on every write. Quote it back on a patch (`If-Match`) and a save made
+     *  against a value that has since moved is refused instead of overwriting it. */
+    revision: number;
+    updatedBy: PortalRowAuthor | null;
 };
 type PortalRowPage = {
     rows: PortalRow[];
@@ -235,8 +248,14 @@ type PortalData = {
     insertRow(slug: string, row: Record<string, unknown>): Promise<string>;
     /** Pass an empty string to clear a field. */
     patchRow(slug: string, rowId: string, patch: Record<string, unknown>): Promise<number>;
-    /** Only what the company allows a customer to delete, and only when nothing
-     *  depends on it. Rejects with the reason otherwise. */
+    /**
+     * Only what the company allows a customer to delete, and only when nothing
+     * depends on it. Rejects with the reason otherwise.
+     *
+     * Genuinely any table: which ones are deletable, and what holds a row back, is
+     * declared in the company's own schema rather than known to the platform. This
+     * used to look general and answer for two hard-coded slugs.
+     */
     deleteRow(slug: string, rowId: string): Promise<number>;
     /** Everything exchanged with this customer, newest first. */
     listFiles(): Promise<PortalFile[]>;
@@ -279,12 +298,477 @@ type PortalData = {
 };
 declare const createPortalData: (config: ApiTransportConfig) => PortalData;
 
+/** Build a `PortalField[]` from a slice's rows, typed by the dominant JSON value type per key.
+ *  `select` is never inferred (it needs an option set only a template carries) — such columns fall
+ *  back to `text`. Returns [] for an empty slice. */
+declare function deriveFields(rows: readonly {
+    data: Record<string, unknown>;
+}[]): PortalField[];
+
+/** How a metric column is reduced to a single number. */
+type Agg = "sum" | "avg" | "count" | "min" | "max" | "last";
+type WidgetType = "stat" | "line" | "bar" | "donut" | "table" | "text";
+/** A headline number: one metric reduced by `agg` (omit `metric` to count the rows). */
+interface StatWidget {
+    type: "stat";
+    /** Which table to read. Absent = the dashboard's primary table. See `Widget.source`. */
+    source?: string | undefined;
+    label?: string | undefined;
+    metric?: string | undefined;
+    agg?: Agg | undefined;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+}
+/** A time series: `y` (a numeric column) aggregated per day of `x` (a date column); omit `y` to count
+ *  rows per day. `line` and `bar` differ only in how the renderer draws the same points. */
+interface SeriesWidget {
+    type: "line" | "bar";
+    /** Which table to read. Absent = the dashboard's primary table. See `Widget.source`. */
+    source?: string | undefined;
+    title?: string | undefined;
+    x: string;
+    y?: string | undefined;
+    agg?: Agg | undefined;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+}
+/** A breakdown per distinct value of `groupBy`.
+ *
+ *  `metric` + `agg` say WHAT is measured for each group; omit `metric` and it counts rows, which was
+ *  the only thing this could do and stays the default — every donut authored before this renders
+ *  identically. With one, "how many newsletters per status" becomes "how many RECIPIENTS per
+ *  status", which is usually the number the dashboard exists to show. */
+interface DonutWidget {
+    type: "donut";
+    /** Which table to read. Absent = the dashboard's primary table. See `Widget.source`. */
+    source?: string | undefined;
+    title?: string | undefined;
+    groupBy: string;
+    metric?: string | undefined;
+    agg?: Agg | undefined;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+}
+/** A row table: `columns` (by key, in order) or every non-plumbing column when omitted. */
+interface TableWidget {
+    type: "table";
+    /** Which table to read. Absent = the dashboard's primary table. See `Widget.source`. */
+    source?: string | undefined;
+    title?: string | undefined;
+    columns?: string[] | undefined;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+}
+/** Static prose — a note above or between the data widgets. */
+interface TextWidget {
+    type: "text";
+    title?: string | undefined;
+    body: string;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+}
+/**
+ * `source` — which table a widget reads.
+ *
+ * One dashboard, many tables: a service's work items, its spend, a channel breakdown. Absent means
+ * the primary table, which is what every spec authored before this said implicitly, so an old spec
+ * keeps rendering unchanged. The renderer supplies the named tables; a widget naming one it was not
+ * given is dropped rather than silently redrawn against the primary — a chart of the wrong table is
+ * worse than no chart, because it looks right.
+ */
+type Widget = StatWidget | SeriesWidget | DonutWidget | TableWidget | TextWidget;
+interface DashboardSpec {
+    version: number;
+    title?: string | undefined;
+    widgets: Widget[];
+}
+/** Parse a service's stored dashboard spec (a JSON string or an already-parsed object). Returns null
+ *  for anything that isn't a usable spec — empty, absent, garbled, or with no valid widgets — so the
+ *  caller falls back to inference instead of showing a blank dashboard. */
+declare function parseDashboardSpec(raw: unknown): DashboardSpec | null;
+
+declare function inferSpec(fields: PortalField[], rows: PortalRow[]): DashboardSpec;
+
+/** A point on a line/bar chart or a slice of a donut. */
+interface Point {
+    label: string;
+    value: number;
+}
+/** A widget resolved against the data — everything a renderer needs, already computed. */
+type ResolvedWidget = {
+    kind: "stat";
+    label: string;
+    value: number;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+} | {
+    kind: "series";
+    draw: "line" | "bar";
+    title: string;
+    points: Point[];
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+} | {
+    kind: "donut";
+    title: string;
+    points: Point[];
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+} | {
+    kind: "table";
+    title?: string | undefined;
+    columns: PortalField[];
+    rows: PortalRow[];
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+} | {
+    kind: "text";
+    title?: string | undefined;
+    body: string;
+    w?: number | undefined;
+    h?: number | undefined;
+    gx?: number | undefined;
+    gy?: number | undefined;
+};
+/** One table a dashboard can draw from. */
+interface DataSource {
+    fields: PortalField[];
+    rows: PortalRow[];
+}
+/**
+ * Resolve a whole spec against the data. The result is render-ready and free of widgets that would
+ * draw nothing.
+ *
+ * `fields`/`rows` are the PRIMARY source — what a widget binds to when it names none, and what every
+ * dashboard used to be limited to. `others` adds further tables by name, which is what lets one
+ * dashboard mix them: a widget's `source` picks which table it reads, so the posts chart and the
+ * spend stat can sit on the same canvas over different data.
+ *
+ * A widget naming a source we were not given is DROPPED, like any other widget that would draw
+ * nothing. Falling back to the primary would be worse than silence: it would draw a real chart, with
+ * a plausible shape, of the wrong table.
+ */
+declare function renderModel(spec: DashboardSpec, fields: PortalField[], rows: PortalRow[], others?: Record<string, DataSource>): ResolvedWidget[];
+
+type Band = "stat" | "chart" | "block";
+type StatView = Extract<ResolvedWidget, {
+    kind: "stat";
+}>;
+type ChartView = Extract<ResolvedWidget, {
+    kind: "series" | "donut";
+}>;
+/** The dashboard grid is a fixed 6 columns wide, at every width. */
+declare const GRID_COLS = 6;
+declare const GRID_MAX_COLS = 6;
+declare const GRID_MAX_ROWS = 4;
+/** The band a resolved widget belongs to. */
+declare function bandOfKind(kind: ResolvedWidget["kind"]): Band;
+/** The band a spec widget TYPE belongs to — for the editor, which lays out widgets before they resolve
+ *  (a half-configured widget still needs a cell). Mirrors bandOfKind. */
+declare function bandOfType(type: WidgetType): Band;
+/** A band's default cell size. */
+declare function footprintOf(band: Band): {
+    w: number;
+    h: number;
+};
+/** A widget's effective cell size: its stored `w`×`h` (clamped to the grid), else the band default.
+ *  The renderers and the editor both size cells through this, so a widget looks the same everywhere. */
+declare function footprintWith(band: Band, w: number | undefined, h: number | undefined): {
+    w: number;
+    h: number;
+};
+/** A widget placed on the grid — the view-model plus its top-left cell and size in cells. */
+interface PlacedWidget {
+    widget: ResolvedWidget;
+    gx: number;
+    gy: number;
+    w: number;
+    h: number;
+}
+/** Place every widget on the fixed grid: honor its stored `gx`/`gy` when set (and free), else auto-
+ *  place it first-fit (top-to-bottom, left-to-right) at its footprint. Deterministic + collision-free,
+ *  so a legacy spec (no positions) and a positioned one both render stably, and a stale position that
+ *  now overlaps (e.g. after a neighbour grew) falls back to a free slot instead of stacking. */
+declare function placeWidgets(resolved: ResolvedWidget[]): PlacedWidget[];
+/** A dashboard split into the two things that lay out differently: square TILES (stats + charts) that
+ *  pack into the fixed grid, and full-width BLOCKS (tables + notes) that stack UNDER the grid at their
+ *  content height. A table's height depends on its rows, not the column width, so it can't share the
+ *  square-cell grid without leaving slack — it flows below instead, exactly as tall as its content. */
+interface DashboardLayout {
+    /** Stats + charts, placed on the fixed grid. */
+    tiles: PlacedWidget[];
+    /** Tables + notes, full-width and content-height, in spec order (top to bottom). */
+    blocks: ResolvedWidget[];
+}
+/** Split resolved widgets into grid tiles and stacked full-width blocks (see {@link DashboardLayout}).
+ *  Every surface (portal, console) renders these the same way, so a dashboard reads identically. */
+declare function splitLayout(resolved: ResolvedWidget[]): DashboardLayout;
+
+type DeliverableItemKind = "file" | "link" | "text" | "table";
+type DeliverableItem = {
+    kind: DeliverableItemKind;
+    value: string;
+    /** Version this item was delivered in, numbered from 1 (absent = v1). */
+    v?: number;
+};
+/** One delivered version — a bundle of items sent together, numbered from 1. */
+type DeliverableVersion = {
+    v: number;
+    items: DeliverableItem[];
+};
+declare function normalizeDeliverableItem(x: unknown): DeliverableItem | null;
+declare function groupDeliverableVersions(items: DeliverableItem[]): DeliverableVersion[];
+/** Parse a deliverable row's items from its `data`. Tolerant of the legacy single `file` field and of
+ *  bare-string refs; returns [] when there is nothing. */
+declare function parseDeliverableItems(data: Record<string, unknown>): DeliverableItem[];
+type DeliverableReviewState = "awaiting" | "accepted" | "revise";
+declare function deliverableStatus(items: DeliverableItem[], publishedVersion: number, verdictById: Map<string, string>, 
+/** The client's verdict on the delivered TABLE (from the deliverable's response), if any. */
+tableVerdict?: "" | "accepted" | "revise"): DeliverableReviewState;
+/** The version the client currently sees — the EXPLICIT `published_version` pointer the operator set
+ *  (0 = nothing published). No `done → latest` fallback: that followed the latest version, so a new
+ *  version the team delivered would auto-appear to the client before it was published. */
+declare function publishedVersionOf(data: Record<string, unknown>): number;
+
+/** A column type. `select` is an open enum edited as text; the rest drive how a cell reads. */
+type DeliverableColType = "text" | "number" | "url" | "date" | "boolean" | "select";
+type DeliverableColumn = {
+    key: string;
+    label: string;
+    type: DeliverableColType;
+    /** The customer may fill this column in from their portal — their values live in the deliverable's
+     *  `responses`, layered over the operator's cells. Absent = read-only (the default). */
+    clientEditable?: boolean;
+};
+type DeliverableRow = {
+    id: string;
+    cells: Record<string, unknown>;
+};
+type DeliverableTable = {
+    /** The operator's name for this table (e.g. "Twitter influencers"). Optional for older payloads. */
+    name?: string;
+    columns: DeliverableColumn[];
+    rows: DeliverableRow[];
+};
+/** Legacy tables used `link`/`checkbox`; the current vocabulary is `url`/`boolean`. */
+declare function normalizeDeliverableColType(t: unknown): DeliverableColType;
+/** Parse a table item's JSON `value` into the grid model, tolerating the legacy id-keyed shape (its
+ *  columns carried `id` not `key`, so a legacy column keeps its cells by keying on that id). Returns
+ *  null when `value` is not a table payload. */
+declare function parseDeliverableTable(value: string): DeliverableTable | null;
+/** A cell value as display text (a stored null/undefined reads as empty). */
+declare function deliverableCellText(v: unknown): string;
+/** Whether a `boolean` cell is checked — tolerant of a real boolean or the string forms it was stored
+ *  as across versions. */
+declare function isDeliverableChecked(v: unknown): boolean;
+type TableReviewVerdict = "" | "accepted" | "revise";
+type TableResponses = {
+    /** The client's edits to client-editable columns: rowId → columnKey → value. */
+    cells: Record<string, Record<string, unknown>>;
+    /** The client's review of the table — empty until they submit. */
+    verdict: TableReviewVerdict;
+    /** The client's comment when sending back (or a note on approve). */
+    comment: string;
+};
+declare function emptyTableResponses(): TableResponses;
+/** Parse a deliverable's `responses` field (client_tasks.responses). Tolerant of the legacy bare
+ *  rowId→colKey map (read as edits with no review yet). */
+declare function parseTableResponses(value: unknown): TableResponses;
+/** The value to SHOW for a cell: the customer's edit on a client-editable column, else the operator's
+ *  authored value. */
+declare function cellValue(col: DeliverableColumn, row: DeliverableRow, responses: TableResponses): unknown;
+/** Merge one client cell edit into a response (immutably) — for the client's local draft. */
+declare function setResponse(responses: TableResponses, rowId: string, colKey: string, value: unknown): TableResponses;
+/** Set the review verdict + comment (immutably) — for the submit (approve / send back) action. */
+declare function setTableReview(responses: TableResponses, verdict: TableReviewVerdict, comment: string): TableResponses;
+/** A `date` cell stores YYYY-MM-DD; format it as e.g. "Aug 18, 2026" (raw string if unparseable). */
+declare function formatDeliverableDate(v: string): string;
+
+/** Extract a streamed text delta from a raw pi turn event, or null. */
+declare const textDeltaOf: (event: unknown) => string | null;
+/** Extract a streamed reasoning delta from a raw pi turn event, or null. */
+declare const thinkingDeltaOf: (event: unknown) => string | null;
+/** Extract a tool-execution start/end from a raw pi turn event, or null. */
+declare const toolEventOf: (event: unknown) => HolaToolEvent | null;
+
+type PortalShopConfig = {
+    /** API origin, e.g. "https://api.holaos.ai" — or empty for a portal whose own worker answers
+     *  `/api/v1/end-user/…` same-origin, which is how the iMerch template is wired. */
+    baseUrl: string;
+    /**
+     * The tenant's publishable key, which is the whole of the authentication here.
+     *
+     * A plain string rather than the getter `ApiTransportConfig.token` takes: an end-user token
+     * refreshes and a publishable key does not — it is baked into the page source a visitor can read,
+     * which is what makes it publishable. There is deliberately no token field on this config at all,
+     * so nothing in a storefront can come to depend on being signed in to browse.
+     */
+    publishableKey: string;
+};
+/** How a product is taken: `buy` charges for it, `ask` opens the conversation the customer already
+ *  has with the company, `apply` posts the form `apply()` sends. */
+type ShopMode = "buy" | "ask" | "apply";
+/**
+ * What a product costs — exactly one of four shapes, never two.
+ *
+ * The number is in whatever unit the OPERATOR prices in: credits for an org that sells them, money
+ * for one that does not — and the wire says which, on `ShopProduct.currency` beside this. It used
+ * to say otherwise, that the figure travelled bare and the unit "belongs to the template that knows
+ * the tenant", which was how this contract was written before `pricing_unit` existed and was false
+ * the day the server started sending the field. A template built on that sentence prints a
+ * hardcoded `$` in front of a credit price — wrong by the whole book rate. Nothing here should ever
+ * print a `$` it did not read off `currency`.
+ *
+ * `quoted` is not a price. It is the honest answer for everything in a real catalogue that reads
+ * `5k – 10k`, `20k+` or 待定 — a statement that a human has to quote this. Render it as words, and
+ * never behind a Buy button that cannot compute a total.
+ */
+type ShopPricing = {
+    kind: "flat";
+    price: number;
+} | {
+    kind: "per_unit";
+    unit: string;
+    unitPrice: number;
+    unitStep: number;
+} | {
+    kind: "variants";
+    variants: {
+        name: string;
+        price: number | null;
+    }[];
+} | {
+    kind: "quoted";
+};
+/** One part of a bundle, as the shelf is allowed to describe it: what it is called, what it covers,
+ *  how long it runs — and no price, for the reason at the top of this file. */
+type ShopInclusion = {
+    name: string;
+    content?: string;
+    period?: string;
+};
+/** A named tier — 基础 / 标准 / 高阶 — and what it covers. Its PRICE is not here: it is in
+ *  `pricing` (`kind: "variants"`), matched to this by name, so that there is one place the money
+ *  comes from and no way for the two to disagree. */
+type ShopVariant = {
+    name: string;
+    includes: ShopInclusion[];
+};
+/** One product as a visitor sees it. */
+type ShopProduct = {
+    id: string;
+    name: string;
+    summary: string;
+    description: string;
+    /**
+     * One of `ShopMode` for anything authored in the console — but typed as the string it is on the
+     * wire, because the server sends the row's own value and a product from before the field existed
+     * answers `""`. A storefront that switched over the union would be handed a value the type swore
+     * could not occur, so match the three and keep a default arm.
+     */
+    mode: string;
+    category: string;
+    platform: string;
+    cadence: string;
+    period: string;
+    /** Image URLs for the card and the product page; empty when the operator set none. */
+    media: string[];
+    pricing: ShopPricing;
+    /** What THIS product's numbers are in — an ISO code, or the literal "credits". It sits on the
+     *  product rather than on the shelf because a shelf can be mixed: once an org sells credits, its
+     *  buyable products are priced in them while a 20k engagement it merely quotes stays in money.
+     *  Empty from a backend older than the field, which is a shelf that has not SAID — and is not the
+     *  same as one that said dollars, so print the bare figure rather than guessing a symbol. */
+    currency: string;
+    /** Bounds on a per-unit purchase, when the product states them. Public because the quantity
+     *  picker has to honour them — a customer who meets a limit they were never shown reads it as a
+     *  broken shop. */
+    minQty?: number;
+    maxQty?: number;
+    includes: ShopInclusion[];
+    /** Present only where the tiers differ in scope; a product without them has one implicit tier,
+     *  which is its own `pricing` and its own `includes`. */
+    variants?: ShopVariant[];
+};
+type ShopShelf = {
+    products: ShopProduct[];
+    /**
+     * The catalogue is bigger than what came back.
+     *
+     * Kept rather than dropped for the reason `listRows` returns a page: the server caps a shelf read,
+     * and a shop that quietly ends at the cap is a customer who cannot see half of it and nobody who
+     * can tell. The same argument the server makes when it bothers to send the flag.
+     */
+    truncated: boolean;
+};
+/** An application against a product, or against nothing in particular — a general enquiry that
+ *  names no product is a real thing to receive, so `productId` is optional. */
+type ShopApplication = {
+    name: string;
+    /**
+     * Where the operator answers. Required, and checked by the server — but a malformed one is
+     * dropped SILENTLY (see `apply` below), so a form that wants to tell someone their address is
+     * wrong has to say so itself, before it sends.
+     */
+    email: string;
+    phone?: string;
+    message?: string;
+    productId?: string;
+};
+/** The one answer every application gets. See `apply` for why it never varies. */
+type ShopApplyResult = {
+    /**
+     * Always `true` — including for a submission that was dropped. It is a receipt that the request
+     * was accepted, never evidence that a row exists.
+     */
+    ok: boolean;
+    /** The server's own thank-you line. Shown as sent rather than reworded, so the operator's copy is
+     *  the copy the applicant reads. */
+    message: string;
+};
+type PortalShop = {
+    /** Everything on sale, in the operator's own order. Listed products only — a draft is something
+     *  still being written and an archived one is off sale but kept because orders point at it. */
+    listProducts(): Promise<ShopShelf>;
+    /**
+     * Send an application. No account, no session — this is the one write on the platform a total
+     * stranger can make.
+     *
+     * It answers the SAME "thanks, we have your details" to an unknown key, a body that did not
+     * parse and a write that failed as it does to an application that landed, and that is deliberate:
+     * anything else would turn this into a way to ask which publishable keys reach a real company —
+     * and, once signups are invite-only, which addresses one already has. The cost is that a
+     * miswired form gets a cheerful reply and files nothing, so when applications are not arriving,
+     * the answer is in the operator's server logs and cannot be here.
+     */
+    apply(application: ShopApplication): Promise<ShopApplyResult>;
+};
+declare const createPortalShop: (config: PortalShopConfig) => PortalShop;
+
 /** Provides a `HolaClient` (from `createHolaClient`) to `useChat` / `<Chat/>`.
  *  Create the client once (e.g. `useMemo`) so its session persists across renders. */
 declare const HolaProvider: ({ client, children, }: {
     client: HolaClient;
     children: ReactNode;
-}) => react_jsx_runtime.JSX.Element;
+}) => react.JSX.Element;
 declare const useHolaClient: () => HolaClient;
 
 type ChatMessage = {
@@ -305,6 +789,30 @@ type UseChat = {
 /** Chat state for one employee client: greeting, message list, streaming send. */
 declare const useChat: (client: HolaClient) => UseChat;
 
+type UseShop = {
+    products: ShopProduct[];
+    /** In flight — the first read, and every `reload`. The products from the previous read stay put
+     *  underneath it, so a refresh does not blank a shop that is already on screen. */
+    loading: boolean;
+    /** The catalogue is bigger than `products`; the server capped the read. */
+    truncated: boolean;
+    /** Why the last read failed, as the SDK's own code — `rate_limited` is the one worth wording
+     *  differently, since it is the only failure that fixes itself. */
+    error: string | null;
+    reload: () => void;
+};
+/**
+ * The public shelf, loaded on mount.
+ *
+ * Hold `shop` still: build it once at module scope, the way a portal builds its client (`export
+ * const holaShop = createPortalShop(config)`), and hand the same object in on every render. A
+ * `createPortalShop({...})` written inside the component body is a new object each time, and since
+ * that identity is what this re-reads on, the storefront would fetch its own shelf in a loop —
+ * against a route that is rate-limited per visitor, so the shop would end up empty for the person
+ * least at fault.
+ */
+declare const useShop: (shop: PortalShop) => UseShop;
+
 /** A thread message; `pending` marks an optimistic echo of the visitor's own send, shown
  *  instantly and replaced by the authoritative message when the receive channel delivers it. */
 type ThreadMessage = HolaMessage & {
@@ -318,9 +826,6 @@ type UseThread = {
     sending: boolean;
     error: string | null;
 };
-/** Merge one incoming thread message: dedupe by id, and replace a pending optimistic echo of the
- *  visitor's own send (same text) with the authoritative one. Pure — the hook's core, so the
- *  merge rule is unit-checkable without React. */
 declare function mergeMessage(list: ThreadMessage[], incoming: HolaMessage): ThreadMessage[];
 /** A poll-based UNIFIED thread: the whole conversation — visitor, agent, and HUMAN turns — as one
  *  live list via the receive channel (`client.subscribe`). Unlike `useChat` (streaming, one turn
@@ -331,4 +836,4 @@ declare const useThread: (client: HolaClient, options?: {
     pollMs?: number;
 }) => UseThread;
 
-export { type ApiTransportConfig, Chat, type ChatMessage, type CreateHolaClientOptions, type HolaArtifact, type HolaAuthor, type HolaClient, type HolaCompletion, type HolaEmployeeInfo, type HolaError, type HolaIdentity, type HolaMessage, HolaProvider, type HolaStreamHandlers, type HolaSubscribeHandlers, type HolaSubscribeOptions, type HolaToolEvent, type HolaTransport, PortalConflict, type PortalData, type PortalDocument, type PortalDocumentSummary, type PortalField, type PortalFile, type PortalRow, type PortalRowPage, type PortalTable, type ThreadMessage, type UseChat, type UseThread, type WidgetTransportConfig, createApiTransport, createHolaClient, createPortalData, createWidgetTransport, mergeMessage, textDeltaOf, thinkingDeltaOf, toolEventOf, useArtifactUrl, useChat, useHolaClient, useThread };
+export { type Agg, type ApiTransportConfig, type Band, type ChartView, Chat, type ChatMessage, type CreateHolaClientOptions, type DashboardLayout, type DashboardSpec, type DataSource, type DeliverableColType, type DeliverableColumn, type DeliverableItem, type DeliverableItemKind, type DeliverableReviewState, type DeliverableRow, type DeliverableTable, type DeliverableVersion, type DonutWidget, GRID_COLS, GRID_MAX_COLS, GRID_MAX_ROWS, type HolaArtifact, type HolaAuthor, type HolaClient, type HolaCompletion, type HolaEmployeeInfo, type HolaError, type HolaIdentity, type HolaMessage, HolaProvider, type HolaStreamHandlers, type HolaSubscribeHandlers, type HolaSubscribeOptions, type HolaToolEvent, type HolaTransport, type PlacedWidget, type Point, PortalConflict, type PortalData, type PortalDocument, type PortalDocumentSummary, type PortalField, type PortalFile, type PortalRow, type PortalRowAuthor, type PortalRowPage, type PortalShop, type PortalShopConfig, type PortalTable, type ResolvedWidget, type SeriesWidget, type ShopApplication, type ShopApplyResult, type ShopInclusion, type ShopMode, type ShopPricing, type ShopProduct, type ShopShelf, type ShopVariant, type StatView, type StatWidget, type TableResponses, type TableReviewVerdict, type TableWidget, type TextWidget, type ThreadMessage, type UseChat, type UseShop, type UseThread, type Widget, type WidgetTransportConfig, type WidgetType, bandOfKind, bandOfType, cellValue, createApiTransport, createHolaClient, createPortalData, createPortalShop, createWidgetTransport, deliverableCellText, deliverableStatus, deriveFields, emptyTableResponses, footprintOf, footprintWith, formatDeliverableDate, groupDeliverableVersions, inferSpec, isDeliverableChecked, mergeMessage, normalizeDeliverableColType, normalizeDeliverableItem, parseDashboardSpec, parseDeliverableItems, parseDeliverableTable, parseTableResponses, placeWidgets, publishedVersionOf, renderModel, setResponse, setTableReview, splitLayout, textDeltaOf, thinkingDeltaOf, toolEventOf, useArtifactUrl, useChat, useHolaClient, useShop, useThread };