@soba-so/react 0.0.10 → 0.0.12

package/dist/ComputeStatus.d.ts

@@ -13,3 +13,24 @@ export interface ComputeStatusProps {
  * these on one page is still one request.
  */
 export declare function ComputeStatus({ className }: ComputeStatusProps): import("react").JSX.Element;
+/**
+ * THE THREE ANSWERS A COMPUTE SECTION HAS, IN ONE PLACE.
+ *
+ * "Nothing connected yet." is a claim about somebody's account, and it is only
+ * true once the account has been read. While the first poll is in flight, or
+ * after it has failed, the honest answer is that we do not know — and saying
+ * the empty thing instead tells a person with a paired laptop that it has
+ * vanished, during an outage they cannot see and did not cause.
+ *
+ * SHARED BECAUSE THE BUG WAS THE COPY. Two components drew the same list and
+ * only one of them knew about these two states: `<ComputeStatus />` had the
+ * rule, `<ConnectCompute />` — the one most apps actually place, because it
+ * brings the control with it — did not, so the whole product's most important
+ * status line was the one that lied when the network was down. Not exported
+ * from the package: it is how our own two surfaces agree, not a third surface.
+ *
+ * MACHINES IN HAND BEAT BOTH FLAGS. The provider polls, so `loading` and
+ * `error` come back around; a poll that fails on its fourth round must not
+ * blank a list somebody is already reading.
+ */
+export declare function MachineList(): import("react").JSX.Element;

package/dist/ConnectButton.d.ts

@@ -4,8 +4,16 @@ export interface ConnectButtonProps {
     /** Override the label. Defaults to "Connect compute", or to what they have. */
     children?: ReactNode;
     /**
-     * `outline` is the same control at lower volume, for a settings row that
-     * already has a primary action on it. The design shows both.
+     * WHICH WEIGHT, AND WHY THE DEFAULT IS THE QUIET ONE.
+     *
+     * This button hands somebody to a flow that is not the host app's: nine
+     * steps, a download, and a sheet with our name at the foot of it. Drawn as a
+     * filled black control it was the loudest thing on whatever settings page it
+     * landed on — louder than Save, louder than the app's own primary action —
+     * which is a component deciding what somebody else's page is mainly about.
+     *
+     * `primary` is still one prop away, for a page whose whole purpose is this
+     * (an empty state, an onboarding step, a wall).
      */
     variant?: "primary" | "outline";
     className?: string;

package/dist/ConnectModal.d.ts

@@ -8,6 +8,14 @@ export interface ConnectModalProps {
     onConnected?: (machines: Machine[]) => void;
     /** Whether the panel draws the machines they already have, or the app does. */
     showStatus?: boolean;
+    /**
+     * Why this was opened, when it was opened by a run that could not land.
+     *
+     * Changes the opening words and nothing else. Somebody who arrived here
+     * because their laptop is asleep has already bought the idea; being sold it
+     * again is the screen telling them it did not read its own error.
+     */
+    reason?: "payment_required" | "no_compute";
 }
 /**
  * THE CONNECT FLOW, IN A DIALOG.
@@ -20,4 +28,4 @@ export interface ConnectModalProps {
  * was, which is now where the button is: an error that replaces the thing you
  * were about to press is worse than one inside the thing you just opened.
  */
-export declare function ConnectModal({ open, onOpenChange, initialCode, onConnected, showStatus, }: ConnectModalProps): import("react").JSX.Element;
+export declare function ConnectModal({ open, onOpenChange, initialCode, onConnected, showStatus, reason, }: ConnectModalProps): import("react").JSX.Element;

package/dist/ConnectNudge.d.ts

@@ -0,0 +1,120 @@
+import { type ReactNode } from "react";
+export interface ConnectNudgeProps {
+    /**
+     * How little has to be left before this says anything. A fraction of the
+     * allowance rather than a count, so it means the same on a plan of 20 and a
+     * plan of 2,000. Only consulted in the standing form.
+     */
+    at?: number;
+    /**
+     * WHAT THE LAST RUN CAME BACK WITH, and passing it at all changes which of
+     * the two integrations this is. See the note on the component.
+     *
+     * Anything your catch block caught: the parsed body, a `Response`, or an
+     * `Error` carrying either. Read through `sobaErrorCode`, so an unrelated
+     * failure is silence here and still renders however your app renders errors.
+     */
+    error?: unknown;
+    /**
+     * Both halves at once — what is already in the way, AND what refused the run
+     * once one has been tried. True exactly when `error` is not passed.
+     */
+    predict?: boolean;
+    /**
+     * THE CEILING THE RUN WAS SENT UNDER, when your app narrows `route.allow`
+     * per run rather than leaving the question to the plan.
+     *
+     * Without it this reads the PLAN's ceiling, which is right for an app that
+     * sends `POST /v1/runs` and lets the plan decide where a run may land. It is
+     * wrong, and silently so, for one that narrows per run: a surface that sends
+     * `route: { allow: ["user-hardware", "user-subscription"] }` because it needs
+     * the user's own files in front of the agent cannot run anywhere else — and
+     * on a plan that would happily have bought the run, nothing in `plan` says
+     * that. The `no_compute` came back, this had no reason to speak, and the
+     * person was told to go and find a screen.
+     *
+     * Same shape as the run's own field, so it is the value you already have: an
+     * explicit `null` is no ceiling, an empty array is a ceiling of nothing, and
+     * `undefined` — absent, or the value an optional variable happens to hold —
+     * falls back to the plan rather than claiming anything.
+     *
+     * It narrows what this card SAYS, never what a run may do — the gateway owns
+     * that — so a value that disagrees with the run costs a wrong sentence and
+     * nothing else.
+     */
+    allow?: string[] | null;
+    /**
+     * WHAT TO DRAW WHEN THIS HAS NOTHING TO OFFER — your own error UI, usually.
+     *
+     * For the attempted form, and it is the piece that makes that form safe to
+     * put in place of a message rather than above one. `<ConnectNudge error={e}/>`
+     * renders nothing for a failure connecting cannot fix, and nothing while the
+     * plan is still loading, and nothing when the machine came back between the
+     * run failing and this rendering — so a host that replaced its error line
+     * with this card had a run fail and say nothing at all.
+     *
+     * Passing the line you would otherwise have drawn means the card speaks when
+     * it can and your app speaks when it cannot, and the failure is never
+     * swallowed by either.
+     *
+     * Ignored in spirit by the standing form: a nudge with nothing to offer
+     * should be silent, and an app that has not failed at anything has no error
+     * line to pass.
+     */
+    fallback?: ReactNode;
+    className?: string;
+}
+/**
+ * THE SAME OFFER, EARLIER, AND MUCH QUIETER.
+ *
+ * A wall converts because the person has no choice, which is also why it is a
+ * bad first introduction: the only two moments they have heard of connecting
+ * are the moment it was demanded of them and the moment it was demanded again.
+ * This is the version that arrives while they still have a choice, so the wall
+ * lands on somebody who has already been told what it is.
+ *
+ * TWO REASONS TO SPEAK, and it says nothing at all otherwise, because a nudge
+ * that shows up when it cannot help is an advertisement.
+ *
+ * **Nothing can run until a machine is attached.** A "Bring your own" plan,
+ * free and unlimited on nothing but compute the user owns, is not running low
+ * on anything: it is not running at all. That state is permanent until somebody
+ * attaches a machine, and without this the only thing that would ever mention
+ * it is the `no_compute` on their first attempt. Said as a fact rather than an
+ * offer, because there is no bonus here, only a prerequisite.
+ *
+ * The plan is not the only thing that can impose that. A surface which needs
+ * the user's own files in front of the agent sends its runs under a narrower
+ * ceiling than the plan's, and then the plan is no evidence at all — see
+ * `allow`, which is how such a host says so, and `fallback`, which is how it
+ * keeps a failure from going unsaid when even this has nothing to offer.
+ *
+ * **The allowance is running out and connecting would lift it.** Needs all of:
+ * a reward felt as ALLOWANCE (`unlimited` or `included`, never `credit`, which
+ * is settled at renewal and changes nothing today), nothing connected, and an
+ * allowance that is real and nearly gone.
+ *
+ * Either way it disappears the moment something is connected. Somebody who has
+ * a machine attached has taken the offer, and repeating it reads as the app not
+ * knowing.
+ *
+ * TWO INTEGRATIONS, AND THE HOST PICKS BY WHETHER IT PASSES AN ERROR — the same
+ * pair `<RunLimit />` has, said the same way, because an app that learned one
+ * has learned the other:
+ *
+ * **Standing** — `<ConnectNudge />`. It watches the plan and stands above the
+ * composer for as long as the offer is real. The right shape when connecting is
+ * the point of the plan, and the wrong one for an app that would rather its
+ * chat opened empty: on a bring-your-own plan this is on screen from the first
+ * session, before anybody has typed anything.
+ *
+ * **On a run that failed** — `<ConnectNudge error={err} />`. Silent until
+ * something is actually refused, and silent then for anything but the two
+ * failures connecting fixes. An empty slot is not an invitation to predict:
+ * `error={null}` is a chat that has not failed yet, and it says nothing.
+ *
+ * `predict` takes both — what is already in the way and what refused the run —
+ * for an app that wants the offer standing AND wants it to answer the failure
+ * when one comes.
+ */
+export declare function ConnectNudge(props: ConnectNudgeProps): import("react").JSX.Element;

package/dist/RunLimit.d.ts

@@ -0,0 +1,55 @@
+export interface RunLimitProps {
+    /**
+     * Whatever your catch block caught. Anything that is not an answerable
+     * failure renders nothing, so this can sit permanently in your tree — and
+     * `null`, the value every app holds before the first failure, renders nothing
+     * too. Passing the prop says "report what failed"; holding an empty slot is
+     * not a request to talk about a run nobody has started.
+     *
+     * OMIT IT to have the card watch the state instead, and appear BEFORE a run
+     * is attempted rather than after one failed. In a chat that is the form you
+     * want: a plan that can only reach compute the user owns, with nothing
+     * connected, has nowhere to send a message, and the card belongs in the
+     * stream above the composer rather than in the wreckage of a request.
+     */
+    error?: unknown;
+    /**
+     * Both halves at once: watch the state AND report the failure. Defaults to
+     * true exactly when `error` is not passed.
+     *
+     * A chat wants this with `error`, because the message has nowhere to land
+     * before it is typed. A button does not: there, "nothing connected" before
+     * anybody has pressed anything is a card about a run that has not happened.
+     */
+    predict?: boolean;
+    /**
+     * `card` sits in the flow of the page, where the failed run is. `dialog`
+     * covers it. Same content either way — the container is the only difference,
+     * which is why "a card or a modal" is one decision and not two components.
+     */
+    variant?: "card" | "dialog";
+    /** Dismissing. A card without one is a card that cannot be got rid of, and
+     *  the run underneath it may be one the person no longer wants to retry. */
+    onDismiss?: () => void;
+    className?: string;
+}
+/**
+ * THE WALL, AND THE WAY THROUGH IT, WHERE THE WALL IS.
+ *
+ * A run failed for one of the two reasons a person can do something about, and
+ * this is the thing that says so and offers the two doors: run it on compute
+ * you own, or buy more. Both examples in this repo used to end that moment with
+ * a red paragraph and a pointer at a settings page in another route, which is
+ * the pattern this exists to replace.
+ *
+ * It draws two buttons at most. Connecting is primary wherever the plan
+ * actually rewards it, because it is the cheaper door for the person and the
+ * free one for the app, and putting the paid door first on a product whose
+ * argument is "use the AI you already pay for" would be arguing against
+ * ourselves.
+ *
+ * `useRunLimit` is underneath and is exported: an app whose cards have their
+ * own structure should call that and draw this itself. Ours will never match
+ * the card sitting above it in somebody else's chat.
+ */
+export declare function RunLimit(props: RunLimitProps): import("react").JSX.Element | null;

package/dist/SobaBilling.d.ts

@@ -0,0 +1,41 @@
+import { type SobaPlansProps } from "./SobaPlans.js";
+export interface SobaBillingProps extends Omit<SobaPlansProps, "className" | "showConnect"> {
+    /** The current-plan card's own heading. Empty string draws none, for an app
+     *  that has already titled the card it is putting this in. */
+    heading?: string;
+    /**
+     * The grid's heading. Defaults to what is true of the person reading it:
+     * "Change plan" for somebody on one, "Choose a plan" for somebody on none.
+     * Empty string draws none.
+     */
+    plansHeading?: string;
+    /** Hide the usage panel on the card above, for an app that draws its own
+     *  meter. The plans below are unaffected. */
+    showUsage?: boolean;
+    /**
+     * Draw the plan's name and description on the card above. On by default;
+     * pass `false` for an app that has already titled the card itself.
+     */
+    showName?: boolean;
+    className?: string;
+}
+/**
+ * THE WHOLE BILLING PAGE, IN THE ORDER SOMEBODY READS ONE.
+ *
+ * `<SobaCurrentPlan />` and `<SobaPlans />` are halves of one page — what they
+ * are on, then what else there is — and every app that used both was writing
+ * the same wrapper: the two in that order, a heading over the grid, and the
+ * decision about where the connect offer goes.
+ *
+ * THAT LAST ONE IS THE REASON THIS EXISTS RATHER THAN A SNIPPET IN THE DOCS.
+ * Both components can draw the connect offer, from the same rule, so an app
+ * assembling them itself gets the same button twice and no error to tell it so.
+ * Here the answer is structural: the offer sits on the card that reports the
+ * state it changes, and the grid under it keeps "Your plan" on the plan that is
+ * already theirs. `<SobaPlans showConnect />` is for the other page — a pricing
+ * page standing alone, with no current-plan card on it at all.
+ *
+ * Everything else is passed straight through, because a billing page's grid is
+ * the same grid: `variant`, `featured`, `showCompute`, the checkout props.
+ */
+export declare function SobaBilling({ heading, plansHeading, showUsage, showName, className, ...plans }: SobaBillingProps): import("react").JSX.Element;

package/dist/SobaCurrentPlan.d.ts

@@ -0,0 +1,29 @@
+export interface SobaCurrentPlanProps {
+    /** The section's own heading. Empty string draws none, for an app that has
+     *  already titled the card it is putting this in. */
+    heading?: string;
+    /** Hide the usage panel, for a card that only names the plan. */
+    showUsage?: boolean;
+    /**
+     * Draw the plan's name and description. Off when something else on the page
+     * already names it — `<SobaBilling />` turns it off, because the grid
+     * directly beneath marks the same plan "Current" and repeats both lines.
+     *
+     * The trial clock is NOT part of this: it is the one thing on the card the
+     * grid never shows, so it survives with the name hidden.
+     */
+    showName?: boolean;
+    className?: string;
+}
+/**
+ * WHAT THEY ARE ON, AND HOW MUCH OF IT IS LEFT.
+ *
+ * The other half of a billing page: `<SobaPlans />` answers "what could I be
+ * on", this answers "what am I on, and what happens next". The plan's name at
+ * display size, a trial clock when there is one, and a usage panel beside it.
+ *
+ * Every decision it draws — which ceiling applies, whether past the line is a
+ * bill or a wall, which single sentence is true — belongs to `useCurrentPlan`,
+ * which is exported and documented. This file is markup over it.
+ */
+export declare function SobaCurrentPlan({ heading, showUsage, showName, className, }: SobaCurrentPlanProps): import("react").JSX.Element;

package/dist/SobaPlans.d.ts

@@ -15,6 +15,61 @@ export interface SobaPlansProps {
     /** Hide the compute row. It is shown by default because on this product the
      *  plan decides which compute a run reaches, which is the differentiator. */
     showCompute?: boolean;
+    /**
+     * OFFER THE CONNECT FLOW FROM THE CURRENT CARD. OFF, AND DELIBERATELY.
+     *
+     * A card in a price list answers one question — what is this plan, and how do
+     * I get on it — and the card for the plan somebody is already on answers it
+     * with "Your plan". Putting `Connect compute` in that slot instead makes the
+     * one card that is NOT a choice carry the loudest control on the page, and
+     * takes away the only thing that said, plainly, which plan is theirs.
+     *
+     * Connecting is a fact about the plan they hold rather than about the
+     * catalogue, so the offer belongs on the surface that reports what they hold:
+     * `<SobaCurrentPlan />` draws it from the same rule (`useCurrentPlan`'s
+     * `reward.actionable` is `usePlans`' `connect.actionable`), and
+     * `<SobaBilling />` puts that card above this grid for exactly this reason.
+     *
+     * Turn it on for a pricing page that stands alone — no current-plan card
+     * anywhere on it — where a Bring-your-own plan would otherwise state a
+     * requirement with no way to meet it. Then the current card's slot carries
+     * the offer instead of the dead button.
+     *
+     * The connect LINE is not affected either way. "10,000 runs a month when you
+     * connect your own AI" is part of what a plan IS, and somebody comparing
+     * plans should read it on every card whether or not they can act on it here.
+     */
+    showConnect?: boolean;
+    /**
+     * THE SHAPE OF THE PAGE, WHICH IS NOT THE SAME DECISION AS THE CONTENT.
+     *
+     * Every layout here draws the same facts from the same plan objects — what it
+     * costs, what is included, what happens past the allowance, which compute it
+     * may reach, what connecting earns. What changes is the reading order, and
+     * that follows the page rather than the product:
+     *
+     * - `cards` is a choice being made. Each plan whole and side by side, for a
+     *   pricing page or an upgrade screen where nobody has decided yet.
+     * - `rows` is a choice being reviewed. One line per plan, price and control
+     *   on the right, which is how a settings page lists things you can switch
+     *   between — and it survives a narrow column, where a grid of cards cannot.
+     * - `table` is a choice being argued. Facts as rows and plans as columns, so
+     *   two plans can actually be compared on the dimension that separates them,
+     *   which on this product is usually the compute row rather than the price.
+     *
+     * The default stays `cards`, because it is what every caller already has.
+     */
+    variant?: "cards" | "rows" | "table";
+    /**
+     * THE PLAN THE APP IS PUSHING, by id. Drawn with emphasis in every layout.
+     *
+     * A prop rather than something derived, because nothing on a plan says
+     * "recommended" and inventing the claim from the price would be this
+     * component making a business decision on the app's behalf. A plan somebody
+     * is already ON is never featured: "Current" is the more useful of the two
+     * things to say, and two badges on one card is a page shouting.
+     */
+    featured?: string;
     className?: string;
 }
 /**
@@ -32,4 +87,4 @@ export interface SobaPlansProps {
  * would have to hand-maintain in a second place, and get wrong the first time
  * the plan changed.
  */
-export declare function SobaPlans({ onSelect, successUrl, cancelUrl, showCompute, className, }: SobaPlansProps): import("react").JSX.Element;
+export declare function SobaPlans({ onSelect, successUrl, cancelUrl, showCompute, showConnect, variant, featured, className, }: SobaPlansProps): import("react").JSX.Element;

package/dist/SobaProvider.d.ts

@@ -61,6 +61,15 @@ export interface SobaProviderProps {
     pollMs?: number;
     /** The stylesheet injects itself once. Turn it off to ship your own. */
     injectStyles?: boolean;
+    /**
+     * Whether the provider mounts the one shared `<ConnectModal />`.
+     *
+     * Left true, `connect.open()` works from anywhere in the tree and there is
+     * exactly one flow on screen however many things can raise it. False for an
+     * app that places `<ConnectModal />` itself and drives `open` from its own
+     * state: a drawer, a route, a step in a wizard.
+     */
+    modal?: boolean;
     fetchImpl?: typeof fetch;
     onError?: (error: Error) => void;
 }

package/dist/context.d.ts

@@ -20,6 +20,9 @@ export interface ComputeState {
     error: Error | null;
     refresh(): Promise<void>;
 }
+/** Why the flow was opened, carried into the panel's opening words. A person
+ *  whose laptop went to sleep should not be sold the idea from scratch. */
+export type ConnectReason = "payment_required" | "no_compute" | "manual";
 export interface ConnectState {
     /** Your app's name, as the person connecting will see it. */
     app: {
@@ -27,9 +30,35 @@ export interface ConnectState {
     } | null;
     /** The exact command to run on the machine being paired. */
     command: string | null;
+    /**
+     * Where this app's connect flow lives, which is also the only thing in the
+     * context that names OUR host — so a component that needs to offer a build
+     * derives the origin from it rather than hard-coding one. See
+     * `downloadOrigin` in connect-ui.
+     */
+    connectUrl: string | null;
     publishableKey: string | null;
     loading: boolean;
     error: Error | null;
+    /**
+     * OPEN THE FLOW FROM ANYWHERE, and there is exactly one of it.
+     *
+     * The provider mounts a single `<ConnectModal />` and this raises it. Before
+     * this, every trigger owned its own, so an app with a card in its chat, a
+     * row on its pricing page and a wall at the end of a run mounted three
+     * copies of a nine-phase flow and could have two of them on screen at once,
+     * each polling, each with its own half-finished pairing.
+     *
+     * Pass `modal={false}` to <SobaProvider> to place the modal yourself; these
+     * then do nothing, which is the honest behaviour for a control with nothing
+     * to control.
+     */
+    open(reason?: ConnectReason): void;
+    close(): void;
+    isOpen: boolean;
+    /** Whether the provider mounted the shared modal, so `open` does something.
+     *  False under `modal={false}`, where the app places its own. */
+    hasModal: boolean;
 }
 /**
  * The plans this app sells, and the one this user is on.
@@ -46,6 +75,23 @@ export interface PlanState {
     current: CurrentPlan | null;
     /** The plan object behind `current`, resolved for convenience. */
     plan: Plan | null;
+    /**
+     * THE ALLOWANCE, DERIVED, because an app should not have to know that
+     * "remaining" is a subtraction across two objects in the same response.
+     *
+     * Both halves already arrive: `plans[].included_units` and
+     * `current.units_used`. What was missing was anyone putting them together,
+     * so every app that wanted to say "two left today" wrote the arithmetic
+     * itself, and wrote the null case (unlimited) wrong the first time,
+     * because `included_units: null` is unlimited and `0` is not, and a falsy
+     * check reads them identically.
+     *
+     * Null everywhere when there is no plan, which is no ceiling.
+     */
+    used: number | null;
+    included: number | null;
+    remaining: number | null;
+    unlimited: boolean;
     loading: boolean;
     error: Error | null;
     /** Take a plan. A priced one rejects with `payment_required`; send it to

package/dist/index.d.ts

@@ -2,10 +2,17 @@ export { ComputeStatus, type ComputeStatusProps } from "./ComputeStatus.js";
 export { ConnectButton, type ConnectButtonProps } from "./ConnectButton.js";
 export { ConnectCompute, type ConnectComputeProps } from "./ConnectCompute.js";
 export { ConnectModal, type ConnectModalProps } from "./ConnectModal.js";
-export { type ComputeState, type ConnectState, type PlanState, type RunRequest, type SobaContextValue, useSoba, } from "./context.js";
+export { ConnectNudge, type ConnectNudgeProps } from "./ConnectNudge.js";
+export { type ComputeState, type ConnectReason, type ConnectState, type PlanState, type RunRequest, type SobaContextValue, useSoba, } from "./context.js";
 export { collectText, parseEvent, readEvents } from "./events.js";
+export { RunLimit, type RunLimitProps } from "./RunLimit.js";
+export { SobaBilling, type SobaBillingProps } from "./SobaBilling.js";
 export { SobaCheckout, type SobaCheckoutProps } from "./SobaCheckout.js";
+export { SobaCurrentPlan, type SobaCurrentPlanProps } from "./SobaCurrentPlan.js";
 export { SobaPlans, type SobaPlansProps } from "./SobaPlans.js";
 export { SobaProvider, type SobaProviderProps } from "./SobaProvider.js";
 export { injectStyles } from "./styles.js";
 export type { AgentEvent, AgentEventType, ConnectApi, ConnectContext, CostClass, CurrentPlan, Machine, MachineState, Message, PendingCode, Plan, Runtime, RunUsage, } from "./types.js";
+export { type AllowanceState, type CurrentPlanReward, type CurrentPlanView, useCurrentPlan, } from "./useCurrentPlan.js";
+export { type PlanCompute, type PlanConnect, type PlanCta, type PlanOffer, type PlanPrice, type PlansOptions, type PlansView, usePlans, } from "./usePlans.js";
+export { type LimitReason, type Offer, sobaErrorCode, useRunLimit } from "./useRunLimit.js";