@womp/openai-plugin 0.11.1 → 0.13.0

package/README.md

@@ -45,7 +45,7 @@ src/
 | `WompBackend` | the contract the host implements |
 | `BackendRefusal` | an error whose message reaches the model as worded |
 | `CheckoutSession`, `CompleteCheckoutArgs` | ChatGPT's payment sheet: the session it takes, and what it hands `complete_checkout` |
-| `LiveView`, `ClaimLink` | what `openScene` and `claimLink` return for the design card's live view and account link |
+| `LiveView`, `ClaimLink` | what `liveView` and `claimLink` return for the design card's live view and account link |
 
 `subject` is the caller as the host established it. `onError` receives every
 error that is not a `BackendRefusal`. `instructions` is appended to the
@@ -62,16 +62,18 @@ sign-in.
 
 | Method | Does |
 |---|---|
-| `openScene(subject, { designId?, title? })` | finds the caller's design, or makes one, and opens a **build** of it; returns `{ designId, buildId, title, live? }`, `live` only from a host that can show the design live |
+| `openScene(subject, { designId?, title? })` | finds the caller's design, or makes one, and opens a **build** of it; returns `{ designId, buildId, title }` |
 | `getSceneApi()` | the scene skill, script limits, view names, and `notes` about these designs |
 | `runScript(subject, { designId, code, purpose })` | runs one script on the design; `purpose` becomes the current build's activity, its last screenshot or a fresh render its picture; a failed script returns `ok: false` |
 | `renderScene(subject, { designId, view?, targetId? })` | renders the design; the image also becomes the current build's picture |
 | `getMaterials(subject)` | the materials on offer to the caller, before any design exists: each with its label, whether it prints in one colour (`colorRequired`) and its finishes, the first the default; and the largest size checkout takes |
 | `analyzePrint(subject, { designId, longestSideCm?, parts? })` | the design as its scene is now, analysed as it prints at its own size, or scaled so its longest side is `longestSideCm`, changing nothing, leaving out Areas named `REFERENCE` (bought parts modelled only to show a fit); with `parts` (node ids of Areas that print), only those Areas, at the scale of the whole design: size, whether it fits the largest size, separate pieces, and the price per piece in each material on offer |
 | `finishScene(subject, { designId, title })` | marks the current build done, with this version's title; called only for a design that passed the print checks |
+| `liveView?(subject, { designId })` | optional: the caller's design live in 3D on `liveViewOrigin`, with a new key, made each time the design card opens its live view; a design that isn't the caller's is a `BackendRefusal`; undefined when it can't now; without it, or without `liveViewOrigin`, the design card offers no live view |
 | `claimLink?(subject)` | optional: a one-time link to a page that keeps the chat's designs in an account; without it the design card offers no button |
 | `getBuild(subject, { designId, buildId })` | a build's status, activity, title and picture; a build that isn't the caller's reads as empty |
 | `checkoutDesign(subject, { designId, items, longestSideCm?, shipTo? })` | freezes the design as quoted, at its own size or scaled to `longestSideCm`, and without its `REFERENCE` Areas, and returns the quote with one checkout link for all its `items`, each `{ parts?, material, color?, finish?, quantity? }`: the Areas `parts` names, or the whole design, priced on its own; with `shipTo`, also shipping to that address: from a host with `completeCheckout`, the order there as a payment-sheet `session`, else `shipping`, the cheapest shipping as the user's checkout on the web first offers it and the day it arrives; called only when every item passed the print checks |
+| `checkoutLink?(subject, { url })` | optional: `url`, a checkout link `checkoutDesign` returned, as a one-time link that for a few minutes also signs a signed-out browser in to the caller's account; undefined when it can't now; without it, or then, the quote card's Checkout opens `url` as it is |
 | `completeCheckout?(subject, payment)` | optional: charges a payment made in ChatGPT's payment sheet and places the session's order; without it there is no `complete_checkout`, and a quote to an address carries `shipping` instead of a session |
 | `getOrderStatus(subject, { orderId? })` | the caller's paid orders, newest first, and the one to show, with no name, address, email or money |
 
@@ -93,6 +95,7 @@ changes an earlier one.
 - **Tool metadata states facts.** Descriptions, input schemas and server instructions say what a tool does, never how the model should behave. Behaviour lives in `prompts/` and reaches the model in `load_scene_skill`'s result.
 - **Every tool** declares `ui.visibility`, explicit annotation hints, and `securitySchemes: oauth2` with the `mcp:generate` scope. Tools only a card calls are `ui.visibility: ["app"]`.
 - **Card data** is the tool result's `structuredContent`, typed by the card's `data.ts`. Tools map backend types to it; a card never receives backend types. What only the card may see is in the result's `_meta`, typed by the same `data.ts`: a link that is a credential, and a quote or an order, which the model would otherwise draw as a card of its own.
+- **Live view.** `open_scene` sets `_meta.live` when the host has `liveView` and `liveViewOrigin`. The design card then offers the live view for as long as it is shown, and asks `get_live_view` for a new key each time it opens it. A result from before 0.13.0 carries a live view with its own key in `_meta.live`; the card reads it as the same offer, whether or not that key has expired.
 - **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading no script, style or font from outside, at a fixed URI, `ui://womp/<card>.html`. A ChatGPT app added while card URIs were content hashes keeps the URI of its time, `ui://womp/<card>-<hash>.html`; every such URI reads as the current card. Only the design card frames a page: the live view, on `liveViewOrigin`.
 
 ### Tools
@@ -105,8 +108,10 @@ changes an earlier one.
 | `render_scene` | model | |
 | `finish_scene` | model | |
 | `get_scene_progress` | `design` card | |
+| `get_live_view` | `design` card | |
 | `get_claim_link` | `design` card | |
 | `checkout_design` | model | shows `quote` |
+| `get_checkout_link` | `quote` card, only with `checkoutLink` | |
 | `complete_checkout` | model and ChatGPT's payment sheet, only with `completeCheckout` | |
 | `get_order_status` | model | shows `order` |
 

package/dist/index.d.ts

@@ -250,7 +250,6 @@ interface Order extends OrderSummary {
     statusUrl: string | null;
 }
 interface WompBackend {
-    /** `live` is optional: a host that cannot offer a live view leaves it out and the card shows its picture. */
     openScene(subject: string, input: {
         designId?: string;
         title?: string;
@@ -258,7 +257,6 @@ interface WompBackend {
         designId: string;
         buildId: string;
         title: string;
-        live?: LiveView;
     }>;
     getSceneApi(): Promise<SceneApi>;
     runScript(subject: string, input: {
@@ -286,6 +284,14 @@ interface WompBackend {
         designId: string;
         title: string;
     }): Promise<void>;
+    /**
+     * Optional: the design live in 3D with a new key, which the card asks for each time it opens the live view. A design
+     * that isn't this user's is a `BackendRefusal`; undefined when there is no live view now. Without it the card offers
+     * no live view.
+     */
+    liveView?(subject: string, input: {
+        designId: string;
+    }): Promise<LiveView | undefined>;
     /** Optional: without it the card offers no account button. Undefined when no link is available now. */
     claimLink?(subject: string): Promise<ClaimLink | undefined>;
     getBuild(subject: string, input: {
@@ -309,6 +315,14 @@ interface WompBackend {
         longestSideCm?: number;
         shipTo?: ShipTo;
     }): Promise<Checkout>;
+    /**
+     * Optional: `url`, a checkout link from `checkoutDesign`, as a one-time link that for a few minutes also signs a
+     * signed-out browser in to this user's account. Undefined when it can't now; without it, or then, the quote card opens
+     * `url` as it is.
+     */
+    checkoutLink?(subject: string, input: {
+        url: string;
+    }): Promise<CheckoutLink | undefined>;
     /** Optional: charges a payment from ChatGPT's payment sheet and places the order; without it, checkout is on the web alone. */
     completeCheckout?(subject: string, payment: CompleteCheckoutArgs): Promise<CheckoutSession>;
     /** The user's paid orders, newest first, and the one to show: `orderId` when it is one of theirs, else the newest. */