@holaboss/client 0.2.0-beta.3 → 0.2.0-beta.30

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 = {
@@ -131,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". */
@@ -158,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;
@@ -183,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[];
@@ -244,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[]>;
@@ -288,14 +298,1033 @@ 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;
+
+/**
+ * A refusal this surface makes on purpose, carrying both halves of it.
+ *
+ * `toHolaError` reads only `.error` and `.retryable`, so routing these through it would keep the
+ * code and drop the sentence — and the sentence is the part worth showing. `insufficient_credits`
+ * NAMES THE SHORTFALL ("that costs 100 credits and you have 0; top up 100 more"), which is the whole
+ * of what the customer needs and strictly more than a portal could say for itself.
+ *
+ * The code is what a caller branches on, and the branches are not cosmetic: `insufficient_credits`
+ * is fixed by topping up, `stripe_not_connected` is the company's own setup and no amount of trying
+ * again will move it, `rate_limited` wants a pause, and a `pack_*` refusal means the list on screen
+ * is stale. Answering all of them with "please try again" is wrong for every one but the last.
+ */
+declare class CreditRefused extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+/** One pack on sale: what it grants, and what it costs in real money.
+ *
+ *  `credits` and `price` are different units and the pair is the point — 500 credits for $99 is a
+ *  rate, not a discount. `currency` belongs to the PRICE; the balance those credits land in is
+ *  denominated in credits and nothing else. */
+type CreditPack = {
+    packId: string;
+    name: string;
+    credits: number;
+    price: number;
+    currency: string;
+};
+/** A top-up started and not finished. */
+type PendingTopup = {
+    txnId: string;
+    credits: number;
+    packId: string | null;
+    /** The money is known to have arrived and only the grant is outstanding. The difference between
+     *  "we are waiting for you" and "we are waiting for us", which a customer should never have to
+     *  guess at. */
+    paid: boolean;
+    /** Where this top-up stands, as one value rather than two booleans a reader has to combine:
+     *  `waiting` on the customer, `paid` on the operator, `failed` on nobody — the payment was
+     *  declined and this is terminal. Absent from a backend older than the field, where the two
+     *  live states are all there were; treat a missing value as `paid ? "paid" : "waiting"`. */
+    state?: "waiting" | "paid" | "failed";
+    createdAt: string;
+    /** The server's own sentence for the state above. Rendered rather than re-derived: a second
+     *  account of it written portal-side is one that can disagree with the first. */
+    note: string;
+    /** Where to go to finish paying, when there is somewhere.
+     *
+     *  Stripe payment links neither expire nor refuse a second visit, so the one this top-up was
+     *  minted with is still good. Null once `paid` — the money is in, and a link back to a payment
+     *  page invites paying twice — and null for a top-up started before the link was recorded. */
+    resumeUrl?: string | null;
+};
+/** What the customer has, what they can buy, and what they have started. */
+type CreditWallet = {
+    balance: number;
+    packs: CreditPack[];
+    pending: PendingTopup[];
+    /** What the BALANCE is in, which is `credits` however the shelf happens to be priced. */
+    currency: string;
+    /** What one unit of currency is worth in credits on this company's books — 1 means 1 credit = $1.
+     *
+     *  Nominal by design: it is what values a credit-priced order on the operator's money surfaces,
+     *  NOT what any particular customer paid, because two customers can legitimately pay different
+     *  money for the same credit — that is what a volume bonus IS. So a portal may show the balance
+     *  in money beside it, and should not present that figure as what they spent. */
+    bookRate?: number;
+    /** Whether this company prices in credits AT ALL.
+     *
+     *  Ask this, never `packs.length`. An empty list is what a company selling for money gets (it is
+     *  never asked) and equally what a credits company that has not priced a pack yet gets — and a
+     *  portal reading the two as one hides its credits surface from the operator who has just turned
+     *  credits on and gone looking for it. Optional, so a portal pointed at a backend older than the
+     *  field still works; absent, the count is the only signal left. */
+    sellsCredits?: boolean;
+};
+/** One movement of the balance, with what it left the customer on. */
+type CreditEntry = {
+    id: string;
+    /** Signed: negative spent it, positive added to it. The sign IS the direction, so a portal never
+     *  has to decide which way a row goes from its reason. */
+    delta: number;
+    /** What they were on immediately AFTER this one — computed server-side by working backwards from
+     *  the current balance, so it cannot disagree with the number at the top of the page. */
+    balance: number;
+    /** Why: `topup`, `purchase`, or whatever an operator recorded by hand. */
+    reason: string;
+    /** The order this bought, when it bought one. Null for a top-up or an adjustment. */
+    orderId: string | null;
+    /** That order's name, when it still exists. Absent for a top-up, and absent for an order deleted
+     *  since — a ledger row for a purchase that happened is not made wrong by that, so it falls back
+     *  to a generic label rather than disappearing or showing a row id. */
+    orderName?: string;
+    createdAt: string;
+};
+/** What a balance has taken in and paid out over its whole life. Both POSITIVE — a customer reads
+ *  "spent 1,275", not "spent −1,275". */
+type CreditTotals = {
+    purchased: number;
+    spent: number;
+};
+type CreditHistory = {
+    entries: CreditEntry[];
+    totals: CreditTotals;
+    /** The same figure `wallet()` answers, returned here so a page drawing both cannot show two. */
+    balance: number;
+};
+/** A started top-up: where to pay, and what it will grant. */
+type TopupStarted = {
+    /** The Stripe payment link. It ends on Stripe's own confirmation page and never returns here, so
+     *  open it in a NEW TAB and leave the portal standing — and re-read the wallet when the customer
+     *  comes back, because the credits land on the webhook and not on their return. */
+    url: string;
+    txnId: string;
+    credits: number;
+    amount: number;
+    currency: string;
+    /** This handed back a link the customer already had rather than minting another. Not an error and
+     *  usually not worth saying out loud — the same tab opens either way. */
+    resumed?: boolean;
+};
+/** What a purchase comes back as. Every figure is the server's own: a quantity in the request is a
+ *  request and never a price, so the amount is recomputed from the product row. */
+type Purchased = {
+    /** The order the credits bought, ready to open at `/orders/:orderId`. */
+    orderId: string;
+    /** Credits actually taken, at the price the server recomputed. */
+    credits: number;
+    /** What is left afterwards. */
+    balance: number;
+    /** What the order is worth in money at the company's book rate — the figure that lands on the
+     *  operator's money surfaces. NOT what the customer paid: they paid credits. */
+    value: number;
+};
+/**
+ * What the customer agrees to pay, and when.
+ *
+ * Carried BY THE QUOTE rather than left to the order, because accepting a total without a schedule
+ * is half an agreement — nobody should discover "50% up front" after saying yes — and because it is
+ * what lets the order's payment rows be raised from something they have actually seen.
+ *
+ * MONEY, in the same unit `total` is. Not the shelf unit the LINES are priced in: the two travel
+ * together in one payload and telling them apart is the whole of what `QuotedLine.price` warns
+ * about below.
+ */
+type QuoteTerms = {
+    /** Taken before the work starts. The deposit IS the starting gun — nothing runs until it lands. */
+    upfront?: number;
+    /** Taken on delivery. ADVISORY: see `quoteSchedule`, which derives the balance as the remainder
+     *  instead, so what a customer is shown and what they are billed cannot drift apart. */
+    onDelivery?: number;
+    /** Anything the operator wants said about the schedule, in their own words. */
+    note?: string;
+};
+/**
+ * One service being quoted, as the customer may see it.
+ *
+ * An ALLOWLIST assembled server-side, field by field, and not a projection of the stored item. The
+ * durable shape behind it carries the INTERNAL checklist, the skill row ids and the dashboard spec
+ * in the same object as the customer-facing `deliverables` — so the rule is that a new field
+ * upstream stays invisible here until somebody adds it on purpose.
+ */
+type QuotedLine = {
+    name: string;
+    /** A line of scope in the operator's words. */
+    notes?: string;
+    /** Longer scope — what this service actually covers, when it needs a paragraph. */
+    content?: string;
+    /**
+     * MONEY, in the same unit `total` is — safe to print with a currency symbol.
+     *
+     * IT DID NOT USED TO BE. This was handed over in the org's SHELF unit (credits on a credits org)
+     * beside a `total` that was money, in a payload naming no unit at all, and no portal could fix
+     * that from where it stood: `5,000` next to `$8,000` reads as dollars and is wrong by the whole
+     * book rate. It is converted server-side now, where the rate lives, so one payload is in one
+     * unit.
+     *
+     * Absent is still a real answer and is NOT a price of 0 — work thrown in is an agreement like
+     * any other. The lines also need not add up to `total`: `total` wins, exactly as `orders.value`
+     * beats the sum of its services, because a bundle priced below its parts is a real deal.
+     */
+    price?: number;
+    /** "per month", "one-off" — how often this recurs, when it recurs. */
+    period?: string;
+    /** What they get: the client-visible deliverables this line buys. */
+    deliverables: string[];
+};
+/**
+ * The live quote on a 询单, or the fact that there isn't one.
+ *
+ * A UNION rather than a nullable object so "not quoted yet" cannot be read as "quoted at nothing".
+ * They are opposite states — one is the team still working, the other is an offer of an empty
+ * basket — and a portal that conflated them would put an Accept button under a quote nobody sent.
+ */
+type InquiryQuote = {
+    quoted: false;
+} | {
+    quoted: true;
+    /** THE VERSION IN THIS PAYLOAD, and the number `acceptInquiry` must be given. Once they have
+     *  accepted one it is that one — what somebody signed does not change because the operator
+     *  sent another afterwards — and until then it is the newest sent. */
+    version: number;
+    /** The newest version that EXISTS. Equal to `version` in the ordinary case; greater when they
+     *  accepted one and the operator has sent another since, which is the only way a portal can
+     *  know to say so. Never a thing to accept: `version` is what is on screen, and accepting
+     *  something nobody has read is the failure the whole scheme exists to prevent. */
+    latest: number;
+    sentAt: string;
+    lines: QuotedLine[];
+    /** MONEY, whatever the lines are priced in. The one figure to print as a price. */
+    total: number;
+    terms?: QuoteTerms;
+    /** Which version they have ALREADY accepted; 0 for none. So a reload after accepting shows
+     *  the agreement rather than the button again. `accepted === version` is the ordinary way a
+     *  portal knows it is looking at the contract rather than at an offer. */
+    accepted: number;
+};
+/** One line of the payment schedule: what is owed, and what it is called. */
+type QuoteScheduleLine = {
+    label: string;
+    amount: number;
+};
+/** The two labels the platform raises payment rows under. Stated here so a portal can show a
+ *  customer the SAME words before they accept that they will read on the bill afterwards — a
+ *  schedule that says "Deposit" and a bill that says "Pre-payment" is two documents about one
+ *  agreement, and the customer is the one left reconciling them. */
+declare const QUOTE_DEPOSIT_LABEL = "Pre-payment";
+declare const QUOTE_BALANCE_LABEL = "After-payment";
+/**
+ * The schedule a quote's terms come to, as lines. MONEY in, money out.
+ *
+ * THE BALANCE IS THE REMAINDER, never a second stated figure, and this is the reason the function
+ * exists rather than a portal reading `terms.upfront` and `terms.onDelivery` straight out. Those
+ * two are typed by a human into two boxes and do not have to add up to the contract; the server
+ * bills the remainder regardless. A portal printing both would show a customer a schedule that
+ * silently forgives or double-charges the difference against the bill they actually receive.
+ *
+ * It mirrors the server's own `scheduleFrom` deliberately — same clamp, same rounding, same labels
+ * — because the point is that the customer sees, before they say yes, exactly the lines that will
+ * be raised when they do. In the SDK for the reason `orderBilling` is: the second portal to write
+ * this by hand would inherit nothing the first one learned, and being subtly wrong here is money.
+ *
+ * No terms at all means the whole thing up front — the honest reading of "they agreed a price and
+ * said nothing about instalments", and it never bills more than the contract.
+ */
+declare function quoteSchedule(total: number, terms: QuoteTerms | undefined): QuoteScheduleLine[];
+type PortalCredits = {
+    /** Balance, packs and anything in flight — one call, because they are one question. A balance
+     *  without the packs cannot be acted on, and a balance without the pending top-ups looks wrong to
+     *  anyone who has just paid. */
+    wallet(): Promise<CreditWallet>;
+    /** Start buying a pack, by ID alone — the price is read from the pack row server-side, so there
+     *  is no amount here for a client to choose. */
+    topup(packId: string): Promise<TopupStarted>;
+    /** The ledger behind the balance. Its OWN call, not part of `wallet()`: the wallet is read on
+     *  every page that draws a balance, and hanging a fifty-row scan off it would make the cheapest
+     *  read on this surface the most expensive one. */
+    history(): Promise<CreditHistory>;
+    /**
+     * Buy something from the shelf.
+     *
+     * NOT a redirect. On a credits shelf the money moved at the top-up, so this is a synchronous
+     * debit: it takes the credits, writes the order and its services, and answers `Purchased`.
+     *
+     * Refuses with `insufficient_credits` when they cannot cover it, and that refusal names the
+     * shortfall — it is the one message worth showing verbatim, because "not enough credits" is all a
+     * portal could say for itself.
+     */
+    checkout(purchase: {
+        productId: string;
+        variant?: string;
+        qty?: number;
+    }): Promise<Purchased>;
+    /**
+     * Ask for a quote on an `ask` product — the other way a shelf turns into an order.
+     *
+     * Writes a real order in `ask` status carrying these answers, with no services, no value and
+     * nothing running: the brief, waiting to be priced. Send the KEYS the product's `form` declares;
+     * the labels are read from the product row server-side, so a client cannot restate the question
+     * it is answering.
+     *
+     * On this surface rather than the shelf's for the same reason `checkout` is: an order belongs to
+     * somebody, so it takes the customer's bearer. (The public shelf's `apply` is the stranger's
+     * door, and it leaves an inquiry instead — there is no customer to write an order against.)
+     */
+    /** Raise a 询单 on an `ask` product. Returns the inquiry it created, so the caller can open it.
+     *
+     *  It used to return `orderId`: an enquiry wrote an ORDER in `ask` status, which was the wrong
+     *  object — an order with no money, no services and no agreed price, and a dead row in the
+     *  customer's order list for every quote that went nowhere. */
+    enquire(
+    /** The `ask` product this is about. EMPTY for a 询单 raised about something that is not on the
+     *  shelf — "can you also do X", which is how most of them start. */
+    productId: string, answers: {
+        key: string;
+        value: string;
+    }[], 
+    /** What THEY say they need, in their words. Required when `productId` is empty and ignored when
+     *  it is not: a product's own name is snapshotted server-side so a later rename cannot rewrite
+     *  what somebody asked for. */
+    name?: string): Promise<{
+        inquiryId: string;
+        name: string;
+    }>;
+    /**
+     * The quote on a 询单: the services being offered, at the prices being offered.
+     *
+     * ITS OWN ROUTE, not a field on the inquiry row, and that is load-bearing rather than tidy. The
+     * spine's read permission is per TABLE and never per column, so a basket parked on the
+     * externally-visible `inquiries` row would hand the customer the internal checklist, the skill
+     * row ids and the dashboard spec along with their price. The server reads it as the org and
+     * projects an allowlist; there is one door, and `QuotedLine` is the whole of what fits through it.
+     *
+     * `{quoted: false}` is a REAL answer and not an error — nobody has sent anything yet, which is
+     * what a portal draws "we're working on your proposal" from. It is also what an inquiry quoted
+     * the old way answers, so a portal reading this keeps working against one.
+     *
+     * WHAT THEY SIGNED WINS over what has been sent since: once a version is accepted this returns
+     * THAT one, with `latest` naming the newest that exists. Before, it always returned the newest
+     * and left `accepted` as a bare number — so a customer whose operator revised after they said
+     * yes had a screen that knew which version was the contract and displayed a different one.
+     */
+    inquiryQuote(inquiryId: string): Promise<InquiryQuote>;
+    /**
+     * Accept the quote on a 询单 — and, when there is one, get the order written from it.
+     *
+     * THE VERSION IS REQUIRED, and deliberately not defaulted to the latest. Defaulting would make
+     * the stale case unrepresentable: a tab left open on v1 would silently agree to whatever price is
+     * current, which is the exact failure versioning exists to prevent. Pass the `version` off the
+     * quote that was actually on screen; pass 0 for an inquiry with no quote, which keeps today's
+     * behaviour (it moves to `accepted` and the operator writes the order by hand).
+     *
+     * Idempotent — `changed: false` means they had already accepted, which is what a double-tap on a
+     * slow connection looks like and is not an error.
+     *
+     * Refuses with `CreditRefused`, and the code says which of three things happened. Each wants a
+     * different sentence, which is why they are three:
+     *
+     * - `quote_revised` — the version is no longer the current one. The ONLY correct response is to
+     *   re-read `inquiryQuote` and show what came back: retrying with the version named in the
+     *   refusal is the stale accept again, one round trip later. (Which is why that number is not
+     *   surfaced here — the re-read answers it, and answers it as of now rather than as of then.)
+     * - `not_quoted` — nobody has sent anything. There is nothing to accept, and there is nothing
+     *   for the customer to do but wait.
+     * - `inquiry_closed` — it is already closed, or already an order. Someone else moved it, so the
+     *   page should re-read rather than argue.
+     */
+    acceptInquiry(inquiryId: string, version: number): Promise<{
+        status: string;
+        changed: boolean;
+    }>;
+    /** Every payment on this customer's orders, due and paid both — what they owe, on what, and by
+     *  when. Join to an order on `order`.
+     *
+     *  On this surface rather than portal-data because it is NOT a table read: `payments` is not
+     *  externally visible, and the server projects an allowlist of bill fields off the row. */
+    payments(): Promise<{
+        payments: CustomerPayment[];
+    }>;
+    /** How this company takes a bank transfer. `null` when they publish no details — Stripe is not
+     *  the only way money moves, and for an operator banking with Mercury it is not a way at all. */
+    paymentMethods(): Promise<{
+        transfer: TransferDetails | null;
+    }>;
+    /** "I've sent the transfer." Records the customer's claim against one payment and puts it on the
+     *  operator's desk to confirm against the account.
+     *
+     *  It does NOT settle the payment, and a portal must not present it as though it does: work
+     *  starts on payment, and a claim is not a receipt. `claimed: false` with `status: "paid"` means
+     *  the operator had already confirmed it. */
+    markPaymentSent(paymentId: string, reference?: string): Promise<{
+        claimed: boolean;
+        status: string;
+    }>;
+};
+/** One line on a customer's bill. Mirrors the projection holaapp-backend's `customerPayment`
+ *  emits — an allowlist, not the stored row. */
+type CustomerPayment = {
+    id: string;
+    /** The order this runs against. */
+    order: string;
+    /** "Pre-payment", "After-payment", "Paid in full" — whatever the operator labelled it. */
+    label: string;
+    amount: number;
+    /** Anything the server could not read as `paid` comes back as `due`. */
+    status: "due" | "paid";
+    method: string;
+    dueDate: string;
+    paidAt: string;
+    /** Where to pay this online, when the money can be taken that way. Empty for a bank transfer,
+     *  which is not a link but a set of details plus a person confirming it arrived. */
+    payUrl: string;
+    /** When the customer said they had sent it — their claim, not a receipt. Set by `markPaymentSent`
+     *  and cleared by nothing: it is the record of what was said, and the operator confirming the
+     *  money is what changes `status`. */
+    claimedAt: string;
+    reference: string;
+};
+/** How to pay this company by transfer. Null when the operator has published nothing you could
+ *  actually send money to — no details is not an empty form, it is no transfer option. */
+type TransferDetails = {
+    bank: string;
+    accountName: string;
+    accountNumber: string;
+    routing: string;
+    swift: string;
+    note: string;
+};
+/** Where one order stands financially, and therefore whether it has started. */
+type OrderBilling = {
+    /** The agreed contract value. 0 when nobody priced it — not the same as free, which is what
+     *  `priced` is for. */
+    value: number;
+    priced: boolean;
+    /** Raised against this order, settled or not. Can exceed `value` on a renegotiated one: it is a
+     *  record of what was billed, not a derivation of the contract. */
+    billed: number;
+    paid: number;
+    /** Still owed. Falls back to the whole contract value when the order is priced but no line has
+     *  been raised yet — the ordinary case the moment an order is written, where the customer is owed
+     *  a figure rather than a shrug. Never negative. */
+    due: number;
+    /** The lines, what is owed first. */
+    lines: CustomerPayment[];
+    /**
+     * Whether the work is waiting on money — and so has not started.
+     *
+     * PRICED AND NOTHING PAID. Not "billed and unsettled", which is wrong in the ordinary case: an
+     * order is written with a value and no payment lines until somebody raises one, so a customer
+     * looking at a fresh contract would be told it was under way while the operator's console badged
+     * it Unpaid. This matches the operator side's rule exactly — any PAID line means started — which
+     * is what stops the two describing one order in opposite terms.
+     */
+    awaitingPayment: boolean;
+};
+/**
+ * Fold an order's payment lines into where it stands.
+ *
+ * In the SDK rather than in each portal for the reason the whole of this file is: every portal that
+ * shows a bill needs exactly this, and the second one to write it by hand would inherit nothing the
+ * first one learned. Pure, so the arithmetic that decides whether somebody is told "this hasn't
+ * started" is testable without a server.
+ */
+declare const orderBilling: (order: {
+    value: number;
+}, all: CustomerPayment[], orderId: string) => OrderBilling;
+declare const createPortalCredits: (config: ApiTransportConfig) => PortalCredits;
+
+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";
+/**
+ * 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. */
+/** One question an `ask` product asks before it can be quoted. Authored by the operator on the
+ *  product row; the storefront draws it and sends back answers keyed to it. */
+type ShopFormField = {
+    key: string;
+    label: string;
+    type: "text" | "textarea" | "number" | "date" | "select";
+    required?: boolean;
+    options?: string[];
+    help?: string;
+};
+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[];
+    /** The enquiry form, on an `ask` product only. Never empty when present — a product that asks
+     *  nothing still gets one box, because a Send button over nothing collects an enquiry that says
+     *  only that somebody was interested. Absent on `buy` and `apply`, which are not asked. */
+    form?: ShopFormField[];
+    /** 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;
+    /** What an enquiry with NO product asks — "can you also do X", which has no product row to carry
+     *  questions. The operator's own defaults; empty when they have set none, which a storefront
+     *  reads as one box ("What do you need?"). A product's `form` is already resolved against these
+     *  server-side, so a card never has to merge the two itself. */
+    enquiryForm: ShopFormField[];
+};
+/** 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;
 
+/**
+ * How this product is taken.
+ *
+ * The wire carries the row's own value rather than the union, because a product authored before
+ * the field existed answers `""`. A shelf that switched on the three names and fell through would
+ * render a product with no action at all, so an unrecognised mode becomes `ask`: it is the one
+ * path that needs no money, writes nothing, and always has somebody at the other end of it.
+ */
+declare function modeOf(product: ShopProduct): ShopMode;
+/** The price that applies once a tier has been chosen. A tiered product is not a price until then;
+ *  every other shape already was one. */
+type ChosenPrice = {
+    kind: "flat";
+    price: number;
+} | {
+    kind: "per_unit";
+    unit: string;
+    unitPrice: number;
+    unitStep: number;
+} | {
+    kind: "quoted";
+};
+/**
+ * The figure the shelf carries, printed in the unit the ORG prices in.
+ *
+ * `currency` comes off the shelf payload and from nowhere else. It used to be a line of portal
+ * config on the portal itself, which is a portal guessing at somebody else's rate card: the
+ * numbers belong to the org and so does what they MEAN, and those two travelling separately is how
+ * a catalogue ends up wrong by an exchange rate. An ISO code prints money; the literal "credits"
+ * prints credits, which is the other unit an operator can price in.
+ *
+ * A shelf that names no unit prints the bare figure. That is a backend older than the field, and an
+ * ambiguous number is a far smaller lie than a confident "$" in front of a price in RMB.
+ *
+ * An unusable code is caught rather than left to throw: one bad value would otherwise raise a
+ * RangeError from inside a price label and take the whole shelf down with it.
+ */
+declare function money(amount: number, currency: string): string;
+/** What a customer is quoted, in words. `quoted` is deliberately not a number: it is the honest
+ *  answer for a catalogue line that reads `20k+` or 待定, and it must never sit behind a button
+ *  that cannot compute a total. */
+declare function priceLabel(price: ChosenPrice, currency: string): string;
+/** The one line a card shows about money. A tiered product is a RANGE until a tier is picked, so
+ *  the card says "From" and the product page says which — a card that printed one tier's figure
+ *  would be quoting a price that half the buyers do not pay. */
+declare function shelfPriceLabel(product: ShopProduct): string;
+/** The chosen tier's price, matched to it BY NAME — the tier's scope and the tier's money are two
+ *  fields on the wire, and this is the join. A tier nobody priced is quoted, which is a real state:
+ *  基础 / 标准 published, 高阶 still being costed. */
+declare function priceFor(pricing: ShopPricing, variant: string | null): ChosenPrice;
+/** What the customer would pay for `qty` units, or null where there is no total to compute. Steps,
+ *  not units: 50 upvotes at a time is what is actually sold, so a request for 60 is charged as two
+ *  steps — the same arithmetic the server does when it recomputes this from the row. */
+declare function totalFor(price: ChosenPrice, qty: number): number | null;
+/** How much of a per-unit product may be bought, and in what increments. The bounds are the
+ *  product's own, and they are shown as well as enforced: a customer who hits a limit they were
+ *  never told about reads it as a broken shop rather than a rule. */
+declare function quantityRange(product: ShopProduct, price: ChosenPrice): {
+    min: number;
+    max: number | null;
+    step: number;
+};
+/**
+ * What the chosen tier covers.
+ *
+ * A tier with nothing listed falls back to the product's own inclusions rather than showing an
+ * empty list. That is not a guess: `variants` is authored only where the tiers DIFFER in scope, so
+ * a tier that lists nothing is one that adds nothing to what the product already says it includes —
+ * and an empty "What's included" reads as a bundle containing nothing at all.
+ */
+declare function includesFor(product: ShopProduct, variant: string | null): ShopInclusion[];
+/** The values a facet actually has on this shelf, in the operator's own order. Not sorted: `sort`
+ *  on the product rows is a decision somebody made about what to show first, and re-ordering these
+ *  alphabetically throws it away. Products with the facet unset are simply not counted. */
+declare function facetValues(products: ShopProduct[], of: (product: ShopProduct) => string): string[];
+/** The message a "buy this" enquiry sends when a portal cannot take the money itself.
+ *
+ *  Named rather than described by id: an operator reads this in the same thread as everything else,
+ *  and a row id is not a thing anyone can answer. It is a SENTENCE and not a product because the
+ *  same text opens the apply form for a signed-out visitor — a request that read differently
+ *  depending on which door it came through would be two requests to reconcile.
+ */
+declare function buyRequestText(product: ShopProduct, variant: string | null, price: ChosenPrice, qty: number): string;
+declare function shelfProblem(error: unknown): string | null;
+
 type ChatMessage = {
     id: number;
     role: "user" | "assistant";
@@ -314,6 +1343,45 @@ type UseChat = {
 /** Chat state for one employee client: greeting, message list, streaming send. */
 declare const useChat: (client: HolaClient) => UseChat;
 
+type UseCredits = {
+    wallet: CreditWallet | null;
+    /** The FIRST read only. A refresh keeps the numbers on screen and swaps them when the answer
+     *  lands: blanking a balance somebody is reading, to show a spinner, to show the same balance
+     *  again, is a flicker that reads as a fault. */
+    loading: boolean;
+    failure: string | null;
+    refresh: () => void;
+};
+declare const useCredits: (credits: PortalCredits) => UseCredits;
+
+type UseShop = {
+    products: ShopProduct[];
+    /** What an enquiry asks when the product has authored nothing of its own — and the WHOLE form
+     *  for somebody asking about something not on the shelf, which has no product to carry questions
+     *  at all. The org's, set in the console. Empty is a real answer: it means one box. */
+    enquiryForm: ShopFormField[];
+    /** 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 & {
@@ -327,9 +1395,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
@@ -340,4 +1405,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 ChosenPrice, type CreateHolaClientOptions, type CreditEntry, type CreditHistory, type CreditPack, CreditRefused, type CreditTotals, type CreditWallet, type CustomerPayment, 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 InquiryQuote, type OrderBilling, type PendingTopup, type PlacedWidget, type Point, PortalConflict, type PortalCredits, type PortalData, type PortalDocument, type PortalDocumentSummary, type PortalField, type PortalFile, type PortalRow, type PortalRowAuthor, type PortalRowPage, type PortalShop, type PortalShopConfig, type PortalTable, type Purchased, QUOTE_BALANCE_LABEL, QUOTE_DEPOSIT_LABEL, type QuoteScheduleLine, type QuoteTerms, type QuotedLine, type ResolvedWidget, type SeriesWidget, type ShopApplication, type ShopApplyResult, type ShopFormField, 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 TopupStarted, type TransferDetails, type UseChat, type UseCredits, type UseShop, type UseThread, type Widget, type WidgetTransportConfig, type WidgetType, bandOfKind, bandOfType, buyRequestText, cellValue, createApiTransport, createHolaClient, createPortalCredits, createPortalData, createPortalShop, createWidgetTransport, deliverableCellText, deliverableStatus, deriveFields, emptyTableResponses, facetValues, footprintOf, footprintWith, formatDeliverableDate, groupDeliverableVersions, includesFor, inferSpec, isDeliverableChecked, mergeMessage, modeOf, money, normalizeDeliverableColType, normalizeDeliverableItem, orderBilling, parseDashboardSpec, parseDeliverableItems, parseDeliverableTable, parseTableResponses, placeWidgets, priceFor, priceLabel, publishedVersionOf, quantityRange, quoteSchedule, renderModel, setResponse, setTableReview, shelfPriceLabel, shelfProblem, splitLayout, textDeltaOf, thinkingDeltaOf, toolEventOf, totalFor, useArtifactUrl, useChat, useCredits, useHolaClient, useShop, useThread };