@soba-so/react 0.0.10 → 0.0.11

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * and the code disagree about what a thing is called.
  */
 export type MachineState = "online" | "busy" | "offline";
-export type CostClass = "user-hardware" | "user-subscription" | "open-weights" | "frontier";
+export type CostClass = "user-hardware" | "user-subscription" | "user-api-key" | "open-weights" | "frontier";
 export interface Runtime {
     id: string;
     display_name: string;
@@ -97,6 +97,9 @@ export interface Plan {
     interval: string;
     unit: string;
     included_units: number | null;
+    /** What happens past the allowance: `stop` or `meter`. The difference
+     *  between a wall and a bill, and not guessable from the price. */
+    overage: string;
     /** Dollars per unit past the allowance. */
     overage_per_unit: number;
     trial_days: number;
@@ -106,6 +109,18 @@ export interface Plan {
     route_allow: string[] | null;
     /** Whether it can be taken without a payment rail. */
     selectable: boolean;
+    /**
+     * WHAT CONNECTING THEIR OWN COMPUTE EARNS THEM.
+     *
+     * `none` | `unlimited` | `included` | `credit`. The one dimension no other
+     * pricing component has a column for, and the reason a free plan on this
+     * product can be worth choosing.
+     */
+    connected_reward: string;
+    /** The larger allowance an `included` reward grants. Null otherwise. */
+    connected_included_units: number | null;
+    /** Dollars back per interval on a `credit` reward. Zero otherwise. */
+    connected_credit: number;
 }
 export interface CurrentPlan {
     plan_id: string;

package/dist/useCurrentPlan.d.ts

@@ -0,0 +1,98 @@
+import type { CurrentPlan, Plan } from "./types.js";
+/**
+ * THE ALLOWANCE, WORKED OUT ONCE, FOR WHOEVER IS DRAWING IT.
+ *
+ * `<SobaCurrentPlan />` is one rendering of this. The arithmetic is the part
+ * apps get wrong, and it is worth saying exactly why: it lives across two
+ * objects and four fields that disagree about what zero means.
+ *
+ * - `included_units: null` is unlimited. `0` is not. A falsy check reads them
+ *   identically, which is how an unlimited plan starts advertising no
+ *   allowance at all.
+ * - Past the allowance is a BILL on `meter` and a WALL on `stop`, and nothing
+ *   in the price says which.
+ * - `connected_reward: "included"` RAISES the ceiling to
+ *   `connected_included_units` while a machine is attached, awake or not,
+ *   because a larger allowance is a promise about the month.
+ * - `connected_reward: "unlimited"` raises nothing. It takes the runs their own
+ *   AI SERVES out of the count, so the ceiling stays the plan's and the number
+ *   simply stops rising for those runs.
+ * - `credit` touches neither: it settles at renewal.
+ *
+ * Those last three mirror `allowanceFor` in `@soba-platform/core`, which is the
+ * rule the gateway actually enforces — so a card drawn from this and the run it
+ * describes cannot disagree about what is left.
+ */
+export type AllowanceState = 
+/** No plan is assigned, so there is no ceiling of this kind at all. */
+"none"
+/** A trial clock is running, which outranks every other thing to say. */
+ | "trial"
+/** No ceiling: an unlimited plan. */
+ | "unlimited"
+/** Inside the allowance. */
+ | "within"
+/** Past it, and being billed. A bill is not a wall. */
+ | "metered"
+/** Past it, and stopped until it resets. */
+ | "spent";
+export interface CurrentPlanReward {
+    line: string;
+    /** The reward is live right now, because something is attached. */
+    inForce: boolean;
+    /** Not a reward at all: this plan cannot run until something is connected,
+     *  and nothing is. The state `connected_reward` cannot express. */
+    required: boolean;
+    /**
+     * Something is attached right now, whatever it is doing.
+     *
+     * Not the same question as `inForce`: a `credit` plan with a laptop paired
+     * has a machine and no reward running yet, and a card that reads only the
+     * reward would draw that account as though it owned no computer. This is
+     * what decides whether the control beside the line ASKS for a machine or
+     * NAMES the one there is.
+     */
+    connected: boolean;
+    /**
+     * Whether there is anything to press about it.
+     *
+     * True only while connecting would CHANGE something: a cap this plan would
+     * lift, or a requirement it has not met, with nothing attached. False once
+     * something is — repeating an offer to somebody who took it is the screen
+     * telling them it did not work — and false for a credit, which settles at
+     * renewal and cannot be acted on today.
+     */
+    actionable: boolean;
+    /** Raise the connect flow. The same one flow the provider mounts, so a
+     *  billing page with this and a pricing grid cannot put two on screen. */
+    open(): void;
+}
+export interface CurrentPlanView {
+    plan: Plan | null;
+    assignment: CurrentPlan | null;
+    loading: boolean;
+    error: Error | null;
+    state: AllowanceState;
+    /** Whole days, rounded up, because half a day left is a day left to whoever
+     *  is reading — and zero days left while the trial runs is a lie. */
+    trialDaysLeft: number | null;
+    /** The ceiling that actually applies, raised where an `included` reward is in
+     *  force. Null is unlimited. */
+    ceiling: number | null;
+    /** True when `ceiling` is larger than the plan's own because of a machine. */
+    raised: boolean;
+    /** Runs their own AI serves are not counted against the ceiling at all. */
+    uncounted: boolean;
+    used: number;
+    /** Against `ceiling`, floored at zero. Null when unlimited. */
+    remaining: number | null;
+    /** 0–100 against `ceiling`, or null when there is nothing to be a share of. */
+    percent: number | null;
+    unlimited: boolean;
+    periodEnd: Date | null;
+    reward: CurrentPlanReward | null;
+    /** One sentence, already chosen from the state above. The thing a billing
+     *  page has to get right and the reason this hook exists. */
+    summary: string;
+}
+export declare function useCurrentPlan(): CurrentPlanView;

package/dist/useOpenSobaConnect.d.ts

@@ -0,0 +1,32 @@
+import { type Launch } from "@soba-so/connect-ui";
+/**
+ * THE PRESS THAT PUTS SOBA CONNECT IN FRONT OF SOMEBODY, and the one honest
+ * thing a page can say about it afterwards.
+ *
+ * Two surfaces need this and they draw it differently — the nudge above a
+ * composer puts the line under its detail, the wall puts it under its actions —
+ * so this is the behaviour without the markup, the same split `useRunLimit` and
+ * `<RunLimit />` already have.
+ *
+ * WHY THERE IS A NOTE AT ALL. No browser will tell a page whether a scheme
+ * handler exists; the only observable consequence of one is that something else
+ * takes the foreground, which is what `showSobaConnect` watches for. So a press
+ * can be followed by nothing happening, and a button that can do nothing
+ * without saying so is a button people press twice and then give up on.
+ *
+ * AND WHY IT SAYS SO LITTLE. `absent` means less here than it does in the
+ * connect flow: the machine that went quiet is very often NOT the computer this
+ * browser is on — a phone, a work laptop, the desktop in another room — and on
+ * that one there is nothing to open and nothing wrong. So the note reports what
+ * was seen and names the likeliest reason, and never concludes that the app is
+ * missing. `unknown` says nothing: the tab was already in the background, so
+ * the signal means nothing and inventing a sentence from it would be worse than
+ * the silence.
+ */
+export declare function useOpenSobaConnect(): {
+    open: () => void;
+    /** What the attempt looked like, or null before one. */
+    launch: Launch | null;
+    /** The one line worth showing, or null when there is nothing honest to say. */
+    note: string | null;
+};

package/dist/usePlans.d.ts

@@ -0,0 +1,115 @@
+import type { Plan } from "./types.js";
+/**
+ * THE PRICE LIST AS A DECISION, NOT AS MARKUP.
+ *
+ * `<SobaPlans />` is one rendering of this, and it is the rendering that will
+ * never match the cards already on a customer's page. Everything that is
+ * genuinely OURS about a pricing surface lives here instead — and it is more
+ * than it looks, which is why every app that drew its own got at least one of
+ * these wrong:
+ *
+ * - **Free is selected, priced is checked out.** `select` answers 402 for
+ *   anything with a price, so calling the wrong one is an error either way.
+ * - **The connect row has two reasons.** A plan that REWARDS connecting, and a
+ *   plan that REQUIRES it — the second carries `connected_reward: "none"` and
+ *   is invisible to anyone reading the reward alone, which is how the one card
+ *   where a machine is mandatory ends up with no way to attach one.
+ * - **A credit is never a button.** It is settled at renewal against the share
+ *   of the period their own compute served; there is nothing to press today.
+ * - **Which control is loud.** On a plan that is already theirs with nothing
+ *   connected, the connect button is the only thing on the card that does
+ *   anything, so it is the primary one and the plan's own control is not.
+ * - **Who pays for the compute.** The classes the user already owns cost the
+ *   app nothing at the moment of a run, and that difference is the product.
+ *
+ * An app rendering its own pricing page reads this and draws it. Ours draws it
+ * too, from the same values, so the two cannot drift.
+ */
+export interface PlanPrice {
+    /** Already formatted: `$19`, or `Free`. */
+    amount: string;
+    /** `month`, or null on a free plan — where an app usually writes "forever". */
+    interval: string | null;
+    free: boolean;
+}
+export interface PlanCompute {
+    costClass: string;
+    /** What the class is called on a pricing page, not in the router. */
+    label: string;
+    /** The user already pays for this one, so a run on it costs the app nothing.
+     *  The whole argument of the product, as a boolean. */
+    owned: boolean;
+    /** The runtimes that satisfy it, for a caller drawing vendor marks. Empty for
+     *  the classes we buy, which is an answer rather than a gap: a vendor mark
+     *  there would imply they could bring something they cannot. */
+    runtimes: string[];
+}
+export interface PlanConnect {
+    /** `Connect your own` for a reward, `To use this` for a requirement. */
+    key: string;
+    line: string;
+    /** Whether this plan rewards connecting (rather than requiring it). */
+    reward: boolean;
+    /**
+     * Whether there is anything to press, which is narrower than whether the line
+     * is worth reading: only on the plan they are ON, only while nothing is
+     * connected, and never for a credit. Connecting changes the allowance of the
+     * plan somebody holds, so the offer means nothing from a card they have not
+     * taken.
+     *
+     * WHEN THIS IS TRUE, THIS IS THE CARD'S CONTROL. The plan is already theirs,
+     * so `cta` below is a disabled "Your plan" — a button-shaped thing that does
+     * nothing — and drawing both put a live control above a dead one. The dead
+     * one is the one to drop.
+     */
+    actionable: boolean;
+    /** Raise the connect flow, with the reason carried into its opening words. */
+    open(): void;
+}
+export interface PlanCta {
+    /** `Choose`, `Subscribe for $19/month`, `Your plan`, `Switching…`. */
+    label: string;
+    disabled: boolean;
+    busy: boolean;
+    /** Take this plan: granted outright when free, Stripe when priced. Rejects
+     *  with whatever the endpoint said; `failed` below carries the last message
+     *  for a caller that would rather read than catch. */
+    take(): Promise<void>;
+}
+export interface PlanOffer {
+    plan: Plan;
+    current: boolean;
+    featured: boolean;
+    price: PlanPrice;
+    /** `2,000 runs`, or `Unlimited runs`. The figure a person compares on. */
+    allowance: string;
+    /** What follows from it: `Included each month · then $0.02 a run · 14-day
+     *  trial`. A consequence of the figure rather than a second fact beside it. */
+    allowanceNote: string;
+    /** Null `route_allow` is any compute, an empty one is none, and both are
+     *  sentences rather than lists. Null here means `compute` below is the list. */
+    computeLabel: string | null;
+    compute: PlanCompute[];
+    connect: PlanConnect | null;
+    cta: PlanCta;
+}
+export interface PlansOptions {
+    /** The plan the app is pushing, by id. Never derived: nothing on a plan says
+     *  "recommended", and guessing from the price would be a component making a
+     *  business decision for the app. Yields to `current`. */
+    featured?: string;
+    /** Handle a priced plan yourself instead of using Soba's checkout. */
+    onSelect?: (plan: Plan) => void;
+    successUrl?: string;
+    cancelUrl?: string;
+}
+export interface PlansView {
+    offers: PlanOffer[];
+    /** The plan they are on, already resolved out of `offers`. */
+    current: PlanOffer | null;
+    loading: boolean;
+    error: Error | null;
+    /** What the last `take()` came back with. Cleared by the next attempt. */
+    failed: string | null;
+}
+export declare function usePlans(options?: PlansOptions): PlansView;

package/dist/useRunLimit.d.ts

@@ -0,0 +1,140 @@
+import type { Plan } from "./types.js";
+/**
+ * THE TWO FAILURES THE CONNECT UI ANSWERS, AND WHAT TO OFFER FOR EACH.
+ *
+ * `docs/errors.md` names exactly two run failures a person can do something
+ * about: `402 payment_required`, the plan's allowance is spent, and
+ * `409 no_compute`, nothing this run may use is connected and awake. Everything
+ * else is the app's bug, our outage, or a ceiling that is not an error.
+ *
+ * Until this hook, every app integrating Soba wrote the same dead end. Both
+ * example apps did it the same way — read `error.message`, throw the `code`
+ * away, render a red paragraph, and point at a settings page in another route.
+ * The information to do better was already on the wire; nothing turned it into
+ * an offer.
+ *
+ * SO THIS IS THE WHOLE TRIGGER LAYER, and it is deliberately headless. The
+ * moment of need lands inside somebody else's product, in the middle of their
+ * chat or their composer, and no stylesheet we ship will match the cards
+ * already on that screen. An app that wants ours renders `<RunLimit />`; an app
+ * with its own card grammar calls this and draws it, and both open the same
+ * modal, because the flow behind it is nine phases long and involves a
+ * download. A card is a trigger. The modal is the flow.
+ */
+/** The failure codes worth answering. Anything else returns null. */
+export type LimitReason = "payment_required" | "no_compute";
+export interface Offer {
+    reason: LimitReason;
+    /** A heading, in the app's own voice rather than the API's. */
+    title: string;
+    /** One line under it. Already accounts for what is connected. */
+    body: string;
+    /**
+     * What connecting earns, from the plan itself, or null when the plan offers
+     * nothing for it. Null is the signal NOT to offer connecting as a way out:
+     * an app whose plan carries no reward would be asking for a laptop and giving
+     * nothing back, and a person who connects one and sees no change has been
+     * told something untrue by a component.
+     */
+    connectOffer: string | null;
+    /** The cheapest plan that would lift this, when one is for sale. */
+    upgradeTo: Plan | null;
+    /** Open the connect flow, with the reason carried into its opening copy. */
+    connect(): void;
+    /** Take `upgradeTo`: granted outright when free, Stripe otherwise. */
+    upgrade(): Promise<void>;
+}
+export interface RunLimitOptions {
+    /**
+     * Answer from the plan's own state when nothing has failed yet, rather than
+     * only reporting what did.
+     *
+     * Defaults to true only when the hook is called with no arguments at all.
+     * Pass it explicitly with an error to get both halves — what is already in
+     * the way now, and what refused the run once one has been tried — which is
+     * the shape a chat wants and the wrong shape for a button.
+     */
+    predict?: boolean;
+}
+/**
+ * Read a Soba error code out of whatever your route handed back.
+ *
+ * Accepts the parsed body (`{ error: { code } }`, the OpenAI-compatible
+ * envelope every Soba failure uses), a `Response`, or an `Error` carrying
+ * either. Exported because the alternative an app reaches for is matching on
+ * the message text, which changes.
+ */
+export declare function sobaErrorCode(input: unknown): string | null;
+/**
+ * WHAT, IF ANYTHING, IS IN THE WAY. Null when nothing is.
+ *
+ * Two ways to ask, one answer shape:
+ *
+ * **After a run failed** — pass whatever your catch block caught. Null for
+ * anything that is not one of the two answerable failures, so
+ * `{offer && <Card …/>}` is the whole integration and an unrelated error still
+ * renders however your app renders errors.
+ *
+ * **Before one is tried** — call it with NO ARGUMENTS, or pass
+ * `{ predict: true }` alongside the error to get both. It answers from what is
+ * already known: a plan that can only reach compute the user owns, with nothing
+ * connected, has nowhere to send a run, and saying so before somebody types a
+ * paragraph is strictly better than saying it after. This is the form a chat
+ * wants, because the card belongs in the stream above the composer rather than
+ * in the wreckage of a request.
+ *
+ * AN EMPTY ERROR SLOT IS NOT AN INVITATION TO PREDICT, and the distinction is
+ * the whole reason this takes an options object. `useState<unknown>(null)` is
+ * how every app in this repo holds the last failure, so `useRunLimit(error)`
+ * arrives as `null` on the very first render — and reading that as "no error
+ * was passed" put a card about a refused run on screen before anybody had
+ * pressed the button. `examples/inbox` opened on one. Only the ABSENCE of the
+ * argument asks for the state form now; a slot holding nothing means nothing
+ * has failed yet, which is the plainer reading of both.
+ *
+ * The state form is deliberately CONSERVATIVE. It reports only what the plan
+ * itself declares — its `route_allow` and its `overage` — and never reimplements
+ * the dispatch rule. Predicting a refusal is how a browser starts disagreeing
+ * with the server about whose turn it is to say no.
+ */
+export declare function useRunLimit(...args: [error?: unknown, options?: RunLimitOptions]): Offer | null;
+/**
+ * THE REFUSAL THAT IS ALREADY CERTAIN, from facts the plan states about itself.
+ *
+ * Only two things qualify, and both are the plan's own declarations rather than
+ * a guess at what dispatch will decide:
+ *
+ * - **Nowhere to run.** `route_allow` names nothing but classes the user owns,
+ *   and nothing they own can serve right now. The app has told us it will not
+ *   buy this run; there is no machine to take it. That is a `409` waiting to
+ *   happen, and it is the plan's own ceiling saying so.
+ *
+ *   `online`, NOT `connected`, and the difference is the whole of the bug this
+ *   fixed. A paired machine that has gone quiet — a shut lid, a dropped
+ *   connection, a worker still retrying — is `connected` and cannot take a
+ *   thing, so an app whose plan can only reach it said nothing at all until a
+ *   run came back 409. `online` is false for BOTH of them: nothing paired, and
+ *   nothing paired that is awake. It is the same fact dispatch checks first
+ *   (`candidateMachines` is scoped to `state = online`), read from the same
+ *   place, which is why this is not the browser inventing a rule.
+ * - **Nothing left.** The allowance is spent and `overage` is `stop`. `meter`
+ *   is excluded on purpose: past the allowance it is a bill, not a wall, and
+ *   blocking somebody who agreed to pay for overage would be this component
+ *   inventing a policy.
+ *
+ * Anything subtler — a model no supplier carries, a cost class an environment
+ * excludes — is left to the server, which is the only party that knows.
+ *
+ * EXPORTED FOR ITS OWN TEST AND NOT FROM `index.ts`, so it is reachable by
+ * `packages/react/test` and not by anybody's app. This is the whole decision
+ * the predicting form makes, and it is two comparisons with four ways to be
+ * subtly wrong; the alternative is a React harness to assert a sentence.
+ */
+export declare function foreseen(plan: {
+    plan: Plan | null;
+    remaining: number | null;
+}, compute: {
+    connected: boolean;
+    online: boolean;
+    loading: boolean;
+}): LimitReason | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soba-so/react",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Connect the AI your users already pay for, from your own React app.",
   "license": "UNLICENSED",
   "homepage": "https://soba.so/docs/components",
@@ -19,13 +19,18 @@
     "!dist/**/*.map",
     "README.md"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build-react.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "node ../../scripts/build-react.mjs"
+  },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@soba-so/connect-ui": "workspace:*",
     "@types/react": "^19.0.0",
-    "typescript": "^7.0.2",
-    "@soba-so/connect-ui": "0.1.0"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=22"
@@ -39,9 +44,5 @@
   ],
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "node ../../scripts/build-react.mjs",
-    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}