@nuanu-ai/agentify-contracts 0.6.0 → 0.8.0

package/dist/card.d.ts

@@ -33,12 +33,16 @@ import type { Money } from "./primitives.js";
  * `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.
+ * asked first, and the payment executes right after they say yes. `ship` — a
+ * parcel the merchant hands to a carrier (ADR-0033): the payment executes at
+ * the moment of purchase, as in `async`, and the order carries the buyer's
+ * address until the merchant takes it on, or it ends without them.
  */
 export declare const FulfillmentSchema: z.ZodEnum<{
     sync: "sync";
     async: "async";
     confirm: "confirm";
+    ship: "ship";
 }>;
 /**
  * How the price and availability of this card are asked for, if they are.
@@ -66,6 +70,20 @@ export declare const PriceCheckSchema: z.ZodUnion<readonly [z.ZodLiteral<"handle
  * wherever a merchant's listing name is written down.
  */
 export declare const ServiceNameSchema: z.ZodString;
+/**
+ * Who sells, as an agent reads it beside a product and on an order: the name
+ * the merchant sells under and the site of their shop (ADR-0034).
+ *
+ * Both are the merchant's own word and nothing here checked either, which the
+ * description says to the reader who acts on it — a name and a site can be
+ * anybody's. Null is "none given": a merchant who gave no site has none here,
+ * and a name is missing only from an order whose merchant has since lost it.
+ */
+export declare const SellerSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    site: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Seller = z.infer<typeof SellerSchema>;
 /**
  * The words a merchant puts on one product so an agent searching a catalog can
  * find it.
@@ -101,7 +119,7 @@ export declare const CardSchema: z.ZodObject<{
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
-    result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+    result: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
             number: "number";
@@ -110,18 +128,20 @@ export declare const CardSchema: z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
+    }, z.core.$strict>>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     fulfillment: z.ZodDefault<z.ZodEnum<{
         sync: "sync";
         async: "async";
         confirm: "confirm";
+        ship: "ship";
     }>>;
     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>;
+    ship_within_seconds: z.ZodOptional<z.ZodInt>;
 }, z.core.$strict>;
 export type Fulfillment = z.infer<typeof FulfillmentSchema>;
 export type PriceCheck = z.infer<typeof PriceCheckSchema>;
@@ -148,7 +168,8 @@ export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"
     price: Money | string;
     /** Each field whole, or written as its type word alone: `email: 'string'`. */
     params?: ParamSpecInput;
-    result: ParamSpecInput;
+    /** Left out on a parcel's card, whose mode fixes what the agent receives. */
+    result?: ParamSpecInput;
     /** Left out on a card that is delivered in the answer to the purchase. */
     fulfillment?: Fulfillment;
 };
@@ -162,47 +183,70 @@ export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"
  * place that picks.
  */
 export declare const purchaseCheckFor: (card: Card) => z.ZodType;
-/** The check this card's delivery is held to. */
+/**
+ * The check this card's delivery is held to: the goods its `result` declared,
+ * or for a parcel, which is not delivered with goods at all, its shipment
+ * (ADR-0033).
+ */
 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<{
+/**
+ * The fields of a card as an agent reads it in a catalog.
+ *
+ * The published card is what a merchant writes; this is what we say about it
+ * to somebody who is about to spend money. Every difference between the two is
+ * a decision, so each one is written down.
+ *
+ * Our catalog identifier replaces the merchant's own key. `id` is what a
+ * purchase, a receipt and a status all use, while `merchant_item_id` is unique
+ * only inside one merchant's catalog and means nothing outside it. An agent
+ * handed both would use the wrong one some of the time, for no gain.
+ *
+ * `price_check` is gone and one fact out of it stays. The address of a
+ * merchant's pricing service is infrastructure of theirs, no agent ever calls
+ * it, and publishing it would put it in front of everyone. What an agent does
+ * act on is that the price will be asked again: the number in the catalog is
+ * what it compares when choosing, and the sale can go through at another. So
+ * the projection carries `price_checked_at_purchase` and nothing else about
+ * how the asking is done. The flag says we ask, not that we get an answer —
+ * what happens when a merchant is silent depends on the mode and is the
+ * gateway's, and this document does not claim to know it.
+ *
+ * Both deadlines stay, because they are the merchant's promise to the agent
+ * about how long it may wait, and the agent is told them before it pays. The
+ * projection writes each only on a mode that has it, and the document says so
+ * in words rather than as structure: it takes fields added later (ADR-0006
+ * §5), so a field an agent does not expect is one it ignores, not one it can
+ * refuse.
+ *
+ * The mode is a word whose known values are listed beside it, for the same
+ * reason. The storefront has no version, so a mode added later reaches agents
+ * that still hold this contract, and to them it has to be a card to pass over
+ * rather than a catalog they cannot read.
+ *
+ * `as_of` is added: the moment the price shown here was published. A price
+ * with no moment behind it cannot be judged stale, and this is the only
+ * freshness claim a catalog makes.
+ *
+ * `tags` are gone as well, and that one is a decision rather than an omission.
+ * They are words a merchant chose so that a search in a discovery catalog finds
+ * this product, held to that catalog's own rule about length and alphabet. Our
+ * own catalog is not searched that way — an agent reading it has the whole
+ * page — so carrying them here would put a foreign catalog's constraint in
+ * front of a reader who has no use for it.
+ *
+ * Who sells is here as the merchant gave it, a name and the site of their
+ * shop (ADR-0034), and as nothing more: no profile, no contact of ours, and no
+ * claim that either was checked. Who "we" are to the buyer is a question this
+ * document still does not answer.
+ */
+export declare const PublicCardSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     description: z.ZodString;
     price: z.ZodObject<{
         amount: z.ZodString;
         currency: z.ZodString;
-    }, z.core.$strict>;
+    }, z.core.$loose>;
     as_of: z.ZodISODateTime;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
@@ -213,8 +257,8 @@ export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    result: z.ZodRecord<z.ZodString, z.ZodObject<{
+    }, z.core.$loose>>>;
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
             number: "number";
@@ -223,45 +267,40 @@ export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
+    }, z.core.$loose>>>;
     price_checked_at_purchase: z.ZodBoolean;
-    fulfillment: z.ZodLiteral<"async">;
+    seller: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        site: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>;
+    fulfillment: z.ZodUnion<readonly [z.ZodEnum<{
+        sync: "sync";
+        async: "async";
+        confirm: "confirm";
+        ship: "ship";
+    }>, z.ZodString]>;
     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">;
+    ship_within_seconds: z.ZodOptional<z.ZodInt>;
+}, z.core.$loose>;
 export type PublicCard = z.infer<typeof PublicCardSchema>;
+/**
+ * A card as `publicCardOf` builds it: the card's own fields without the index
+ * signature the open schema adds, and a mode this version knows.
+ *
+ * An agent reads a card with `PublicCardSchema`, which takes fields and modes
+ * added later (ADR-0006 §5); what is built is held to the opposite. The type
+ * catches part of that: an unknown field written straight into the returned
+ * object is a compile error. It does not reach inside the card's parts, which
+ * keep the open schema's index signatures, nor tie a deadline to its mode. The
+ * gateway's outbound check holds the rest, at every depth, before anything is
+ * sent (`checksBeforeSending`).
+ */
+export type ProjectedCard = {
+    [Field in keyof PublicCard as string extends Field ? never : Field]: PublicCard[Field];
+} & {
+    readonly fulfillment: Fulfillment;
+};
 /**
  * The card as an agent reads it, built from the card the merchant published.
  *
@@ -272,13 +311,15 @@ export type PublicCard = z.infer<typeof PublicCardSchema>;
  * 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.
+ * The three things the card cannot know are passed in: the catalog identifier
+ * we issued when it was published, the moment its price was published, and
+ * who sells it as their merchant stands now.
  */
 export declare const publicCardOf: (card: Card, issued: {
     readonly id: string;
     readonly as_of: string;
-}) => PublicCard;
+    readonly seller: Seller;
+}) => ProjectedCard;
 /**
  * One card as a discovery catalog reads it: what an agent that has never seen
  * our own catalog finds when it searches somewhere else.
@@ -327,7 +368,10 @@ export interface BazaarDeclaration {
     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`. */
+    /**
+     * An example of what arrives on delivery, derived from the card's `result`,
+     * or for a parcel the record of its shipment.
+     */
     readonly output: {
         readonly example: Record<string, unknown>;
     };
@@ -392,7 +436,7 @@ export declare const MerchantCardSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>>;
-        result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        result: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
             type: z.ZodEnum<{
                 string: "string";
                 number: "number";
@@ -401,18 +445,20 @@ export declare const MerchantCardSchema: z.ZodObject<{
             }>;
             required: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>;
+        }, z.core.$strict>>>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         fulfillment: z.ZodDefault<z.ZodEnum<{
             sync: "sync";
             async: "async";
             confirm: "confirm";
+            ship: "ship";
         }>>;
         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>;
+        ship_within_seconds: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
     selling: z.ZodEnum<{
         open: "open";