@nuanu-ai/agentify-contracts 0.6.0 → 0.8.0

package/dist/results.d.ts

@@ -72,10 +72,11 @@ import { z } from "zod";
  * it cannot parse rather than as a success it cannot name, and reports the
  * call as having gone wrong. So a word added here has to reach those clients
  * before the gateway starts sending it. The version handshake would be the
- * place to catch that. The published SDK keeps this schema strict, and every
- * new word moves `CONTRACT_VERSION` before the gateway sends it. An old worker
- * then stops at its version handshake rather than calling a successful answer
- * unreadable after the merchant has already acted on it (ADR-0006).
+ * place to catch that. The published SDK keeps this schema strict, and once a
+ * merchant we do not control runs it, every new word moves `CONTRACT_VERSION`
+ * before the gateway sends it. An old worker then stops at its version
+ * handshake rather than calling a successful answer unreadable after the
+ * merchant has already acted on it (ADR-0006 §2).
  *
  * `debt_closed_by_delivery` says the delivery deadline had already passed and
  * the goods went out anyway, closing a debt instead of completing a sale; the
@@ -102,13 +103,18 @@ export declare const OrderCallResultSchema: z.ZodEnum<{
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
  * that did not fit are named one by one in the error's `problems`.
+ * `shipment_already_recorded` — a parcel's shipment is recorded on this order
+ * and cannot be changed (ADR-0033); the same shipment sent again is answered
+ * as already delivered, and a different one is refused with this, never
+ * retryable, because a corrected number taken in silence would vanish.
  *
  * The fourth is the only one of them a merchant fixes rather than records, and
  * it is the reason it is promised rather than left to the open set. It is
@@ -131,7 +137,7 @@ export declare const OrderCallResultSchema: z.ZodEnum<{
  * one and reads it as the failure it is. What it loses is the meaning, which is
  * what this list and the dictionary below carry.
  */
-export declare const ORDER_CALL_ERROR_CODES: readonly ["refund_already_settled", "order_already_closed", "not_applicable_in_mode", "delivery_does_not_match_card"];
+export declare const ORDER_CALL_ERROR_CODES: readonly ["refund_already_settled", "order_already_closed", "not_applicable_in_mode", "delivery_does_not_match_card", "shipment_already_recorded"];
 /**
  * One thing wrong with what was sent, in a place, in a code and in words.
  *
@@ -201,9 +207,11 @@ export declare const CARD_REJECTED = "card_rejected";
  * Each arrives in the refusal's `problems` with an empty path, beside whatever
  * is wrong with the card, and none of them is cleared by editing the card: the
  * merchant has no name set for buyers to read, no wallet set for their sales to
- * be paid into, or no approval from the operator for the live catalog. The
+ * be paid into, no approval from the operator for the live catalog, or — on a
+ * parcel's card alone (ADR-0033) — no site for their shop, where a buyer takes
+ * a parcel that did not arrive. The site is set where the name is. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment
@@ -215,6 +223,7 @@ export declare const MERCHANT_FINDINGS: Readonly<{
     readonly NO_SELLER_NAME: "no_seller_name";
     readonly NO_PAYOUT_WALLET: "no_payout_wallet";
     readonly NO_OPERATOR_APPROVAL: "no_operator_approval";
+    readonly NO_SELLER_SITE: "no_seller_site";
 }>;
 /** One of the findings about the merchant, as its code travels on the wire. */
 export type MerchantFinding = (typeof MERCHANT_FINDINGS)[keyof typeof MERCHANT_FINDINGS];

package/dist/results.js

@@ -73,10 +73,11 @@ import { IdentifierSchema } from "./primitives.js";
  * it cannot parse rather than as a success it cannot name, and reports the
  * call as having gone wrong. So a word added here has to reach those clients
  * before the gateway starts sending it. The version handshake would be the
- * place to catch that. The published SDK keeps this schema strict, and every
- * new word moves `CONTRACT_VERSION` before the gateway sends it. An old worker
- * then stops at its version handshake rather than calling a successful answer
- * unreadable after the merchant has already acted on it (ADR-0006).
+ * place to catch that. The published SDK keeps this schema strict, and once a
+ * merchant we do not control runs it, every new word moves `CONTRACT_VERSION`
+ * before the gateway sends it. An old worker then stops at its version
+ * handshake rather than calling a successful answer unreadable after the
+ * merchant has already acted on it (ADR-0006 §2).
  *
  * `debt_closed_by_delivery` says the delivery deadline had already passed and
  * the goods went out anyway, closing a debt instead of completing a sale; the
@@ -103,13 +104,18 @@ export const OrderCallResultSchema = z.enum(ORDER_CALL_RESULTS);
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
  * that did not fit are named one by one in the error's `problems`.
+ * `shipment_already_recorded` — a parcel's shipment is recorded on this order
+ * and cannot be changed (ADR-0033); the same shipment sent again is answered
+ * as already delivered, and a different one is refused with this, never
+ * retryable, because a corrected number taken in silence would vanish.
  *
  * The fourth is the only one of them a merchant fixes rather than records, and
  * it is the reason it is promised rather than left to the open set. It is
@@ -137,6 +143,7 @@ export const ORDER_CALL_ERROR_CODES = Object.freeze([
     "order_already_closed",
     "not_applicable_in_mode",
     "delivery_does_not_match_card",
+    "shipment_already_recorded",
 ]);
 /**
  * One thing wrong with what was sent, in a place, in a code and in words.
@@ -175,7 +182,7 @@ export const ProblemSchema = z
      * are described for the export for the reason the error's codes are.
      */
     code: z.string().regex(/\S/, "a finding carries a code").meta({
-        description: 'What kind of finding it is, for the program that reads it. The set is open: a finding about a field of what was sent carries the name the check gave it. Three are promised, always with an empty path, and each says the merchant rather than the card is missing something, so no edit to the card clears it: "no_seller_name" (no name set for buyers to read), "no_payout_wallet" (no wallet set for the sales to be paid into, asked for wherever a payment settles) and "no_operator_approval" (the operator has not admitted this merchant to the live catalog, which only the operator can change).',
+        description: 'What kind of finding it is, for the program that reads it. The set is open: a finding about a field of what was sent carries the name the check gave it. Four are promised, always with an empty path, and each says the merchant rather than the card is missing something, so no edit to the card clears it: "no_seller_name" (no name set for buyers to read), "no_payout_wallet" (no wallet set for the sales to be paid into, asked for wherever a payment settles), "no_operator_approval" (the operator has not admitted this merchant to the live catalog, which only the operator can change) and "no_seller_site" (no site set for the merchant\'s shop, asked for on a parcel\'s card alone, because a parcel that does not arrive is a question its buyer takes there).',
     }),
     /** The same finding in words, for the person who has to fix the card. */
     message: z.string().regex(/\S/, "a finding carries an explanation a person can read"),
@@ -211,7 +218,7 @@ export const CallErrorSchema = z.strictObject({
     code: z.string().regex(/\S/, "an error carries a code").meta({
         // Same reason as the refusal code: the dictionary travels with the field
         // or it does not reach the reader the export exists for.
-        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call does not exist for this card\'s mode — refusing separately does not, in the synchronous one, where the handler\'s own answer is the refusal). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
+        description: 'Why the call did not go through. The set is open, and six are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing, and for a parcel\'s card their shop\'s site; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call or the answer does not exist for this card\'s mode — in the synchronous one the handler\'s own answer is the delivery or the refusal, so delivering or refusing separately does not exist there, and neither does taking an order on while it waits for its goods, which promises them later through a call that mode does not have). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against. On a parcel\'s order the deliver call has one more: "shipment_already_recorded" (a shipment is recorded on this order and cannot be changed; the same one sent again succeeds as already delivered, and this refusal is never retryable).',
     }),
     message: z.string().regex(/\S/, "an error carries an explanation a person can read"),
     retryable: z.boolean(),
@@ -245,9 +252,11 @@ export const CARD_REJECTED = "card_rejected";
  * Each arrives in the refusal's `problems` with an empty path, beside whatever
  * is wrong with the card, and none of them is cleared by editing the card: the
  * merchant has no name set for buyers to read, no wallet set for their sales to
- * be paid into, or no approval from the operator for the live catalog. The
+ * be paid into, no approval from the operator for the live catalog, or — on a
+ * parcel's card alone (ADR-0033) — no site for their shop, where a buyer takes
+ * a parcel that did not arrive. The site is set where the name is. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment
@@ -259,6 +268,7 @@ export const MERCHANT_FINDINGS = Object.freeze({
     NO_SELLER_NAME: "no_seller_name",
     NO_PAYOUT_WALLET: "no_payout_wallet",
     NO_OPERATOR_APPROVAL: "no_operator_approval",
+    NO_SELLER_SITE: "no_seller_site",
 });
 /**
  * The error a refused publish carries: the shared shape, with the findings made

package/dist/seller-site.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The address of a seller's own shop, held where both the card that names it
+ * and a parcel's tracking page, whose host is held to the same rule, can read
+ * it (ADR-0033, ADR-0034).
+ */
+import { z } from "zod";
+/**
+ * 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 declare const SellerSiteSchema: z.ZodString;

package/dist/seller-site.js

@@ -0,0 +1,43 @@
+/**
+ * The address of a seller's own shop, held where both the card that names it
+ * and a parcel's tracking page, whose host is held to the same rule, can read
+ * it (ADR-0033, ADR-0034).
+ */
+import { z } from "zod";
+/** 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}.` });

package/dist/ship-to.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The address a parcel goes to (ADR-0032).
+ *
+ * An agent buying a parcel sends it beside the purchase, in a shape of ours
+ * with the Agentic Commerce Protocol's names, because that is the address an
+ * agent already writes: `name`, `line_one`, `line_two`, `city`, `state`,
+ * `postal_code`, `country`, `phone_number`. One `name`, because a person may
+ * have one name and a split name cannot be recovered without guessing; no
+ * company, because the second line holds it; a phone, because the carriers a
+ * merchant hands a parcel to mostly ask for one and the merchant cannot ask
+ * for it themselves.
+ *
+ * The door checks the shape and no more. Whether a state or a postal code is
+ * needed in this country, and whether the merchant ships there at all, is the
+ * merchant's to answer in their price check: a per-country table of what is
+ * required is a table this contract would keep wrong.
+ *
+ * The address is the buyer's and passes through Agentify. The merchant's price
+ * question receives only the locality — where the parcel goes, not to whom —
+ * and the full address reaches the merchant only once the order is paid. Once
+ * the merchant takes the order on, or the order ends without them, Agentify
+ * erases its copy, and the order reads only when that happened.
+ */
+import { z } from "zod";
+export declare const ShipToSchema: 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>;
+/** Where a parcel goes as its price is asked: the place, not the person. */
+export declare const ShipToLocalitySchema: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodOptional<z.ZodString>;
+    city: z.ZodString;
+    postal_code: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** An address Agentify no longer holds: only when it let it go. */
+export declare const ErasedShipToSchema: z.ZodObject<{
+    erased_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ShipTo = z.infer<typeof ShipToSchema>;
+export type ShipToLocality = z.infer<typeof ShipToLocalitySchema>;
+export type ErasedShipTo = z.infer<typeof ErasedShipToSchema>;
+/** The locality of an address, with what it did not give left out. */
+export declare const localityOf: (address: ShipTo) => ShipToLocality;

package/dist/ship-to.js

@@ -0,0 +1,76 @@
+/**
+ * The address a parcel goes to (ADR-0032).
+ *
+ * An agent buying a parcel sends it beside the purchase, in a shape of ours
+ * with the Agentic Commerce Protocol's names, because that is the address an
+ * agent already writes: `name`, `line_one`, `line_two`, `city`, `state`,
+ * `postal_code`, `country`, `phone_number`. One `name`, because a person may
+ * have one name and a split name cannot be recovered without guessing; no
+ * company, because the second line holds it; a phone, because the carriers a
+ * merchant hands a parcel to mostly ask for one and the merchant cannot ask
+ * for it themselves.
+ *
+ * The door checks the shape and no more. Whether a state or a postal code is
+ * needed in this country, and whether the merchant ships there at all, is the
+ * merchant's to answer in their price check: a per-country table of what is
+ * required is a table this contract would keep wrong.
+ *
+ * The address is the buyer's and passes through Agentify. The merchant's price
+ * question receives only the locality — where the parcel goes, not to whom —
+ * and the full address reaches the merchant only once the order is paid. Once
+ * the merchant takes the order on, or the order ends without them, Agentify
+ * erases its copy, and the order reads only when that happened.
+ */
+import { z } from "zod";
+import { TimestampSchema } from "./primitives.js";
+/** A part of an address that has to say something. */
+const said = (what) => z.string().regex(/\S/, `${what} is not blank`);
+const CountrySchema = z
+    .string()
+    .regex(/^[A-Z]{2}$/, "a country is two capital letters, ISO 3166-1 alpha-2, such as ID or US");
+const StateSchema = z
+    .string()
+    .regex(/^[A-Z0-9]{1,3}$/, "a state is its subdivision code without the country in front, such as CA, NSW or BA");
+export const ShipToSchema = z
+    .strictObject({
+    /** Who receives the parcel, as one name. */
+    name: said("a name"),
+    line_one: said("the first line of an address"),
+    /** A flat, a building, a company. Absent where there is none. */
+    line_two: said("the second line of an address").optional(),
+    city: said("a city"),
+    /** The subdivision code without the country, where the country has them. */
+    state: StateSchema.optional(),
+    postal_code: said("a postal code").optional(),
+    country: CountrySchema,
+    phone_number: said("a phone number"),
+})
+    .meta({
+    description: "Where a parcel goes, in the Agentic Commerce Protocol's names. A name, a first line, a city, a country and a phone are required; the country is ISO 3166-1 alpha-2 and a state, where given, is its subdivision code without the country in front. Whether a state or a postal code is needed here, and whether the merchant ships to this place, is the merchant's to answer. The address passes through Agentify: the merchant's price question receives only its locality, the merchant receives the whole of it once the order is paid, and Agentify erases its copy once the merchant takes the order on, or the order ends without them.",
+});
+/** Where a parcel goes as its price is asked: the place, not the person. */
+export const ShipToLocalitySchema = z
+    .strictObject({
+    country: CountrySchema,
+    state: StateSchema.optional(),
+    city: said("a city"),
+    postal_code: said("a postal code").optional(),
+})
+    .meta({
+    description: "Where a parcel goes, as its price is asked: the country, the state, the city and the postal code of the address, and nothing about who receives it. A price question reaches a merchant for purchases that are never made, and a shipping rate needs the place alone.",
+});
+/** An address Agentify no longer holds: only when it let it go. */
+export const ErasedShipToSchema = z
+    .strictObject({
+    erased_at: TimestampSchema,
+})
+    .meta({
+    description: "An address Agentify has erased, because nothing of Agentify's needs it any more: the merchant took the order on or recorded its shipment, or the order ended or came to owe a refund without being taken on. Only when it was erased is kept, and nothing of what it was. The merchant holds the address only as they stored it from the paid order, and an order that ended before it was paid never gave it to them.",
+});
+/** The locality of an address, with what it did not give left out. */
+export const localityOf = (address) => ({
+    country: address.country,
+    ...(address.state === undefined ? {} : { state: address.state }),
+    city: address.city,
+    ...(address.postal_code === undefined ? {} : { postal_code: address.postal_code }),
+});

package/dist/shipment.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A parcel's shipment (ADR-0033): what the merchant says once a carrier has the
+ * parcel, and what the agent reads afterwards.
+ *
+ * It is the body of the `deliver` call on a parcel's order, in place of goods.
+ * A carrier, required — a carrier's name, or the shop's own courier — and a
+ * tracking number, whose key is required and whose value is null for a parcel
+ * that has none, never an empty string: a shop's own courier can sell through
+ * this mode, and "no number" has to be said rather than forgotten. A tracking
+ * page and an expected delivery window are optional.
+ *
+ * All of it is the merchant's claim and none of it is checked against a
+ * carrier, so the door holds it to its shape and to plain words on one line,
+ * as it holds a seller's name (ADR-0017): every agent that bought the parcel
+ * reads it exactly as it was written. The instant the parcel shipped is the
+ * gateway's to stamp when it records the shipment, never the merchant's to
+ * send.
+ */
+import { z } from "zod";
+/** What the merchant records when a carrier has the parcel. */
+export declare const ShipmentSchema: z.ZodObject<{
+    carrier: z.ZodString;
+    tracking_number: z.ZodNullable<z.ZodString>;
+    tracking_url: z.ZodOptional<z.ZodString>;
+    estimated_delivery: z.ZodOptional<z.ZodObject<{
+        earliest: z.ZodISODateTime;
+        latest: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A shipment as the agent reads it: what the merchant said, and when it was recorded. */
+export declare const RecordedShipmentSchema: z.ZodObject<{
+    carrier: z.ZodString;
+    tracking_number: z.ZodNullable<z.ZodString>;
+    tracking_url: z.ZodOptional<z.ZodString>;
+    estimated_delivery: z.ZodOptional<z.ZodObject<{
+        earliest: z.ZodISODateTime;
+        latest: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    shipped_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type Shipment = z.infer<typeof ShipmentSchema>;
+export type RecordedShipment = z.infer<typeof RecordedShipmentSchema>;

package/dist/shipment.js

@@ -0,0 +1,112 @@
+/**
+ * A parcel's shipment (ADR-0033): what the merchant says once a carrier has the
+ * parcel, and what the agent reads afterwards.
+ *
+ * It is the body of the `deliver` call on a parcel's order, in place of goods.
+ * A carrier, required — a carrier's name, or the shop's own courier — and a
+ * tracking number, whose key is required and whose value is null for a parcel
+ * that has none, never an empty string: a shop's own courier can sell through
+ * this mode, and "no number" has to be said rather than forgotten. A tracking
+ * page and an expected delivery window are optional.
+ *
+ * All of it is the merchant's claim and none of it is checked against a
+ * carrier, so the door holds it to its shape and to plain words on one line,
+ * as it holds a seller's name (ADR-0017): every agent that bought the parcel
+ * reads it exactly as it was written. The instant the parcel shipped is the
+ * gateway's to stamp when it records the shipment, never the merchant's to
+ * send.
+ */
+import { z } from "zod";
+import { notPlainTextIn } from "./plain-text.js";
+import { TimestampSchema } from "./primitives.js";
+import { SellerSiteSchema } from "./seller-site.js";
+/** How long a carrier's name or a tracking number may be. */
+const SHIPMENT_TEXT_MAX = 100;
+/**
+ * A short piece of the merchant's own words, as an agent will read it. The
+ * plain-text rule is a refinement, which no JSON Schema carries, so the
+ * description says it.
+ */
+const shortPlainText = (what, says) => z
+    .string()
+    .min(1, `${what} must not be empty`)
+    .max(SHIPMENT_TEXT_MAX, `${what} is at most ${SHIPMENT_TEXT_MAX} characters`)
+    .regex(/^\S(?:.*\S)?$/, `${what} must not be blank or padded with spaces`)
+    .superRefine((text, ctx) => {
+    for (const phrase of notPlainTextIn(text, "one line")) {
+        ctx.addIssue({
+            code: "custom",
+            message: `${what} carries ${phrase}, and it is plain text, which an agent reads exactly as it is written`,
+        });
+    }
+})
+    .meta({
+    description: `${says}: at most ${SHIPMENT_TEXT_MAX} characters of plain text on one line, neither blank nor padded with spaces. HTML markup and character references are refused rather than read as words.`,
+});
+/** What a tracking address is held to, said once for the refusal and the description. */
+const TRACKING_FORM = "a tracking address is a whole https address on a domain name, written as an address parser writes it back: at most 500 characters, a host in lower case and in its ASCII form (punycode for a name in another script), with no spaces, line breaks, quotes or markup, and no credentials, port or IP address. It is an address to open, never words to act on";
+/**
+ * Where a parcel can be followed. It is an address and nothing else, because
+ * every agent that bought the parcel reads it: a parser that would rewrite it
+ * — a space, a line break, markup in its query, capitals in its host — means
+ * there are words of the merchant's in it, and those are refused rather than
+ * cleaned, as the rest of the shipment's text is. What its path and query say
+ * is the carrier's, and it is an address to open, never words to act on.
+ */
+const TrackingUrlSchema = z
+    .string()
+    .max(500, TRACKING_FORM)
+    .regex(/^https:\/\//, { message: TRACKING_FORM, abort: true })
+    .refine((address) => {
+    try {
+        const parsed = new URL(address);
+        // A parser writes a slash after a bare host, before a query or a
+        // fragment as well as at the end, and that alone is not a rewrite.
+        const slashed = address.replace(/^(https:\/\/[^/?#]*)(?=[?#]|$)/, "$1/");
+        return ((parsed.href === address || parsed.href === slashed) &&
+            parsed.username === "" &&
+            parsed.password === "" &&
+            // Its origin is held as a seller's site is (ADR-0034): https, a
+            // domain name in lower case, no port.
+            SellerSiteSchema.safeParse(parsed.origin).success);
+    }
+    catch {
+        return false;
+    }
+}, TRACKING_FORM)
+    .meta({ description: `Where the parcel can be followed: ${TRACKING_FORM}.` });
+/** When the merchant expects the parcel to arrive, as a window. */
+const EstimatedDeliverySchema = z
+    .strictObject({
+    earliest: TimestampSchema,
+    latest: TimestampSchema,
+})
+    .refine((window) => Date.parse(window.earliest) <= Date.parse(window.latest), {
+    path: ["earliest"],
+    message: "an expected delivery's earliest instant comes no later than its latest",
+})
+    .meta({
+    description: "When the merchant expects the parcel to arrive, as a window: the earliest instant comes no later than the latest.",
+});
+/** What the merchant records when a carrier has the parcel. */
+export const ShipmentSchema = z
+    .strictObject({
+    /** Who carries it: a carrier's name, or the shop's own courier. */
+    carrier: shortPlainText("a carrier", "Who carries the parcel: a carrier's name, or the shop's own courier"),
+    /** The carrier's number for the parcel, or null where there is none. */
+    tracking_number: shortPlainText("a tracking number", "The carrier's number for the parcel, or null where there is none").nullable(),
+    /** Where the parcel can be followed, where the carrier has such a page. */
+    tracking_url: TrackingUrlSchema.optional(),
+    /** When the merchant expects it to arrive, where they know. */
+    estimated_delivery: EstimatedDeliverySchema.optional(),
+})
+    .meta({
+    description: 'A parcel\'s shipment, as the merchant records it with the deliver call once a carrier has the parcel. "carrier" is required: a carrier\'s name, or the shop\'s own courier. "tracking_number" is required as a key and is null for a parcel that has no number, never an empty string. "tracking_url" is an https page where the parcel can be followed, written as an address and nothing else, and "estimated_delivery" the window it is expected in; both are optional. All of it is the merchant\'s claim, which Agentify does not check against any carrier, and its words are plain text on one line. The instant it shipped is not sent: Agentify records it.',
+});
+/** A shipment as the agent reads it: what the merchant said, and when it was recorded. */
+export const RecordedShipmentSchema = ShipmentSchema.extend({
+    /** When Agentify recorded the shipment. */
+    shipped_at: TimestampSchema,
+}).meta({
+    description: "A parcel's shipment as Agentify recorded it: what the merchant said — the carrier, the tracking number or null where there is none, and where they gave them a tracking page and an expected delivery window — and \"shipped_at\", the instant Agentify recorded it. All of it but that instant is the merchant's claim, which Agentify did not check against any carrier. It is the last thing Agentify knows about the parcel: whether it arrives is between the buyer and the merchant, and the seller's site is where to ask.",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify-contracts",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "The Agentify wire contract as code: the schemas for cards, orders, price checks and receipts that the gateway and the merchant SDK both read.",
   "keywords": [