@nuanu-ai/agentify-contracts 0.7.0 → 0.8.0

package/dist/card.js

@@ -28,18 +28,26 @@ import { z } from "zod";
 import { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, paramSpecToValidator, } from "./param-spec.js";
 import { notPlainTextIn } from "./plain-text.js";
 import { IdentifierSchema, MoneySchema, OpenWordSchema, TimestampSchema } from "./primitives.js";
+import { SellerSiteSchema } from "./seller-site.js";
 import { SellingStateSchema } from "./selling.js";
+import { ShipToSchema } from "./ship-to.js";
+import { ShipmentSchema } from "./shipment.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.
+ * 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 const FulfillmentSchema = z.enum(["sync", "async", "confirm"]).meta({
-    description: 'When the product reaches the agent, and so when the money moves. "sync" — in the answer to the purchase, payment last. "async" — later, by a separate call, payment at the moment of purchase. "confirm" — the merchant is asked first and the payment follows their yes. A card cannot be published as "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order.',
+export const FulfillmentSchema = z.enum(["sync", "async", "confirm", "ship"]).meta({
+    description: 'When the product reaches the agent, and so when the money moves. "sync" — in the answer to the purchase, payment last. "async" — later, by a separate call, payment at the moment of purchase. "confirm" — the merchant is asked first and the payment follows their yes. "ship" — a parcel the merchant hands to a carrier, payment at the moment of purchase; the purchase carries the address it goes to. A card cannot be published as "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order.',
 });
+/** The longest a parcel's card may give its merchant to hand it to a carrier: thirty days. */
+const SHIP_WITHIN_AT_MOST_SECONDS = 2_592_000;
 /**
  * How the price and availability of this card are asked for, if they are.
  *
@@ -145,43 +153,6 @@ export const ServiceNameSchema = listedText("service name")
  * the next time the merchant sets their name.
  */
 const StoredServiceNameSchema = listedText("service name");
-/** What a seller's site is held to, said once for the refusal and the description. */
-const SITE_FORM = "a seller's site is https:// and the domain name of their shop, with nothing after it — https://shop.example: in lower case, a domain name rather than an IP address or a single word, with no path, query, fragment, port, credentials or trailing slash";
-/**
- * The address of a seller's own shop on the web, where an agent takes what an
- * order cannot answer (ADR-0034).
- *
- * Only an https origin, because anything after the host — a path, a query, a
- * fragment — would be text of the merchant's own reaching every agent that
- * reads the card, which is the free text the decision refuses. The host is the
- * one part the merchant writes, so it is held to a domain name too: labels of
- * letters, digits and hyphens, at most 253 characters, ending in a zone of
- * letters or a punycode one. Anything a URL parser keeps as written would
- * otherwise pass — a sentence of instructions, a quote, a host of any length —
- * and so would a single word or an IP address, which point other people's
- * agents into somebody's own network. What the pattern cannot do is tell a
- * public name from a private one: a name in a zone kept for local networks,
- * or a public one whose address leads into one, passes, and so does a
- * hyphenated sentence of up to 253 characters that is a valid name. That is
- * why an agent is told, beside every site, that nobody checked it.
- *
- * The pattern says all that in a form the JSON Schema export keeps, and it
- * stops the check where it fails, so an address copied with a slash at the end
- * is told once. Asking the URL parser for the origin catches what the pattern
- * leaves, such as a punycode label the parser would write differently.
- */
-export const SellerSiteSchema = z
-    .string()
-    .regex(/^https:\/\/(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/, { message: SITE_FORM, abort: true })
-    .refine((site) => {
-    try {
-        return new URL(site).origin === site;
-    }
-    catch {
-        return false;
-    }
-}, SITE_FORM)
-    .meta({ description: `The https origin of a seller's own shop: ${SITE_FORM}.` });
 /**
  * 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).
@@ -445,11 +416,15 @@ const CardFieldsSchema = z.strictObject({
      * says so, or a generated client would first meet the rule as a refusal.
      */
     price: CardPriceSchema.meta({
-        description: 'Publishing refuses a price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot ("5.00", "0.001"), so that a price the catalog shows is one a payment can be taken at.',
+        description: 'Publishing refuses a price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot ("5.00", "0.001"), so that a price the catalog shows is one a payment can be taken at. On a "ship" card it is the goods without shipping: the price a purchase goes through at is the merchant\'s price handler\'s answer, which includes shipping to the buyer\'s place.',
     }),
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
     params: writtenShort(ParamSpecSchema).optional(),
-    result: writtenShort(DeclaredResultSchema),
+    /**
+     * What the agent receives. Every card declares it except a parcel's, whose
+     * mode fixes it: the record of the parcel's shipment (ADR-0033).
+     */
+    result: writtenShort(DeclaredResultSchema).optional(),
     /**
      * Words for an agent searching a discovery catalog. Absent on a card whose
      * merchant named none, and never invented for them.
@@ -479,6 +454,16 @@ const CardFieldsSchema = z.strictObject({
     confirm_deadline_seconds: z.int().positive().optional(),
     /** How long the merchant may take to deliver an order it has accepted. */
     fulfill_deadline_seconds: z.int().positive().optional(),
+    /**
+     * On a parcel's card, how long the merchant may take to hand it to a carrier,
+     * counted from the charge (ADR-0033). A name of its own rather than the
+     * delivery deadline's, because on an asynchronous card that number is the
+     * time to deliver, and a number read under the wrong name tells a person
+     * their parcel arrives when it merely leaves. The ceiling is thirty days, the
+     * longest the marketplaces give a seller, and it bounds how long a buyer's
+     * money sits with a merchant before the order becomes a refund owed.
+     */
+    ship_within_seconds: z.int().positive().max(SHIP_WITHIN_AT_MOST_SECONDS).optional(),
 });
 /**
  * Both deadlines are shown to the agent before it pays, which is why a card
@@ -509,8 +494,8 @@ const cardRules = (card, ctx) => {
         // card that has one problem, and lifting the gate later would uncover it.
         return;
     }
-    // Past the gate only "sync" and "async" remain, and neither is ever asked to
-    // confirm — which is why this needs no test on the mode of its own.
+    // Past the gate no mode is ever asked to confirm — which is why this needs no
+    // test on the mode of its own.
     if (card.confirm_deadline_seconds !== undefined) {
         ctx.addIssue({
             code: "custom",
@@ -518,6 +503,24 @@ const cardRules = (card, ctx) => {
             message: `only a card with fulfillment "confirm" is asked to confirm; this one is "${card.fulfillment}"`,
         });
     }
+    if (card.fulfillment === "ship") {
+        parcelRules(card, ctx);
+        return;
+    }
+    if (card.ship_within_seconds !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ship_within_seconds"],
+            message: `only a card with fulfillment "ship" hands its goods to a carrier and names a time to ship; this one is "${card.fulfillment}"`,
+        });
+    }
+    if (card.result === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["result"],
+            message: 'result is required: a card declares what the agent receives, and only a parcel\'s, fulfillment "ship", leaves that to its mode',
+        });
+    }
     if (card.fulfillment === "sync" && card.fulfill_deadline_seconds !== undefined) {
         ctx.addIssue({
             code: "custom",
@@ -526,12 +529,62 @@ const cardRules = (card, ctx) => {
         });
     }
 };
+/**
+ * What a parcel's card is held to (ADR-0033), beside what every card is.
+ *
+ * Each rule is about a word an agent or a merchant would otherwise read wrong.
+ * The time to ship is required because it is the one promise the agent is
+ * given about when the goods leave. A result is refused because the mode fixes
+ * it — the record of the shipment — and one a merchant declared would be a
+ * second promise beside it. A delivery deadline is refused because the number
+ * would read as the time the parcel arrives. The price is the merchant's
+ * handler's to answer, because shipping depends on where the parcel goes, and
+ * only the merchant knows what it costs to send it there. And the address is
+ * not one of the card's parameters, because it travels in its own block.
+ */
+const parcelRules = (card, ctx) => {
+    if (card.ship_within_seconds === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ship_within_seconds"],
+            message: `a parcel's card names ship_within_seconds, the time to hand it to a carrier counted from the charge, at most ${SHIP_WITHIN_AT_MOST_SECONDS} (thirty days)`,
+        });
+    }
+    if (card.result !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["result"],
+            message: "a parcel's card declares no result: its mode fixes what the agent receives, the record of the parcel's shipment",
+        });
+    }
+    if (card.fulfill_deadline_seconds !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fulfill_deadline_seconds"],
+            message: "a parcel's card names the time to ship, ship_within_seconds, and no delivery deadline: under that name the number would read as the time the parcel arrives",
+        });
+    }
+    if (card.price_check !== "handler") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["price_check"],
+            message: "a parcel's price is asked of the merchant's own price handler, price_check: \"handler\", whose answer is the whole price with shipping to the buyer's place",
+        });
+    }
+    if (card.params !== undefined && "ship_to" in card.params) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["params", "ship_to"],
+            message: "a parcel's card asks for no ship_to among its parameters: the address travels in a block of its own beside them",
+        });
+    }
+};
 // JSON Schema has no way to say "this field only when that one has this
 // value", and zod drops the rules above when it renders a document. Left at
 // that, an engineer generating a client from the export would build one that
 // sends deadlines a card cannot carry and only find out on the first publish.
 // Saying it in words is weaker than checking it, and better than silence.
-const CARD_RULES_IN_WORDS = 'A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own.';
+const CARD_RULES_IN_WORDS = 'A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own. result is required on every card except one whose fulfillment is "ship". A "ship" card, a parcel, names ship_within_seconds and is the only card that may; it declares no result and no fulfill_deadline_seconds, its price_check is "handler", and it asks for no ship_to among its params, because the purchase carries the address in a block of its own.';
 /**
  * The words on a card that an agent reads: the title, the description, and
  * the title of each field the card declares.
@@ -636,8 +689,12 @@ export const CardSchema = CardFieldsSchema.superRefine(cardRules)
  * place that picks.
  */
 export const purchaseCheckFor = (card) => paramSpecToValidator(card.params ?? {}, "purchase");
-/** The check this card's delivery is held to. */
-export const deliveryCheckFor = (card) => paramSpecToValidator(card.result, "delivery");
+/**
+ * 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 const deliveryCheckFor = (card) => card.result === undefined ? ShipmentSchema : paramSpecToValidator(card.result, "delivery");
 /**
  * The fields of a card as an agent reads it in a catalog.
  *
@@ -700,7 +757,11 @@ export const PublicCardSchema = z
     as_of: TimestampSchema,
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
     params: ReadDeclarationSchema.optional(),
-    result: declaringAResult(ReadDeclarationSchema),
+    /**
+     * What the agent receives. Absent on a parcel, whose mode fixes it: the
+     * record of the parcel's shipment.
+     */
+    result: declaringAResult(ReadDeclarationSchema).optional(),
     /**
      * Whether the merchant is asked for this product's price and availability at
      * the moment of purchase, so the sale may go through at a price other than
@@ -735,6 +796,11 @@ export const PublicCardSchema = z
     fulfill_deadline_seconds: z.int().positive().optional(),
     /** On "confirm": how long the merchant has to say yes, in seconds. */
     confirm_deadline_seconds: z.int().positive().optional(),
+    /**
+     * On "ship": how long the merchant has to hand the parcel to a carrier,
+     * counted from the charge, in seconds. When it leaves, not when it arrives.
+     */
+    ship_within_seconds: z.int().positive().optional(),
 })
     .meta({
     // Everything below is written in prose above as well, and it has to be
@@ -743,7 +809,7 @@ export const PublicCardSchema = z
     // money on what this card claims. `as_of` in particular means something
     // narrower here than the same name means elsewhere in this contract, and a
     // reader who assumed otherwise would trust a stale number.
-    description: "A product an agent can buy, projected from the card its merchant published. as_of is when the price shown here was published, and nothing more: on a card whose price is checked at purchase it says nothing about how fresh that check will be — elsewhere in this contract the same name means the moment a live answer was true. price_checked_at_purchase says the merchant is asked for a price at the moment of purchase, not that they answer; what happens when they are silent depends on the mode and belongs to the gateway. The number above is what an agent compares when choosing and may not be what the sale goes through at. Two rules hold beyond the shape: a synchronous product names no delivery deadline, because it is delivered inside a response budget that is the same for every product on the platform, and only a product whose merchant is asked to confirm names a confirmation deadline. seller is who sells, as the merchant gave it: Agentify did not check the name or the site. fulfillment is a word whose known values are listed beside it, and more may be added: a reader keeps a default arm, and a card whose mode it does not know is one to pass over, not a reason to stop reading the catalog. This document and every part inside it may also gain fields; a reader ignores the ones it does not know. The type of a declared field in params and result is a closed list, and a card with a type a reader does not know is one to pass over too.",
+    description: "A product an agent can buy, projected from the card its merchant published. as_of is when the price shown here was published, and nothing more: on a card whose price is checked at purchase it says nothing about how fresh that check will be — elsewhere in this contract the same name means the moment a live answer was true. price_checked_at_purchase says the merchant is asked for a price at the moment of purchase, not that they answer; what happens when they are silent depends on the mode and belongs to the gateway. The number above is what an agent compares when choosing and may not be what the sale goes through at. Three rules hold beyond the shape: a synchronous product names no delivery deadline, because it is delivered inside a response budget that is the same for every product on the platform; only a product whose merchant is asked to confirm names a confirmation deadline; and a parcel, fulfillment \"ship\", names ship_within_seconds — the time to hand it to a carrier counted from the charge, not the time it arrives — and no result, because what the agent receives is the record of its shipment, while every other product names a result. On a parcel the price shown is the goods without shipping, and the purchase goes through at the merchant's answer for the whole, shipping to the buyer's place included. seller is who sells, as the merchant gave it: Agentify did not check the name or the site. fulfillment is a word whose known values are listed beside it, and more may be added: a reader keeps a default arm, and a card whose mode it does not know is one to pass over, not a reason to stop reading the catalog. This document and every part inside it may also gain fields; a reader ignores the ones it does not know. The type of a declared field in params and result is a closed list, and a card with a type a reader does not know is one to pass over too.",
 });
 /**
  * The card as an agent reads it, built from the card the merchant published.
@@ -768,7 +834,7 @@ export const publicCardOf = (card, issued) => {
         price: card.price,
         as_of: issued.as_of,
         ...(card.params === undefined ? {} : { params: card.params }),
-        result: card.result,
+        ...(card.result === undefined ? {} : { result: card.result }),
         price_checked_at_purchase: card.price_check !== undefined,
     };
     switch (card.fulfillment) {
@@ -793,6 +859,14 @@ export const publicCardOf = (card, issued) => {
                     ? {}
                     : { fulfill_deadline_seconds: card.fulfill_deadline_seconds }),
             };
+        case "ship":
+            return {
+                ...common,
+                fulfillment: "ship",
+                ...(card.ship_within_seconds === undefined
+                    ? {}
+                    : { ship_within_seconds: card.ship_within_seconds }),
+            };
     }
 };
 /**
@@ -827,9 +901,40 @@ const exampleOf = (spec) => Object.fromEntries(Object.entries(spec).map(([name,
  * inside another schema, so that one line is dropped here.
  */
 const purchaseBodySchemaOf = (card) => {
-    const { $schema, ...body } = z.toJSONSchema(z.strictObject({ params: purchaseCheckFor(card) }));
+    const { $schema, ...body } = z.toJSONSchema(z.strictObject({
+        params: purchaseCheckFor(card),
+        // A parcel's purchase carries the address it goes to beside its
+        // parameters, and is refused without one (ADR-0032).
+        ...(card.fulfillment === "ship" ? { ship_to: ShipToSchema } : {}),
+    }));
     return body;
 };
+/**
+ * Where a parcel goes, in a listing's example purchase: Agentify's own office
+ * (ADR-0033), with the number taken out of it, so that the example is a real
+ * place and nobody's home.
+ */
+const LISTED_SHIP_TO = {
+    name: "Agentify",
+    line_one: "Jl. Raya Kediri, Beraban",
+    line_two: "Nuanu Creative City",
+    city: "Tabanan",
+    state: "BA",
+    postal_code: "82121",
+    country: "ID",
+    phone_number: "+62 000 0000 0000",
+};
+/**
+ * A recorded shipment, in a listing's example output, written as every other
+ * example here is: each field standing for what goes there, and the instant
+ * at the start of the clock rather than a date that looks like one somebody
+ * shipped on.
+ */
+const LISTED_SHIPMENT = {
+    carrier: "string",
+    tracking_number: "string",
+    shipped_at: "1970-01-01T00:00:00Z",
+};
 /**
  * The card as a discovery catalog reads it.
  *
@@ -849,9 +954,14 @@ export const bazaarDeclarationOf = (card, listed) => ({
         ...(listed.serviceName === null ? {} : { serviceName: listed.serviceName }),
         ...(card.tags === undefined ? {} : { tags: card.tags }),
     },
-    input: { params: exampleOf(card.params ?? {}) },
+    input: {
+        params: exampleOf(card.params ?? {}),
+        ...(card.fulfillment === "ship" ? { ship_to: LISTED_SHIP_TO } : {}),
+    },
     inputSchema: purchaseBodySchemaOf(card),
-    output: { example: exampleOf(card.result) },
+    // What the agent is finally handed: the goods the card declared, or for a
+    // parcel the record of its shipment.
+    output: { example: card.result === undefined ? LISTED_SHIPMENT : exampleOf(card.result) },
 });
 /**
  * One card as the merchant who published it reads it back.

package/dist/envelope.d.ts

@@ -73,12 +73,35 @@ export declare const WORKER_ENVELOPE_PAYLOADS: Readonly<{
             as_of: z.ZodISODateTime;
         }, z.core.$strict>;
         price_id: z.ZodOptional<z.ZodString>;
+        ship_to: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            line_one: z.ZodString;
+            line_two: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            postal_code: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            phone_number: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            erased_at: z.ZodISODateTime;
+        }, z.core.$strict>]>>;
         test: z.ZodBoolean;
     }, z.core.$strict>;
     /** "How much is this and is it there", asked before a sale goes through. */
     readonly quote_request: z.ZodObject<{
         merchant_item_id: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        ship_to: z.ZodOptional<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         price_id: z.ZodString;
         purpose: z.ZodEnum<{
             purchase: "purchase";
@@ -128,6 +151,23 @@ export declare const WorkerEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             as_of: z.ZodISODateTime;
         }, z.core.$strict>;
         price_id: z.ZodOptional<z.ZodString>;
+        ship_to: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            line_one: z.ZodString;
+            line_two: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            postal_code: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            phone_number: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            erased_at: z.ZodISODateTime;
+        }, z.core.$strict>]>>;
         test: z.ZodBoolean;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
@@ -137,6 +177,12 @@ export declare const WorkerEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     payload: z.ZodObject<{
         merchant_item_id: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        ship_to: z.ZodOptional<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         price_id: z.ZodString;
         purpose: z.ZodEnum<{
             purchase: "purchase";