@nuanu-ai/agentify-contracts 0.6.0 → 0.8.0

package/dist/merchant.js

@@ -1,19 +1,16 @@
 /**
- * How a merchant comes to exist, the name their products are sold under, the
- * wallet their sales are paid into, and the keys they open the door with.
+ * What a merchant says about themselves: the name their products are sold
+ * under, the wallet their sales are paid into, and the keys they open the door
+ * with.
  *
- * The first two belong together because registering is the act that produces
- * both: one call makes the merchant and the key its cabinet will call as them
- * with, and what comes back carries that key once. Split across two files, a
- * reader working out what registering leaves a merchant holding would have to
- * read both to find that it is a key of a kind no list here carries. The name is here for the same reason read the other way round — it is a
- * fact about the merchant and about none of their cards, and the one question a
- * reader arrives with is which of the two names a merchant has is which.
+ * The name is here rather than beside the card because it is a fact about the
+ * merchant and about none of their cards, and the one question a reader
+ * arrives with is which of the two names a merchant has is which.
  *
  * Two rules run through the file and are worth saying once.
  *
- * The secret appears in exactly three documents, and every one of them is the
- * answer to a call that has just made a key. Nothing that is ever drawn again —
+ * The secret appears in one document, the answer to the call that has just
+ * made a key. Nothing that is ever drawn again —
  * the list a merchant reads, the row that comes back from disabling one — can
  * carry it, and the shapes below refuse it rather than merely omit it. What is
  * kept on our side is a digest, so there is nothing to put in those documents
@@ -25,9 +22,10 @@
  * nothing, while a flag answers only half.
  */
 import { z } from "zod";
-import { ServiceNameSchema } from "./card.js";
+import { SellerSchema, ServiceNameSchema } from "./card.js";
 import { EvmAddressSchema } from "./evm-address.js";
 import { IdentifierSchema, TimestampSchema } from "./primitives.js";
+import { SellerSiteSchema } from "./seller-site.js";
 /**
  * What a merchant calls one of their keys, so one of several can be told from
  * the others.
@@ -94,18 +92,6 @@ const IssuedKeyLabelSchema = KeyLabelSchema.max(LONGEST_KEY_LABEL, `a label is a
 const KeySecretSchema = z
     .string()
     .regex(/^\S+$/, "a key travels as a bearer token, so it carries no whitespace and is not empty");
-/**
- * The code that stands in the door of registration.
- *
- * It is one value out of the gateway's configuration, handed to a person along
- * with the address of the site (ADR-0014 §3). All this shape asks is that
- * something was actually typed: a form submitted with an empty field is a
- * mistake at the keyboard rather than a wrong code, and the two are worth
- * telling apart before anything is compared.
- */
-const InvitationSchema = z
-    .string()
-    .regex(/\S/, "an invitation is the code handed over with the address of the site");
 /**
  * One key a merchant holds, as they read it.
  *
@@ -161,11 +147,8 @@ export const MerchantKeySchema = z
  * refuses, on the one page where being refused looks like the product being
  * broken.
  *
- * It is not always one of the keys beside it, and that is the thing a reader is
- * likeliest to assume and be wrong about. A cabinet calls with a key made for a
- * cabinet, and those are in nobody's list, so a client that looked this
- * identifier up among the rows would find nothing — which is an answer rather
- * than an error, and a screen has to be built for it.
+ * It is always one of the keys beside it: every key is one a merchant issued
+ * for their own code, and the dashboard calls with none (ADR-0030).
  *
  * An object rather than a bare array, for that reason before any other — an
  * array has nowhere to put it.
@@ -175,18 +158,13 @@ export const MerchantKeyListSchema = z
     /**
      * The keys this merchant made for their own code, the revoked ones among
      * them.
-     *
-     * The keys a cabinet holds are not here and never will be: the merchant did
-     * not issue one and has nothing to do with one. A list is what somebody
-     * acts on, and a row nobody has any business acting on is a row that only
-     * raises the question of why it will not go away.
      */
     keys: z.array(MerchantKeySchema),
     /** The key the request carrying this answer was made with. */
     this_call: IdentifierSchema,
 })
     .meta({
-    description: "The keys one merchant made for their own code, working and revoked together, and the identifier of the key this very call was made with. That last field is here because a merchant cannot disable the key they are holding: without it a screen would offer a button the gateway refuses. It is not always among the keys listed — a cabinet calls with a key of its own, and those are in no list here — so a client matching it against the rows has to be built for finding none. The keys a cabinet holds are left out entirely: they are not issued by the merchant and cannot be revoked by them. This document does not say whether it is the whole list either — paging is not designed, and the absence of a field about it is not a promise that there is no more.",
+    description: "The keys one merchant made for their own code, working and revoked together, and the identifier of the key this very call was made with. That last field is here because a merchant cannot disable the key they are holding: without it a screen would offer a button the gateway refuses. It is always one of the keys listed, since every key is one the merchant issued. This document does not say whether it is the whole list either — paging is not designed, and the absence of a field about it is not a promise that there is no more.",
 });
 /** What a merchant sends to have a key made. */
 export const IssueKeyRequestSchema = z
@@ -211,7 +189,7 @@ export const IssuedKeySchema = z
     secret: KeySecretSchema,
 })
     .meta({
-    description: "A key as it comes back from being issued: the row a merchant will see in their list from now on, and the key itself. It carries the key once. Three answers in this contract carry one — this, what registering gives back, and the key a cabinet asks for — and nothing else does, because what is written down on our side is a digest. A key that is lost is replaced by a new one rather than read back.",
+    description: "A key as it comes back from being issued: the row a merchant will see in their list from now on, and the key itself. It carries the key once, and it is the one answer in this contract that carries one, because what is written down on our side is a digest. A key that is lost is replaced by a new one rather than read back.",
 });
 /**
  * A key that has been revoked, as it now stands.
@@ -227,44 +205,6 @@ export const DisabledKeySchema = z
     .meta({
     description: "The key that was just revoked, with the instant it stopped working on it, so a merchant reads back what happened rather than taking the call's word for it. Revoking a key that was already revoked answers this same way and keeps the first instant, because that is the true one and a retry after a dropped connection must not rewrite it.",
 });
-/**
- * A key made for a cabinet, which is the secret and nothing else.
- *
- * Every other answer that makes a key carries the row beside it, and this one
- * cannot. A key made for a cabinet is in no merchant's list — they did not
- * issue it and have no reason to know it exists — so an identifier here would
- * name a row that no screen of theirs draws and no call of theirs reaches: not
- * the list it is absent from, and not the revoking, which takes the keys a
- * merchant issued and refuses this kind by name. What the caller does with this
- * is put it on the row of whoever just signed in, and that is the whole of what
- * it needs.
- */
-export const CabinetKeySchema = z
-    .strictObject({
-    /** The only moment this is readable. Nothing on our side keeps it. */
-    secret: KeySecretSchema,
-})
-    .meta({
-    description: "A key made for a cabinet to call as one merchant, carried once and readable nowhere afterwards. There is no row beside it and there is nothing to put one: a key made this way is in no merchant's list of keys, and the call that revokes a key refuses this kind by name — so an identifier for it would name something no answer shows and no call acts on. Whoever asked for this holds it until they ask for another.",
-});
-/**
- * That the key a call was made with is gone.
- *
- * A constant, and deliberately: the call has one outcome. It removes the key it
- * was made with and no other, so there is nothing to count — a number here
- * could only be about rows this call cannot reach — and nothing to name, since
- * the caller is holding the only key it names. What is left to say is that it
- * is done, and it is said in a field rather than left to a status code so that
- * a client reads one document and not two kinds of evidence.
- */
-export const ForgottenCabinetKeySchema = z
-    .strictObject({
-    /** The key this call was made with no longer exists. */
-    forgotten: z.literal(true),
-})
-    .meta({
-    description: "That the key this call was made with has been removed, which is the only thing this call does. There is nothing to count and nothing to name: it reaches one key, the one in the caller's hand, and the caller already knows which that is.",
-});
 /**
  * What a merchant's products are sold under, as the merchant reads it back.
  *
@@ -284,11 +224,20 @@ export const ForgottenCabinetKeySchema = z
  */
 export const SellerNameSchema = z
     .strictObject({
-    /** What buyers read beside this merchant's products, or nothing. */
-    seller_name: ServiceNameSchema.nullable(),
+    /**
+     * What buyers read beside this merchant's products, or nothing — read back
+     * by the rule an agent's `seller` reads it by, which leaves the plain-text
+     * rule to the door that writes it.
+     */
+    seller_name: SellerSchema.shape.name,
+    /**
+     * The https address of the merchant's own shop, where an agent takes what
+     * an order cannot answer (ADR-0034), or nothing where none was given.
+     */
+    seller_site: SellerSiteSchema.nullable(),
 })
     .meta({
-    description: "The name a merchant's products are sold under: what a discovery catalog lists them under and what a buyer's agent is shown beside the price. Null means nobody has chosen one, which is where every merchant starts. The field is always present rather than left out when there is no name: an absent field would be indistinguishable from a client that dropped it. What a name may be is the catalog's rule rather than ours — at most 32 characters of printable ASCII — because a name outside it is dropped there in silence, so it is refused here where somebody is told. A merchant with no name cannot publish a card: a card published without one reaches a buyer's agent inside a payment request that names no seller at all.",
+    description: "The name a merchant's products are sold under: what a discovery catalog lists them under and what a buyer's agent is shown beside the price. Null means nobody has chosen one, which is where every merchant starts. The field is always present rather than left out when there is no name: an absent field would be indistinguishable from a client that dropped it. What a name may be is the catalog's rule rather than ours — at most 32 characters of printable ASCII — because a name outside it is dropped there in silence, so it is refused here where somebody is told. A merchant with no name cannot publish a card: a card published without one reaches a buyer's agent inside a payment request that names no seller at all. seller_site is the https address of the merchant's own shop, which every agent reads beside the name on their cards and orders as where to take what an order cannot answer; null means none was given.",
 });
 /**
  * What a merchant sends to change what their products are sold under.
@@ -303,7 +252,7 @@ export const SellerNameSchema = z
  * which is this same call, or an end to selling, which is the pause — and the
  * pause leaves their cards where they can find them again.
  *
- * So it is two documents rather than one, and a cabinet still reads back the
+ * So it is two documents rather than one, and a dashboard still reads back the
  * shape it sent. The message on a null is written here rather than left to a
  * type error, because "expected string, received null" describes the shape and
  * says nothing about which act the sender was reaching for.
@@ -311,7 +260,8 @@ export const SellerNameSchema = z
 export const SellerNameRequestSchema = z
     .strictObject({
     /**
-     * What buyers are to read beside this merchant's products.
+     * What buyers are to read beside this merchant's products, where it is
+     * changing.
      *
      * The rule lives once, in `ServiceNameSchema`, and this reaches it through
      * a string that carries its own words for "this is not a name at all". A
@@ -320,18 +270,36 @@ export const SellerNameRequestSchema = z
      */
     seller_name: z
         .string({
-        // A field that is missing is a client with a bug and a field holding
-        // null is a client with a misunderstanding. Only the second gets this
-        // sentence; the first falls through to the ordinary words about a
-        // field that is not there, which is what its author needs to read.
+        // A field holding null is a client with a misunderstanding, and only
+        // that gets this sentence.
         error: (issue) => issue.input === undefined
             ? undefined
             : "a seller name cannot be taken away, only changed: a merchant who wants to stop being listed pauses their selling, which leaves their cards where they can put them back on sale",
     })
-        .pipe(ServiceNameSchema),
+        .pipe(ServiceNameSchema)
+        .optional(),
+    /**
+     * The https address of the merchant's own shop, where it is changing
+     * (ADR-0034). Like the name it is changed and never taken away: an agent
+     * holding an order that named a site has been told where to go, and a
+     * site that vanished from the same order would leave it nowhere.
+     */
+    seller_site: z
+        .string({
+        error: (issue) => issue.input === undefined
+            ? undefined
+            : "a seller's site cannot be taken away, only changed: send the address it has moved to",
+    })
+        .pipe(SellerSiteSchema)
+        .optional(),
+})
+    .refine((asked) => asked.seller_name !== undefined || asked.seller_site !== undefined, {
+    // A client that dropped both fields has a bug, and is told what this call
+    // takes rather than anything about taking a name away.
+    message: "a request names seller_name, seller_site or both: one that names neither changes nothing",
 })
     .meta({
-    description: "What a merchant sends to change the name their products are sold under. The same rule as the answer — at most 32 characters of printable ASCII, the catalog's rule rather than ours — and one difference: null is refused. A merchant goes from no name to a name and from one name to another, never back to none, because a payment request names the seller and there would be nobody to name: every card they have published would come off sale, which is an end to their selling arriving under the name of editing a setting. Somebody reaching for null wants one of two other things: a different name, which is this call with a different value, or an end to selling, which is the pause.",
+    description: "What a merchant sends to change the name their products are sold under, the address of their shop's own site, or both; a field left out stays as it was, and one of the two has to be there. The name is held to the catalog's rule rather than ours — at most 32 characters of printable ASCII — and is plain text. The site is an https origin and nothing after it, such as https://shop.example. Null is refused for either. A merchant goes from no name to a name and from one name to another, never back to none, because a payment request names the seller and there would be nobody to name: every card they have published would come off sale, which is an end to their selling arriving under the name of editing a setting. Somebody reaching for null wants one of two other things: a different name, which is this call with a different value, or an end to selling, which is the pause. A site is changed the same way and never taken away.",
 });
 /**
  * A change of the wallet that has been asked for, announced, and has not taken
@@ -339,10 +307,9 @@ export const SellerNameRequestSchema = z
  *
  * It exists because a replacement does not apply at once where the money is
  * real (ADR-0019). The address a merchant is paid at is the one setting whose
- * change redirects money, and any key of theirs reaches it — the cabinet's, or
- * one sitting in their own server's environment — so on the live deployment a
- * replacement is told to every account of the merchant first and takes effect
- * forty-eight hours after that. What this document says is the two facts a
+ * change redirects money, and a dashboard session that is not the owner's could
+ * ask for one, so on the live deployment a replacement is told to every account
+ * of the merchant first and takes effect forty-eight hours after that. What this document says is the two facts a
  * merchant needs in that window: what replaces the address, and from when.
  *
  * Both are required. An address with no moment says nothing about when the
@@ -390,9 +357,10 @@ export const PendingPayoutWalletSchema = z
  * without this they would ask again, or conclude the change was lost.
  *
  * It is carried without moving `CONTRACT_VERSION`, which is the one known
- * exception to the rule that a new required field moves it (ADR-0006 §2): no
- * worker of the SDK reads this route, so the version would stop every
- * installed worker for a field none of them sees. What that costs is that a
+ * exception to the rule that a new required field moves it once a merchant we
+ * do not control runs the SDK (ADR-0006 §2): no worker of the SDK reads this
+ * route, so the version would stop every installed worker for a field none of
+ * them sees. What that costs is that a
  * merchant's own code holding this schema from an older release of this
  * package refuses the answer until the package is upgraded.
  */
@@ -406,96 +374,3 @@ export const PayoutWalletSchema = z
     .meta({
     description: "The address a merchant's sales are paid into, and any change of it that is waiting. Payments are not held by anybody on the way: a buyer's agent pays payout_wallet directly, and it is the payTo of every payment request made for this merchant's products now. Null means nobody has set one, which is where every merchant starts; the field is always present rather than left out, because an absent field is indistinguishable from a client that dropped it. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent — so what a merchant reads back on a screen is character for character what they copied out of their wallet. On a deployment that settles on a real chain a merchant with no wallet here cannot publish a card, because the money from that card's sales would have nowhere to go. pending is a replacement that has been asked for and has not taken effect: on the live deployment a merchant who already has a wallet and asks for a different one is told of it by message, and the new address takes effect forty-eight hours later, so until takes_effect_at this answer names the address still paid and the waiting one beside it. A caller reading its old address back beside a pending change has not failed to write; the change is waiting. Null means nothing is waiting, which is every answer on the test channel and in a sandbox, where a change applies at once.",
 });
-/**
- * What a merchant sends to change where their sales are paid.
- *
- * The same field held to the same rule, and one difference, which is the same
- * difference the seller name has and rests on something harder. There is no
- * null. A merchant goes from having no wallet to having one and from one wallet
- * to another, and not back: a merchant who took their address away would keep
- * every card they had already published on sale, and the payment request an
- * agent is answered with cannot be built at all without an address — so the
- * products would stop being buyable and nothing anywhere would say why. What
- * somebody reaching for null actually wants is one of two other acts: a
- * different address, which is this same call, or an end to selling, which is
- * the pause, and the pause leaves their cards where they can put them back.
- *
- * There is nowhere here to put a key, and a document carrying one is refused
- * rather than trimmed. This contract knows where a merchant is paid and has no
- * business knowing anything that could spend it.
- */
-export const PayoutWalletRequestSchema = z
-    .strictObject({
-    /**
-     * Where this merchant's sales are to be paid.
-     *
-     * The rule lives once, in `EvmAddressSchema`, and this reaches it through a
-     * string that carries its own words for "this is not an address at all".
-     */
-    payout_wallet: z
-        .string({
-        // A field that is missing is a client with a bug and a field holding
-        // null is a client with a misunderstanding. Only the second gets this
-        // sentence; the first falls through to the ordinary words about a
-        // field that is not there.
-        error: (issue) => issue.input === undefined
-            ? undefined
-            : "a payout wallet cannot be taken away, only changed: a merchant who wants to stop being paid pauses their selling, which leaves their cards where they can put them back on sale — a merchant with cards on sale and no wallet has products a payment request cannot even be written for",
-    })
-        .pipe(EvmAddressSchema),
-})
-    .meta({
-    description: "What a merchant sends to set or change the address their sales are paid into. The same rule as the answer — 0x and forty hexadecimal characters, in lower case or in the exact mixed-case spelling a wallet shows — and one difference: null is refused. A merchant goes from no wallet to a wallet and from one wallet to another, never back to none, because their published cards stay on sale and a payment request for one of them cannot be written without an address. Somebody reaching for null wants either a different address, which is this call with a different value, or an end to selling, which is the pause. Nothing here takes a private key or a seed phrase, and a document carrying one is refused rather than ignored: this contract knows where a merchant is paid and nothing that could spend it.",
-});
-/**
- * What somebody sends to become a merchant.
- *
- * One field, and what is not here is most of what is worth reading. The address
- * and the password belong to the account rather than to the merchant, and they
- * stay on the other side of the boundary (ADR-0014 §1) — a gateway that took
- * either would be holding a person's credentials on the money path, which is
- * what this route's whole shape is arranged to avoid.
- *
- * The name the seller's products are sold under is not here either, and that
- * omission is a decision rather than a simplification. It is a public answer,
- * and asking for it here asks for it at the one moment a merchant knows least:
- * no products, no catalogue seen, no idea what the name is for. It is asked for
- * on the screen after this one instead, where there is room to say why it
- * matters, and it can be changed afterwards from the merchant's own settings.
- *
- * The shape refuses a name rather than ignoring one, because a field quietly
- * dropped is a person believing they have chosen what buyers will read.
- */
-export const RegistrationRequestSchema = z
-    .strictObject({
-    /** The code handed over with the address of the site. */
-    invitation: InvitationSchema,
-})
-    .meta({
-    description: "What somebody sends to become a merchant: the invitation code they were given, and nothing else. The name their products are sold under is deliberately not here — it is a public answer, and asked for on the way in it is answered by somebody with no products and no idea what the name is for; it is set afterwards, and changed afterwards, through the merchant's own call for it. Nothing about an account is here either: an address and a password belong to whatever signs the person in, and are never sent to the gateway. A document carrying either is refused rather than trimmed, because a field accepted and dropped is somebody believing they said something.",
-});
-/**
- * What registering answers with: a merchant and the key their cabinet will call
- * as them with.
- *
- * The key is made for a cabinet rather than for the merchant's own code, and
- * that is what the caller of this route is. So it is in no list: a merchant who
- * has just registered has no keys of their own at all, and the first one they
- * do have is one they ask for. No row travels beside the secret for the same
- * reason no row appears in the list — the merchant did not issue it and cannot
- * disable it, so an identifier for it would be a value with nothing to do.
- *
- * No name comes back either, because none was chosen. A merchant who has just
- * registered is listed under nothing at all, and a field here would either be a
- * name this call invented or a null that says the same thing at more length.
- */
-export const RegisteredMerchantSchema = z
-    .strictObject({
-    /** The merchant that now exists, which every key and card of theirs names. */
-    merchant_id: IdentifierSchema,
-    /** The key itself, shown once, exactly as issuing one shows it. */
-    secret: KeySecretSchema,
-})
-    .meta({
-    description: "What registering produced: the merchant, and the key whoever registered them will call as them with. The key is readable here and nowhere afterwards, so whoever made this call is the only party that can keep it. It is a key made for a cabinet rather than one of the merchant's own: it appears in no list of their keys and the call that revokes a key refuses its kind by name, so no row for it comes back here either. A merchant who has just registered has no keys of their own until they ask for one. The merchant is listed under no name yet and this answer carries none — the name their products are sold under is chosen afterwards, and until it is, publishing a card is refused. What this answer does not carry either is any notion of an account or a session: registering makes a merchant and a key, and whatever signs a person in is on the other side of this call.",
-});

package/dist/order-status.d.ts

@@ -31,10 +31,11 @@
  * order is reading the wrong list.
  */
 import { z } from "zod";
-export declare const ORDER_STATUSES: readonly ["in_progress", "delivered", "rejected", "payment_unresolved", "declined", "expired", "cancelled", "refund_due", "refunded", "delivered_unpaid"];
+export declare const ORDER_STATUSES: readonly ["in_progress", "delivered", "shipped", "rejected", "payment_unresolved", "declined", "expired", "cancelled", "refund_due", "refunded", "delivered_unpaid"];
 export declare const OrderStatusSchema: z.ZodEnum<{
     delivered: "delivered";
     in_progress: "in_progress";
+    shipped: "shipped";
     rejected: "rejected";
     payment_unresolved: "payment_unresolved";
     declined: "declined";

package/dist/order-status.js

@@ -36,10 +36,22 @@ export const ORDER_STATUSES = Object.freeze([
     "in_progress",
     /** Success: the product is with the agent and the money with the merchant. */
     "delivered",
+    /**
+     * A parcel is with the carrier and the money with the merchant (ADR-0033):
+     * the merchant recorded its shipment, and the order carries it. This is the
+     * last word Agentify has about the parcel. Every protocol that uses the word
+     * goes on past it to arrival; this one does not, because nothing reports an
+     * arrival here, and whether the parcel arrives is between the buyer and the
+     * merchant — the seller's site is where to ask.
+     */
+    "shipped",
     /**
      * Closed and the buyer's money is known not to have moved — the product was
      * gone, the parameters did not fit, the payment failed its check, the charge
-     * came back failed, or a synchronous handler refused.
+     * came back failed, or a synchronous handler refused. On a parcel, the
+     * product being gone is the merchant's price answer saying "not available",
+     * which there can also mean the merchant does not ship to that place or the
+     * address lacks what their carrier needs.
      *
      * The machine keeps a finer distinction behind this word: a purchase that
      * never reached the merchant and one the merchant refused are separate

package/dist/order.d.ts

@@ -45,6 +45,23 @@ export declare const OrderSchema: 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>;
 export type Order = z.infer<typeof OrderSchema>;

package/dist/order.js

@@ -36,6 +36,7 @@
 import { z } from "zod";
 import { ParamNameSchema } from "./param-spec.js";
 import { IdentifierSchema, SalePriceSchema } from "./primitives.js";
+import { ErasedShipToSchema, ShipToLocalitySchema, ShipToSchema } from "./ship-to.js";
 export const OrderSchema = z.strictObject({
     /**
      * The order's identifier, which is also its idempotency key: the same string
@@ -67,6 +68,18 @@ export const OrderSchema = z.strictObject({
      * identifier can release it here.
      */
     price_id: IdentifierSchema.optional(),
+    /**
+     * Where a parcel goes (ADR-0032), present on a parcel's order and never on
+     * any other, in one of three shapes as the order goes along. Before it is
+     * paid, the locality the price was asked for — the place and nothing about
+     * who. Once paid, the whole address, which the merchant stores before taking
+     * the order on. Once Agentify no longer needs it — the order taken on, its
+     * shipment recorded, or the order ended or owing a refund without being taken
+     * on — only when Agentify erased its copy. From then on the merchant has the
+     * address only as they stored it from the paid order, and the order is not
+     * handed to a handler again.
+     */
+    ship_to: z.union([ShipToSchema, ShipToLocalitySchema, ErasedShipToSchema]).optional(),
     /**
      * Whether this is a test order.
      *

package/dist/primitives.d.ts

@@ -67,6 +67,18 @@ export declare const MoneySchema: z.ZodObject<{
  */
 export declare const TimestampSchema: z.ZodISODateTime;
 export declare const IdentifierSchema: z.ZodString;
+/**
+ * A word of a vocabulary that grows without a version (ADR-0006 §5): a mode
+ * on the card an agent reads, a status on its order.
+ *
+ * The storefront has no version, so a word added later reaches agents that
+ * still hold this contract, and they read it rather than refuse the document.
+ * Open is not anything at all, though: a word is read by a program and shown
+ * to a person, so it has the shape every word in those lists already has —
+ * lower-case letters, digits and underscores, starting with a letter — and
+ * markup, padding or a page of text is not one.
+ */
+export declare const OpenWordSchema: z.ZodString;
 /**
  * The price a purchase actually went through at.
  *
@@ -100,4 +112,5 @@ export type CurrencyCode = z.infer<typeof CurrencyCodeSchema>;
 export type Money = z.infer<typeof MoneySchema>;
 export type Timestamp = z.infer<typeof TimestampSchema>;
 export type Identifier = z.infer<typeof IdentifierSchema>;
+export type OpenWord = z.infer<typeof OpenWordSchema>;
 export type SalePrice = z.infer<typeof SalePriceSchema>;

package/dist/primitives.js

@@ -100,6 +100,20 @@ export const IdentifierSchema = z.string().regex(
 // then anything printable, then a last character under the same rule as the
 // first. One character on its own is allowed; nothing at all is not.
 new RegExp(`^[^\\s${UNPRINTABLE}](?:[^${UNPRINTABLE}]*[^\\s${UNPRINTABLE}])?$`, "u"), "an identifier must not be empty, padded with whitespace, or carry characters that show nothing");
+/**
+ * A word of a vocabulary that grows without a version (ADR-0006 §5): a mode
+ * on the card an agent reads, a status on its order.
+ *
+ * The storefront has no version, so a word added later reaches agents that
+ * still hold this contract, and they read it rather than refuse the document.
+ * Open is not anything at all, though: a word is read by a program and shown
+ * to a person, so it has the shape every word in those lists already has —
+ * lower-case letters, digits and underscores, starting with a letter — and
+ * markup, padding or a page of text is not one.
+ */
+export const OpenWordSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{0,63}$/, "a word of this vocabulary is lower-case letters, digits and underscores, starts with a letter and is at most sixty-four characters long");
 /**
  * The price a purchase actually went through at.
  *

package/dist/quote.d.ts

@@ -38,6 +38,12 @@ export declare const QuotePurposeSchema: z.ZodEnum<{
 export declare const QuoteRequestSchema: 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";

package/dist/quote.js

@@ -25,6 +25,7 @@
 import { z } from "zod";
 import { ParamNameSchema } from "./param-spec.js";
 import { IdentifierSchema, MoneySchema, TimestampSchema } from "./primitives.js";
+import { ShipToLocalitySchema } from "./ship-to.js";
 /**
  * Why we are asking.
  *
@@ -44,6 +45,15 @@ export const QuoteRequestSchema = z.strictObject({
     // Same dropped key as everywhere this contract parses free-form names; see
     // `PROTOTYPE_KEY_IS_DROPPED` in `param-spec.ts`.
     params: z.record(ParamNameSchema, z.unknown()).optional(),
+    /**
+     * Where a parcel goes, as its price is asked (ADR-0032): the country, the
+     * state, the city and the postal code, and nothing about who receives it. A
+     * price question reaches a merchant for purchases never made, and a shipping
+     * rate needs the place alone. Present on a parcel's question only; the
+     * answer is the whole price, shipping to this place included, or not
+     * available where the merchant does not ship there.
+     */
+    ship_to: ShipToLocalitySchema.optional(),
     /**
      * The identifier of this question, which comes back attached to the order.
      *

package/dist/receipt.d.ts

@@ -40,18 +40,20 @@ import { z } from "zod";
  * if it did not, there was never anything to record. That is the same promise
  * the portal makes to the buyer in words: we say so when we learn.
  *
- * That leaves four: paid and still running, paid and delivered, paid and owed
- * back, paid and paid back.
+ * That leaves five: paid and still running, paid and delivered, a paid parcel
+ * shipped (ADR-0033), paid and owed back, paid and paid back.
  *
  * What this list does not say is when a receipt is written at all, and a reader
  * should not infer it from here. That is the gateway's, and a gateway that
- * writes one only as goods are released will only ever produce `delivered` —
- * so a consumer must not read the presence of these four as a promise that a
- * receipt exists for every payment that executed.
+ * writes one only as goods are released or a parcel ships will only ever
+ * produce `delivered` and `shipped` — so a consumer must not read the presence
+ * of these five as a promise that a receipt exists for every payment that
+ * executed.
  */
 export declare const ReceiptOutcomeSchema: z.ZodEnum<{
     delivered: "delivered";
     in_progress: "in_progress";
+    shipped: "shipped";
     refund_due: "refund_due";
     refunded: "refunded";
 }>;
@@ -70,6 +72,7 @@ export declare const ReceiptSchema: z.ZodObject<{
     outcome: z.ZodEnum<{
         delivered: "delivered";
         in_progress: "in_progress";
+        shipped: "shipped";
         refund_due: "refund_due";
         refunded: "refunded";
     }>;

package/dist/receipt.js

@@ -41,16 +41,23 @@ import { IdentifierSchema, SalePriceSchema, TimestampSchema } from "./primitives
  * if it did not, there was never anything to record. That is the same promise
  * the portal makes to the buyer in words: we say so when we learn.
  *
- * That leaves four: paid and still running, paid and delivered, paid and owed
- * back, paid and paid back.
+ * That leaves five: paid and still running, paid and delivered, a paid parcel
+ * shipped (ADR-0033), paid and owed back, paid and paid back.
  *
  * What this list does not say is when a receipt is written at all, and a reader
  * should not infer it from here. That is the gateway's, and a gateway that
- * writes one only as goods are released will only ever produce `delivered` —
- * so a consumer must not read the presence of these four as a promise that a
- * receipt exists for every payment that executed.
+ * writes one only as goods are released or a parcel ships will only ever
+ * produce `delivered` and `shipped` — so a consumer must not read the presence
+ * of these five as a promise that a receipt exists for every payment that
+ * executed.
  */
-export const ReceiptOutcomeSchema = z.enum(["in_progress", "delivered", "refund_due", "refunded"]);
+export const ReceiptOutcomeSchema = z.enum([
+    "in_progress",
+    "delivered",
+    "shipped",
+    "refund_due",
+    "refunded",
+]);
 export const ReceiptSchema = z.strictObject({
     /**
      * The receipt's own identifier. In the modes where the payment goes first,