@womp/openai-plugin 0.3.0 → 0.4.0

package/README.md

@@ -23,8 +23,8 @@ src/
   index.ts         public API
   server.ts        createServer → registerResources (every card) + registerTools (every tool group)
   backend.ts       WompBackend: the contract the host implements
-  tools/           one file per tool group (scene.ts); tool.ts: shared helpers
-  cards/           one folder per card (design/); bridge.ts: shared host connection
+  tools/           one file per tool group (scene.ts, commerce.ts); tool.ts: shared helpers
+  cards/           one folder per card (design/, quote/, order/); bridge.ts: shared host connection
   text.ts          what tools and cards say to the model
   prompts/         the workflow the model follows
 ```
@@ -39,13 +39,17 @@ src/
 
 | Export | Purpose |
 |---|---|
-| `createServer({ backend, subject?, onError?, instructions? })` | the MCP server for one request |
+| `createServer({ backend, subject?, onError?, instructions?, liveViewOrigin?, linkOrigins? })` | the MCP server for one request |
 | `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` |
 
 `subject` is the caller as the host established it. `onError` receives every
 error that is not a `BackendRefusal`. `instructions` is appended to the
-server instructions, for tools the host registers itself.
+server instructions, for tools the host registers itself. `liveViewOrigin` is
+the one origin the design card may frame, for a live view. `linkOrigins` are
+the origins of the web pages the cards open (checkout, an order's status, an
+account), which ChatGPT then opens without asking the user first.
 
 ## Contract
 
@@ -58,7 +62,12 @@ server instructions, for tools the host registers itself.
 | `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 |
 | `finishScene(subject, { designId, title })` | marks the current build done, with this version's title |
+| `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 |
+| `getPrintOptions(subject, { designId, longestSideCm? })` | the design priced per piece in each material on offer, with its print size, its pieces, and checkout's size limit and order minimum |
+| `checkoutDesign(subject, { designId, material, color?, finish?, quantity?, longestSideCm?, shipTo? })` | freezes the design as quoted and returns the quote with its checkout link; with `shipTo`, also the order to that address as a payment-sheet session |
+| `completeCheckout?(subject, payment)` | optional: charges a payment made in ChatGPT's payment sheet and places the session's order; without it `checkout_design` takes no `shipTo` and there is no `complete_checkout` |
+| `getOrderStatus(subject, { orderId? })` | the caller's paid orders, newest first, and the one to show, with no name, address, email or money |
 
 A build is one round of changes and has one card. Opening a new build never
 changes an earlier one.
@@ -69,7 +78,7 @@ changes an earlier one.
 - **Errors.** A `BackendRefusal` message reaches the model as is. Any other error is one generic failure, reported to `onError`.
 - **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: noauth`. 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.
+- **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.
 - **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading nothing from outside, with a `ui://` URI that changes with its content.
 
 ### Tools
@@ -82,6 +91,11 @@ changes an earlier one.
 | `render_scene` | model | |
 | `finish_scene` | model | |
 | `get_scene_progress` | `design` card | |
+| `get_claim_link` | `design` card | |
+| `get_print_options` | model | |
+| `checkout_design` | model | shows `quote` |
+| `complete_checkout` | model and ChatGPT's payment sheet, only with `completeCheckout` | |
+| `get_order_status` | model | shows `order` |
 
 ## Extending
 

package/dist/index.d.ts

@@ -57,6 +57,200 @@ interface ClaimLink {
     url: string;
     expiresAt: string;
 }
+interface Size {
+    width: number;
+    height: number;
+    depth: number;
+}
+/** Checkout takes an order whose items cost more than `amount`; below it, it tops the items up to it (`topUp`) or refuses the order. */
+interface MinimumOrder {
+    amount: number;
+    topUp: boolean;
+}
+/** One material a design can be printed in, priced per piece. */
+interface PrintOption {
+    /** The name checkout_design takes, such as "resin-clear-tinted". */
+    material: string;
+    /** Such as "Tinted clear". */
+    label: string;
+    /** Per piece, before shipping. */
+    unitPrice: number;
+    /** Business days to make it, once ordered. */
+    productionDays: number;
+    /** The material is dyed, so an order names a colour. */
+    colorRequired: boolean;
+    /** The finishes it is made in; the first is the default. */
+    finishes: string[];
+}
+/** A design priced for printing in each material on offer. */
+interface PrintOptions {
+    designId: string;
+    title: string;
+    /** The size it prints at, in cm. */
+    sizeCm: Size;
+    /** Scaled to the longest side asked for, rather than at its own size. */
+    resized: boolean;
+    /** How many separate pieces it prints as. */
+    pieces: number;
+    /** The largest size checkout takes, in cm, in any orientation. */
+    maxSizeCm: [number, number, number];
+    /** Whether `sizeCm` fits within `maxSizeCm`. */
+    fits: boolean;
+    currency: string;
+    minimumOrder: MinimumOrder;
+    options: PrintOption[];
+}
+/** Where an order paid in ChatGPT's payment sheet ships. */
+interface ShipTo {
+    name: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    /** ISO 3166-1 alpha-2, such as "US". */
+    country: string;
+    phoneNumber?: string;
+}
+/**
+ * The user's own checkout on the web, where they enter an address and pay. Like `ClaimLink` it is a credential: it goes
+ * to the card alone, never into text the model reads.
+ */
+interface CheckoutLink {
+    url: string;
+    expiresAt: string;
+}
+/** A design quoted for ordering, as the user chose it. */
+interface Checkout {
+    designId: string;
+    title: string;
+    /** The item as an order lists it, such as "Tinted clear · #e11d48 · glossy · 4.0 × 3.0 × 1.0 cm". */
+    summary: string;
+    quantity: number;
+    /** How many separate pieces each one prints as. */
+    pieces: number;
+    currency: string;
+    /** The whole quantity's price, before shipping. */
+    price: number;
+    /** The day it leaves the factory, as YYYY-MM-DD. */
+    shipsBy: string;
+    minimumOrder: MinimumOrder;
+    link: CheckoutLink;
+    /** Quoted with `shipTo`: the order to that address, ready to pay in ChatGPT's payment sheet. */
+    session?: CheckoutSession;
+}
+/** A checkout session in the shape ChatGPT's payment sheet takes (OpenAI's Checkout API). Amounts in cents. */
+interface CheckoutSession {
+    id: string;
+    status: "ready_for_payment" | "completed";
+    currency: string;
+    payment_provider: {
+        provider: string;
+        merchant_id: string;
+        supported_payment_methods: {
+            type: string;
+            allowed_card_brands?: string[];
+        }[];
+    };
+    payment_mode: "test" | "live";
+    line_items: {
+        id: string;
+        item: {
+            id: string;
+            quantity: number;
+        };
+        name: string;
+        description: string;
+        base_amount: number;
+        discount: number;
+        subtotal: number;
+        tax: number;
+        total: number;
+    }[];
+    totals: {
+        type: "items_base_amount" | "items_discount" | "subtotal" | "discount" | "fulfillment" | "fee" | "tax" | "total";
+        display_text: string;
+        amount: number;
+    }[];
+    fulfillment_options: {
+        id: string;
+        type: "shipping";
+        title: string;
+        subtitle: string;
+        carrier: string;
+        earliest_delivery_time: string;
+        latest_delivery_time: string;
+        subtotal: number;
+        tax: number;
+        total: number;
+    }[];
+    fulfillment_option_id: string;
+    fulfillment_address: {
+        name: string;
+        line_one: string;
+        line_two?: string;
+        city: string;
+        state: string;
+        country: string;
+        postal_code: string;
+        phone_number?: string;
+    };
+    messages: {
+        type: "error";
+        code: "missing" | "invalid" | "payment_declined" | "requires_3ds";
+        content_type: "plain";
+        content: string;
+    }[];
+    links: {
+        type: "terms_of_use" | "privacy_policy";
+        url: string;
+    }[];
+    order?: {
+        id: string;
+        checkout_session_id: string;
+        permalink_url: string;
+    };
+}
+/** What ChatGPT's payment sheet hands complete_checkout once the buyer has paid. */
+interface CompleteCheckoutArgs {
+    checkout_session_id: string;
+    buyer?: {
+        name?: string;
+        email?: string;
+    };
+    payment_data: {
+        token: string;
+    };
+}
+/** One of the user's orders, enough to tell them apart. */
+interface OrderSummary {
+    id: number;
+    statusLabel: string;
+}
+/**
+ * An order as the chat may show it. A checkout link can be forwarded and its buyer's order is found too, so it carries
+ * no name, address, email or money.
+ */
+interface Order extends OrderSummary {
+    step: "paid" | "printing" | "shipped" | "delivered" | "canceled";
+    /** Only the items made from this user's checkout links. */
+    items: {
+        title: string;
+        summary: string;
+        quantity: number;
+    }[];
+    tracking: {
+        carrier: string;
+        trackingNumber: string;
+    }[];
+    /** When it leaves the factory and when it arrives, as happened or expected (ISO); null when it won't arrive or can't be dated. */
+    timeline: {
+        factoryShippingStartedAt: string;
+        deliveredAt: string;
+    } | null;
+    /** The order's status page on the web. */
+    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: {
@@ -92,6 +286,33 @@ interface WompBackend {
         designId: string;
         buildId: string;
     }): Promise<Build>;
+    getPrintOptions(subject: string, input: {
+        designId: string;
+        longestSideCm?: number;
+    }): Promise<PrintOptions>;
+    /** Freezes the design as quoted, so its order prints it as it is now. `shipTo` comes only to a host with `completeCheckout`. */
+    checkoutDesign(subject: string, input: {
+        designId: string;
+        material: string;
+        color?: string;
+        finish?: string;
+        quantity?: number;
+        longestSideCm?: number;
+        shipTo?: ShipTo;
+    }): Promise<Checkout>;
+    /**
+     * Optional: paying in ChatGPT's payment sheet. It charges the payment the sheet hands over and places the session's
+     * order; a refused payment returns the session with an error message. A host that leaves it out takes no address in
+     * checkout_design, and 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. */
+    getOrderStatus(subject: string, input: {
+        orderId?: number;
+    }): Promise<{
+        order?: Order;
+        orders: OrderSummary[];
+    }>;
 }
 declare class BackendRefusal extends Error {
 }
@@ -107,7 +328,13 @@ interface ServerOptions {
      * that is not an origin is the same as none.
      */
     liveViewOrigin?: string;
+    /**
+     * The origins of the web pages the cards open — checkout, an order's status, keeping designs in an account — such as
+     * ["https://app.womp.com"]. ChatGPT opens a page on one of them without asking the user first; anything that is not
+     * an https origin is left out.
+     */
+    linkOrigins?: string[];
 }
-declare function createServer({ backend, subject, onError, instructions, liveViewOrigin }: ServerOptions): McpServer;
+declare function createServer({ backend, subject, onError, instructions, liveViewOrigin, linkOrigins }: ServerOptions): McpServer;
 
-export { BackendRefusal, type ClaimLink, type LiveView, type WompBackend, createServer };
+export { BackendRefusal, type CheckoutSession, type ClaimLink, type CompleteCheckoutArgs, type LiveView, type WompBackend, createServer };