@nuanu-ai/agentify-contracts 0.3.2

package/dist/card.d.ts

@@ -0,0 +1,423 @@
+/**
+ * One product, in the shapes it has: the card the merchant publishes, the card
+ * an agent reads in a catalog, and the card its own merchant reads back.
+ *
+ * The published card comes first and everything the agent sees is drawn from
+ * it. The requirement that runs through every field follows from that: an
+ * agent holding only this card has to be able to assemble a correct purchase
+ * and know what it will get back. A field that fails that test is not a
+ * detail, it is a sale that ends in a refusal.
+ *
+ * The catalog id is not part of the published schema. We issue it when the
+ * card is published and hand it back in the result, so a card arriving with
+ * one is a card whose author is guessing at our numbering.
+ *
+ * The first two shapes share this file rather than being separated by
+ * audience, because what they have to be is in step with each other. Anything a
+ * merchant may publish has to project into something an agent can read, and
+ * anything the projection copies is a claim we make to whoever spends money on
+ * it. Kept apart, the rule that ties them would live in neither file.
+ *
+ * The third is not a projection at all and is here for the opposite reason: a
+ * merchant reading their own catalog is reading what they wrote, so the card
+ * travels whole, wrapped in the two facts they cannot have — the identifier we
+ * issued and the word it is selling under. A second projection would be one
+ * more shape to keep in step for no gain to anybody.
+ */
+import { z } from "zod";
+import type { ParamSpecInput } from "./param-spec.js";
+import type { Money } from "./primitives.js";
+/**
+ * When the product reaches the agent, and therefore when the money moves.
+ *
+ * `sync` — in the answer to the purchase, and the payment executes last, after
+ * the merchant has delivered. `async` — later, by a separate call, and the
+ * payment executes at the moment of purchase. `confirm` — the merchant is
+ * asked first, and the payment executes right after they say yes.
+ */
+export declare const FulfillmentSchema: z.ZodEnum<{
+    sync: "sync";
+    async: "async";
+    confirm: "confirm";
+}>;
+/**
+ * How the price and availability of this card are asked for, if they are.
+ *
+ * `"handler"` is the default path: the question travels the same outgoing
+ * channel as the orders, and the merchant hosts nothing. The other form names
+ * an address, for merchants whose price is computed by a separate service that
+ * the order handler cannot reach.
+ *
+ * The address has to be https. The question and the answer carry a merchant's
+ * prices; over plain http they are readable and rewritable by anyone on the
+ * path, and a sale that went through at someone else's price would be
+ * indistinguishable from an honest one.
+ */
+export declare const PriceCheckSchema: z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
+    url: z.ZodURL;
+}, z.core.$strict>]>;
+/**
+ * The name the seller of a card is listed under, wherever a catalog names a
+ * seller rather than a product.
+ *
+ * It belongs to the merchant and not to any one card: a merchant sells under
+ * one name, and a per-card name would be one seller appearing as several. What
+ * holds it is the merchants table, so this schema is the rule alone, applied
+ * wherever a merchant's listing name is written down.
+ */
+export declare const ServiceNameSchema: z.ZodString;
+/**
+ * The words a merchant puts on one product so an agent searching a catalog can
+ * find it.
+ *
+ * They describe this product and not the seller, which is why they sit on the
+ * card. At most five, because the catalog keeps the first five and drops the
+ * rest without a word.
+ */
+export declare const TagsSchema: z.ZodArray<z.ZodString>;
+/**
+ * Both deadlines are shown to the agent before it pays, which is why a card
+ * may only carry the ones its own mode uses. A synchronous card advertising a
+ * delivery deadline would be advertising a wait that never happens — and the
+ * wait for a synchronous answer is our system-wide budget, the same for every
+ * product, so it has no field here at all.
+ */
+export declare const CardSchema: z.ZodObject<{
+    merchant_item_id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    price: z.ZodPreprocess<z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strict>>;
+    params: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fulfillment: z.ZodDefault<z.ZodEnum<{
+        sync: "sync";
+        async: "async";
+        confirm: "confirm";
+    }>>;
+    price_check: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
+        url: z.ZodURL;
+    }, z.core.$strict>]>>;
+    confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
+    fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export type Fulfillment = z.infer<typeof FulfillmentSchema>;
+export type PriceCheck = z.infer<typeof PriceCheckSchema>;
+export type Card = z.infer<typeof CardSchema>;
+/**
+ * A card as a merchant may write it, before the short forms are opened out.
+ *
+ * It is the input face of the one schema above rather than a second schema, and
+ * it is spelled out by hand because zod cannot describe it: the short forms are
+ * read by a step whose own input is `unknown`, so inference would hand a
+ * merchant no help at all where this hands them the two spellings each field
+ * takes.
+ *
+ * What that costs is one place to keep in step, and it is bounded: everything
+ * except the four fields named below is taken from `Card` itself, so a field
+ * added to a card appears here without anybody remembering to add it. A test
+ * holds the other direction — a canonical card is a thing a merchant may write.
+ *
+ * `Card` is what everything else uses. This type is for the call that publishes
+ * and for nothing else; nothing is ever read back in this shape.
+ */
+export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"> & {
+    /** `{ amount, currency }`, or the two as one string: `'5.00 USD'`. */
+    price: Money | string;
+    /** Each field whole, or written as its type word alone: `email: 'string'`. */
+    params?: ParamSpecInput;
+    result: ParamSpecInput;
+    /** Left out on a card that is delivered in the answer to the purchase. */
+    fulfillment?: Fulfillment;
+};
+/**
+ * The check an agent's purchase parameters are held to, for this card.
+ *
+ * The compiler underneath takes a direction, and a direction is a string a
+ * caller can get backwards: compiling a card's result as a purchase silently
+ * restores the hole where a delivery promises nothing. These two take the card
+ * instead, so the only place that knows which declaration is which is the
+ * place that picks.
+ */
+export declare const purchaseCheckFor: (card: Card) => z.ZodType;
+/** The check this card's delivery is held to. */
+export declare const deliveryCheckFor: (card: Card) => z.ZodType;
+export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    price: z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    as_of: z.ZodISODateTime;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    result: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    price_checked_at_purchase: z.ZodBoolean;
+    fulfillment: z.ZodLiteral<"sync">;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    price: z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    as_of: z.ZodISODateTime;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    result: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    price_checked_at_purchase: z.ZodBoolean;
+    fulfillment: z.ZodLiteral<"async">;
+    fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    price: z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    as_of: z.ZodISODateTime;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    result: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    price_checked_at_purchase: z.ZodBoolean;
+    fulfillment: z.ZodLiteral<"confirm">;
+    confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
+    fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>], "fulfillment">;
+export type PublicCard = z.infer<typeof PublicCardSchema>;
+/**
+ * The card as an agent reads it, built from the card the merchant published.
+ *
+ * It exists so there is one projection rather than one per caller. The
+ * decision about what an agent may see is made once, here, and it is made by
+ * naming each field that is copied. Built the other way — copy the card, then
+ * remove what is internal — a field added to the published card would reach
+ * every agent by default, and the first anybody heard of it would be a
+ * merchant's pricing address in a public catalog.
+ *
+ * The two things the card cannot know are passed in: the catalog identifier we
+ * issued when it was published, and the moment its price was published.
+ */
+export declare const publicCardOf: (card: Card, issued: {
+    readonly id: string;
+    readonly as_of: string;
+}) => PublicCard;
+/**
+ * One card as a discovery catalog reads it: what an agent that has never seen
+ * our own catalog finds when it searches somewhere else.
+ *
+ * This is the second projection of a card and it sits beside the first because
+ * the two have to be read together. Both are claims we make to somebody about
+ * to spend money, both are built by naming what is copied rather than by
+ * copying the card and removing what is internal, and a field added to a card
+ * has to be considered against both or it reaches one audience by accident.
+ *
+ * What comes out is not a wire document of ours. It is the material an x402
+ * payment challenge is assembled from — the resource block, an example of the
+ * purchase body, the JSON Schema that body is held to, and an example of what a
+ * delivery carries — and the assembling is done at the edge, by the protocol's
+ * own library, from exactly these pieces. Keeping the projection here and the
+ * assembly there is what stops this package growing a payment library's
+ * dependency tree, which is the merchant SDK's dependency tree (ADR-0003 §8).
+ *
+ * Two decisions inside are worth reading before the code.
+ *
+ * The card's title is not sent. The resource block has one field of prose and
+ * the card has two, and joining a merchant's headline to a merchant's
+ * description with punctuation of our own would be us writing their listing for
+ * them. The description is the field a card writes for a program to read, so it
+ * is the one that goes.
+ *
+ * The examples are shapes rather than facts. A card declares the types of what
+ * it takes and what it returns and carries no example values, so what goes out
+ * is every declared field holding a value that stands for its type and nothing
+ * more. That is a claim we can keep — a test holds the input example to this
+ * card's own purchase check and the output example to its own delivery check,
+ * so what we publish is something our own door would accept — and it is not a
+ * claim about anybody's real data, which we do not have and will not invent.
+ */
+export interface BazaarDeclaration {
+    /** The resource block: what is being paid for, and who is selling it. */
+    readonly resource: {
+        /** The canonical address of this resource, exactly as it was given. */
+        readonly url: string;
+        readonly description: string;
+        readonly mimeType: string;
+        readonly serviceName?: string;
+        readonly tags?: readonly string[];
+    };
+    /** An example purchase body, in the shape this gateway takes one. */
+    readonly input: Record<string, unknown>;
+    /** The JSON Schema that body is held to, derived from the card's `params`. */
+    readonly inputSchema: Record<string, unknown>;
+    /** An example of what arrives on delivery, derived from the card's `result`. */
+    readonly output: {
+        readonly example: Record<string, unknown>;
+    };
+}
+/**
+ * The card as a discovery catalog reads it.
+ *
+ * The two things a card cannot know are passed in: the address this resource
+ * answers at, which is pinned by whoever runs the gateway rather than worked
+ * out from a request, and the name its seller is listed under, which belongs to
+ * the merchant. A seller with no listing name and a card with no tags leave
+ * those fields out altogether — an empty string and an empty list are values a
+ * catalog would render, and the absence is the only way to say that nobody
+ * named one.
+ */
+export declare const bazaarDeclarationOf: (card: Card, listed: {
+    readonly url: string;
+    readonly serviceName: string | null;
+}) => BazaarDeclaration;
+/**
+ * One card as the merchant who published it reads it back.
+ *
+ * The public catalog answers none of what a merchant needs from their own
+ * catalog. It is unscoped, so nothing in it says which entries are theirs; it
+ * carries our identifier in place of their key; and a card that is off sale is
+ * not in it at all, which is precisely the card a merchant is looking for when
+ * they go to put it back on sale.
+ *
+ * So the card travels whole rather than as a third projection. Everything the
+ * merchant wrote is theirs already, and copying a subset of it here would be
+ * one more shape to hold in step with the published card — the drift the
+ * projection above exists to prevent once, repeated for no gain.
+ *
+ * Two fields say where the card stands, and they are two rather than one for a
+ * reason that is invisible from the shape. `selling` is what a purchase of this
+ * card meets right now, and it is the same word the order machine is given at
+ * the birth of an order, so a card reading "paused" here is a card that refuses
+ * new orders there. `paused` says whether the pause is this card's own. They
+ * differ exactly when the merchant has stopped all selling: every card then
+ * reads `selling: "paused"`, and only the ones with `paused: true` are still
+ * paused after the merchant starts selling again. A merchant given only the
+ * first would press resume on a card and watch nothing change.
+ */
+export declare const MerchantCardSchema: z.ZodObject<{
+    id: z.ZodString;
+    as_of: z.ZodISODateTime;
+    card: z.ZodObject<{
+        merchant_item_id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        price: z.ZodPreprocess<z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+        }, z.core.$strict>>;
+        params: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                integer: "integer";
+            }>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>>;
+        result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                integer: "integer";
+            }>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fulfillment: z.ZodDefault<z.ZodEnum<{
+            sync: "sync";
+            async: "async";
+            confirm: "confirm";
+        }>>;
+        price_check: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
+            url: z.ZodURL;
+        }, z.core.$strict>]>>;
+        confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
+        fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    selling: z.ZodEnum<{
+        open: "open";
+        paused: "paused";
+        departed: "departed";
+    }>;
+    paused: z.ZodBoolean;
+}, z.core.$strict>;
+export type MerchantCard = z.infer<typeof MerchantCardSchema>;