@nuanu-ai/agentify-contracts 0.7.0 → 0.8.0

package/dist/api.js

@@ -42,23 +42,23 @@
  * later by a merchant who took an order on and now has the goods or has run
  * out of them. The order machine keeps the same two apart, and in the
  * synchronous mode it is the returned answer that exists and the explicit
- * calls that do not. The addendum of 2026-08-26 to ADR-0004 settles this; §2
- * of that decision, read alone, leaves the synchronous handler with no address
- * at all.
+ * calls that do not. ADR-0004 §2 settles this.
  */
 import { z } from "zod";
 import { CardSchema, FulfillmentSchema, MerchantCardSchema, PublicCardSchema, SellerSchema, } from "./card.js";
 import { WorkerEnvelopeSchema } from "./envelope.js";
 import { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RefusalSchema } from "./handler.js";
-import { DashboardKeySchema, DisabledKeySchema, ForgottenDashboardKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+import { DisabledKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, PayoutWalletSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 import { OrderSchema } from "./order.js";
 import { OrderStatusSchema } from "./order-status.js";
 import { ParamNameSchema } from "./param-spec.js";
-import { IdentifierSchema, OpenWordSchema, SalePriceSchema } from "./primitives.js";
+import { IdentifierSchema, OpenWordSchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 import { QuoteResponseSchema } from "./quote.js";
 import { ReceiptSchema } from "./receipt.js";
 import { CallErrorSchema, OrderCallResultSchema, PublishResultSchema } from "./results.js";
 import { SellingStateSchema } from "./selling.js";
+import { ShipToSchema } from "./ship-to.js";
+import { RecordedShipmentSchema } from "./shipment.js";
 /**
  * An order together with the word for where it stands.
  *
@@ -304,9 +304,17 @@ export const PurchaseRequestSchema = z
     // The 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()),
+    /**
+     * Where a parcel goes (ADR-0032). Required on the purchase of a card whose
+     * fulfillment is "ship", and refused on any other: only a parcel needs an
+     * address, and one sent with anything else would be a buyer's details
+     * handed over for nothing. Sent again with the payment it must be the one
+     * that was priced, or be left out.
+     */
+    ship_to: ShipToSchema.optional(),
 })
     .meta({
-    description: "What an agent supplies to buy: the purchase parameters, empty for a product that needs none. The names are held to the shape a card could have declared and no further — that these values fit this card is checked against that card at the moment of purchase.",
+    description: "What an agent supplies to buy: the purchase parameters, empty for a product that needs none, and for a parcel the address it goes to. The names are held to the shape a card could have declared and no further — that these values fit this card is checked against that card at the moment of purchase. ship_to is required when the card's fulfillment is \"ship\" and refused on any other card. The merchant's price question receives only its locality; the merchant receives the whole address once the order is paid. Sent again with the payment it must be the same address, or be left out, in which case the payment is for the address that was priced; a different one is refused before the payment is checked, and is a new purchase. That holds while Agentify still holds the address: once it has let go of it — the order taken on, ended, or owing a refund without being taken on — there is nothing to compare with, a payment's ship_to is checked for its shape only, and the answer is the order as it stands.",
 });
 /**
  * What became of a purchase, told to the agent that made it.
@@ -344,6 +352,15 @@ export const PurchaseRequestSchema = z
  * payment that failed its check both still arrive as a bare `rejected`,
  * because neither was worded by anybody.
  */
+/**
+ * A shipment's expected window as an agent reads it: open, as the shipment
+ * around it is, so a field added to the window later is ignored by an agent
+ * built before it rather than making the whole status unreadable (ADR-0006
+ * §5). Opening it makes a new schema, which carries none of the old one's
+ * description, so the description is carried across.
+ */
+const closedWindow = RecordedShipmentSchema.shape.estimated_delivery.unwrap();
+const openWindow = closedWindow.loose().meta(closedWindow.meta() ?? {});
 export const AgentOrderStatusSchema = z
     .looseObject({
     order_id: IdentifierSchema,
@@ -415,12 +432,33 @@ export const AgentOrderStatusSchema = z
      * says null for exactly as long as that is true.
      */
     delivered: DeliverySchema.nullable(),
+    /**
+     * A parcel's shipment once its merchant has recorded it, and null until
+     * then (ADR-0033). Present on a parcel's order and on no other.
+     *
+     * It is beside `delivered` rather than in it because nothing reached the
+     * agent: what the merchant handed a carrier is not goods in hand, and
+     * `delivered` stays null on a parcel for that reason. It is the last thing
+     * Agentify knows about the parcel.
+     */
+    shipment: RecordedShipmentSchema.extend({ estimated_delivery: openWindow.optional() })
+        .loose()
+        .nullable()
+        .optional(),
+    /**
+     * When a parcel has to be with its carrier by, as an absolute instant: the
+     * card's time to ship counted from the charge, and null until the order is
+     * paid (ADR-0033). Present on a parcel's order and on no other. A parcel
+     * not shipped by then leaves its merchant owing a refund, which this
+     * document then says.
+     */
+    ship_by: TimestampSchema.nullable().optional(),
     /**
      * Whether the money behind this purchase was real.
      *
      * The receipt a merchant reads carries this word already, and the buyer's
      * own view of the same purchase is the one place it matters more: a
-     * sandbox settles against nothing (ADR-0008) and every other field here
+     * sandbox settles against nothing (ADR-0020) and every other field here
      * reads exactly as it would after a real charge. Without it, this document
      * is indistinguishable from proof of a purchase that moved money, which is
      * the one thing it must never be mistaken for.
@@ -466,7 +504,7 @@ export const AgentOrderStatusSchema = z
     seller: SellerSchema.loose(),
 })
     .meta({
-    description: 'What became of one purchase, in the words an agent and a merchant both read: where the order stands, what it was priced at, the goods once they are the buyer\'s, and why the merchant would not sell where that is what ended it. "status_url" is where this document is read again — the whole address of the order\'s status route, and the place an agent that bought goods that come later collects them. It is absolute and called as it stands, and it is the address the gateway is configured to answer as, never one taken from the request that asked. It is smaller than the merchant\'s own view of the same order on purpose — no merchant account, no merchant\'s own key for the product, none of the purchase parameters and nothing about any other order. The price is what the buyer was asked for and not proof that anything was charged: an order that was priced and then ended without a sale still carries it, and the status is what says which happened. A null price means nobody ever named one for this order, and a null delivery means there are no goods here to hand over; both fields are always present, because an absent field is a silence a reader cannot tell from an oversight. "refusal" is the exception and is present only where a merchant refused: their own short code to branch on and their own sentence to show, carried across unchanged. The code is an open set — "out_of_stock", "invalid_params" and "cannot_fulfill" are read the same way by everybody, and a merchant whose reason fits none of them sends their own word, so an unfamiliar code has to fall through to the sentence rather than break a reader. An absent "refusal" means there is no refusal to quote and never that one was dropped, which leaves two endings still coarse: "rejected" also covers a product that was gone and a payment that failed its check, and neither of those was worded by anybody — the first because a price answer of "not available" carries no words, the second because it is refused at the door in an error envelope instead. A null delivery is likewise not a promise that no goods were ever made: a purchase whose charge failed or went unanswered can leave goods the buyer has not paid for, and this document withholds them rather than describing them. Every answer says whether the money behind the purchase was real: a gateway settling against nothing produces every other field here exactly as a real charge would, so a reader taking this for proof of a payment has to read that word first. "seller" is who sold it, as the merchant gave it and as the catalog shows it beside their cards: the name and the site of their shop, which Agentify did not check, and the site is where to take what this document cannot answer. "status" is a word whose known values are listed beside it, and more may be added: a word a reader does not know is not an ending it knows, so it asks again later and does not buy again on its strength. This document and every part inside it may also gain fields; a reader ignores the ones it does not know.',
+    description: 'What became of one purchase, in the words an agent and a merchant both read: where the order stands, what it was priced at, the goods once they are the buyer\'s, and why the merchant would not sell where that is what ended it. "status_url" is where this document is read again — the whole address of the order\'s status route, and the place an agent that bought goods that come later collects them. It is absolute and called as it stands, and it is the address the gateway is configured to answer as, never one taken from the request that asked. It is smaller than the merchant\'s own view of the same order on purpose — no merchant account, no merchant\'s own key for the product, none of the purchase parameters and nothing about any other order. The price is what the buyer was asked for and not proof that anything was charged: an order that was priced and then ended without a sale still carries it, and the status is what says which happened. A null price means nobody ever named one for this order, and a null delivery means there are no goods here to hand over; both fields are always present, because an absent field is a silence a reader cannot tell from an oversight. A parcel\'s order also carries "shipment", its merchant\'s record of handing it to a carrier and null until then, and "ship_by", the instant it has to be with a carrier by and null until it is paid; no other order carries either. On a parcel "delivered" stays null, because nothing reached the agent: its status reads "shipped" once the shipment is recorded, and that is the last word Agentify has about it. "refusal" is the exception and is present only where a merchant refused: their own short code to branch on and their own sentence to show, carried across unchanged. The code is an open set — "out_of_stock", "invalid_params" and "cannot_fulfill" are read the same way by everybody, and a merchant whose reason fits none of them sends their own word, so an unfamiliar code has to fall through to the sentence rather than break a reader. An absent "refusal" means there is no refusal to quote and never that one was dropped, which leaves two endings still coarse: "rejected" also covers a product that was gone and a payment that failed its check, and neither of those was worded by anybody — the first because a price answer of "not available" carries no words, the second because it is refused at the door in an error envelope instead. A null delivery is likewise not a promise that no goods were ever made: a purchase whose charge failed or went unanswered can leave goods the buyer has not paid for, and this document withholds them rather than describing them. Every answer says whether the money behind the purchase was real: a gateway settling against nothing produces every other field here exactly as a real charge would, so a reader taking this for proof of a payment has to read that word first. "seller" is who sold it, as the merchant gave it and as the catalog shows it beside their cards: the name and the site of their shop, which Agentify did not check, and the site is where to take what this document cannot answer. "status" is a word whose known values are listed beside it, and more may be added: a word a reader does not know is not an ending it knows, so it asks again later and does not buy again on its strength. This document and every part inside it may also gain fields; a reader ignores the ones it does not know.',
 });
 /**
  * The catalog as an agent reads it.
@@ -508,15 +546,8 @@ export const cardsOf = (page) => page.items.flatMap((item) => {
     const mode = FulfillmentSchema.safeParse(read.data.fulfillment);
     return mode.success ? [{ ...read.data, fulfillment: mode.data }] : [];
 });
-/**
- * The methods this surface uses.
- *
- * `DELETE` is here for the one call that removes rows rather than marking them,
- * and it earns the third verb rather than being folded into a POST: what it
- * does to a key is not what disabling one does, and a surface that spelled both
- * as a POST would be inviting a reader to think it was.
- */
-export const HTTP_METHODS = Object.freeze(["GET", "POST", "DELETE"]);
+/** The methods this surface uses. */
+export const HTTP_METHODS = Object.freeze(["GET", "POST"]);
 /**
  * Which door a call is behind.
  *
@@ -704,7 +735,6 @@ export const ERROR_CODES = Object.freeze([
     "charset_unsupported",
     "encoding_unsupported",
     "gateway_failed",
-    "key_made_for_a_dashboard",
     "key_opened_this_call",
     "malformed_body",
     "malformed_query",
@@ -713,9 +743,7 @@ export const ERROR_CODES = Object.freeze([
     "no_such_key",
     "no_such_order",
     "no_such_route",
-    "not_a_dashboard_key",
     "not_authorised",
-    "not_invited",
     "not_selling",
     "not_this_purchase",
     "order_closed_before_it_was_priced",
@@ -724,10 +752,8 @@ export const ERROR_CODES = Object.freeze([
     "payment_already_spent",
     "payment_not_taken",
     "payment_not_verified",
-    "wallet_change_not_announced",
-    "wallet_change_nobody_to_tell",
-    "wallet_change_raced",
-    "wallet_change_unconfirmed",
+    "ship_to_changed",
+    "ship_to_does_not_fit",
 ]);
 /**
  * Every call of the surface, under the name it is known by in both programs.
@@ -801,14 +827,6 @@ export const API_ROUTES = Object.freeze({
         description: "Starts selling again. Cards paused in their own right stay paused: stopping all selling did not forget which they were, and putting them all back on sale would sell products their merchant took off. The answer is the whole catalog, so which cards actually came back is a fact rather than an inference. A merchant who has left is refused: leaving closed the orders that were open and left refunds owed, and this switch unwinds none of it, so a departure is not undone here.",
         response: { document: MerchantCardListSchema },
     },
-    register_merchant: {
-        method: "POST",
-        path: "/v0/merchants",
-        auth: "none",
-        description: "Makes a merchant and the key whoever registered them will call as them with — both of those or neither. This call is not on the public origin: only the dashboard makes it, from inside the stack, when a signed-in person presses its one control, and from outside the path answers as one the site does not have. It takes no key because nobody registering has one yet; what stands in the door instead is an invitation code out of the gateway's own configuration, and a gateway with no code configured refuses every registration in the same words a wrong code gets, so this call is not a way of finding out whether registration is open. The key comes back once and is readable nowhere afterwards, and it is a key made for a dashboard: it is in no list of the merchant's keys and is not disabled through them, so no row for it comes back here — only the key itself. What the new merchant does not have is a name: they are listed under nothing until somebody sets one at POST /v0/seller-name, and until then publishing a card is refused, so a dashboard that registers a person and takes them straight to a publish screen has built a dead end. Nothing about an account, an address or a password reaches this call either: those belong to whatever signs a person in, on the other side of it. Unlike every other call on this surface that writes something, a repeat of this one is not safe and there is nothing here that could make it so: two calls make two merchants, and the caller holds a key to only the second. A caller whose connection drops before the answer arrives cannot find out from here whether the first landed — it has no key with which to ask — and the merchant it may have made cannot be swept away afterwards, because a merchant is what every card, order and receipt is owned by.",
-        request: RegistrationRequestSchema,
-        response: { document: RegisteredMerchantSchema },
-    },
     get_seller_name: {
         method: "GET",
         path: "/v0/seller-name",
@@ -828,29 +846,21 @@ export const API_ROUTES = Object.freeze({
         method: "GET",
         path: "/v0/payout-wallet",
         auth: "merchant_key",
-        description: "The address the sales of the merchant this call's own key belongs to are paid into now, and any change of it that is waiting. Payments here are not held by anybody on the way: a buyer's agent pays this address directly and no balance of the merchant's is ever held on our side, which is why the address has to be theirs and why this call exists. Any key of the merchant's reads it, the keys made for their own code included; only the merchant's dashboard sets it. Null is the ordinary answer for a merchant who has set none, and it is an answer rather than a refusal — a merchant with no wallet exists and has a settings screen to draw. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent to set it, so a screen showing it shows what the merchant copied out of their wallet character for character. On the live deployment a replacement for an address already set takes effect forty-eight hours after it was announced to the merchant, and until then this answers with the address still paid and names the waiting one, with the moment it takes effect, under pending. Null there means nothing is waiting, which is always the answer on the test channel and in a sandbox.",
-        response: { document: PayoutWalletSchema },
-    },
-    set_payout_wallet: {
-        method: "POST",
-        path: "/v0/payout-wallet",
-        auth: "merchant_key",
-        description: "Sets the address the sales of the merchant this call's own key belongs to are paid into. Only the merchant's dashboard makes this call, with the key made for it, from inside the stack, when a person sets the wallet on its Settings screen: keys operate the shop, and where the shop's money goes is set through the dashboard. The public origin does not route this call at all, so from outside it is a path the site does not have; at the gateway a key made for the merchant's own code is refused under not_a_dashboard_key, for the first address as for any other, and nothing is written or announced. The first address a merchant sets applies at once; on the live deployment every dashboard account of the merchant is then told of it, and a message that cannot be sent refuses nothing. On the live deployment a different address after that does not: before anything is written, every account that names the merchant is sent a message saying what changes, when, and that it was asked for in the dashboard, and the change takes effect forty-eight hours after those messages were handed to the mail provider. Until then every payment request names the address that applies now, and the answer carries the waiting one under pending with the moment it takes effect. Asking again for the address already waiting changes nothing, sends no second message and restarts no clock, and answers with the same pending change, so a retry after a dropped connection is safe; a different address replaces the waiting one and starts the forty-eight hours again; asking for the address that applies now cancels the waiting change. On the test channel and in a sandbox every change applies at once and no message is sent. The answer is the wallet as it now stands, read back from what was written rather than echoed, in the mixed-case spelling a wallet shows. Setting the address that already applies, with nothing waiting, changes nothing and answers the same way. An address whose capital letters do not agree with the rest of it is refused and nothing is written, because those capitals are a checksum and letters that disagree mean a character is wrong — and an address that is wrong is another perfectly good address belonging to somebody else. What this call will not do is take an address away: null is refused, because without an address there is nowhere to send the money and every published card would quietly come off sale — ending the selling under the name of editing a setting; somebody reaching for that wants either a different address, which is this same call, or an end to selling, which is the pause. On a deployment that settles on a real chain, a merchant with no wallet set here cannot publish a card, and the refusal at the publish says so.",
-        request: PayoutWalletRequestSchema,
+        description: "The address the sales of the merchant this call's own key belongs to are paid into now, and any change of it that is waiting. Payments here are not held by anybody on the way: a buyer's agent pays this address directly and no balance of the merchant's is ever held on our side, which is why the address has to be theirs and why this call exists. Any key of the merchant's reads it; none sets it. A person signed in to the merchant's dashboard sets it on its Settings screen. On the live deployment a first address applies at once and is announced afterwards, and a replacement is told to every account of the merchant first and waits. Null is the ordinary answer for a merchant who has set none, and it is an answer rather than a refusal — a merchant with no wallet exists and has a settings screen to draw. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent to set it, so a screen showing it shows what the merchant copied out of their wallet character for character. On the live deployment a replacement for an address already set takes effect forty-eight hours after it was announced to the merchant, and until then this answers with the address still paid and names the waiting one, with the moment it takes effect, under pending. Null there means nothing is waiting, which is always the answer on the test channel and in a sandbox.",
         response: { document: PayoutWalletSchema },
     },
     list_keys: {
         method: "GET",
         path: "/v0/keys",
         auth: "merchant_key",
-        description: "The keys the merchant this call's own key belongs to made for their own code, the revoked ones among them, and never the keys themselves. A merchant who has only ever signed into a dashboard has none of these, and an empty list is that answer rather than a fault: the key a dashboard calls with is made for the dashboard and is in no list here, because the merchant did not issue it and cannot disable it. Whether the list is all of the rest is not something this document claims either: paging is not designed, and the absence of a field about it is not a promise that there is no more. The answer also names the key the call was made with, as this_call, and that field is the reason this is not a bare list: a merchant cannot disable the key their own call was made with, so a screen drawn without knowing which key that is would offer a button the gateway refuses. That identifier is not among the keys listed when the caller is a dashboard, and a client that looked it up among the rows has to be built for finding none. Every row also says when a call was last seen on that key, which is the field a screen offering to revoke one is worth drawing at all — and it is a recorded answer rather than an exact one, lagging by minutes, and blank both for a key nothing has called and for one made before this gateway began recording, which nothing here tells apart. This call is itself one of those calls, so the key it was made with reads as used at about this moment, whether or not it appears in the list.",
+        description: "The keys the merchant this call's own key belongs to made for their own code, the revoked ones among them, and never the keys themselves. A merchant who has only ever signed into a dashboard has none of these, and an empty list is that answer rather than a fault: the dashboard calls with no key. Whether the list is all of the rest is not something this document claims either: paging is not designed, and the absence of a field about it is not a promise that there is no more. The answer also names the key the call was made with, as this_call, and that field is the reason this is not a bare list: a merchant cannot disable the key their own call was made with, so a screen drawn without knowing which key that is would offer a button the gateway refuses. It is always one of the keys listed, since every key is one the merchant issued. Every row also says when a call was last seen on that key, which is the field a screen offering to revoke one is worth drawing at all — and it is a recorded answer rather than an exact one, lagging by minutes, and blank both for a key nothing has called and for one made before this gateway began recording, which nothing here tells apart. This call is itself one of those calls, so the key it was made with reads as used at about this moment.",
         response: { document: MerchantKeyListSchema },
     },
     issue_key: {
         method: "POST",
         path: "/v0/keys",
         auth: "merchant_key",
-        description: "Issues another key for the merchant's own code, to the merchant this call's own key belongs to. The key is generated here and never taken from the caller, and it comes back exactly once — what is kept afterwards is a digest, so nothing can show it again. A merchant with several keys can hand one to each worker and revoke one without touching the others, which is the whole reason a key is a row. This call cannot make the other kind of key: what a dashboard calls with is asked for at POST /v0/keys/dashboard, and a key made here is one the merchant sees, names and revokes.",
+        description: "Issues another key for the merchant's own code, to the merchant this call's own key belongs to. The key is generated here and never taken from the caller, and it comes back exactly once — what is kept afterwards is a digest, so nothing can show it again. A merchant with several keys can hand one to each worker and revoke one without touching the others, which is the whole reason a key is a row. The merchant's dashboard issues keys the same way, and every key a merchant has is one they see, name and revoke.",
         request: IssueKeyRequestSchema,
         response: { document: IssuedKeySchema },
     },
@@ -858,23 +868,9 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/keys/:key_id/disable",
         auth: "merchant_key",
-        description: "Stops one of this merchant's keys working, from that instant, and touches no other key. Disabling a key that is already disabled changes nothing and answers the same way, keeping the instant it was first revoked at, so a retry after a dropped connection is safe. Three refusals are worth knowing before a screen is built on this. A key belonging to another merchant is answered exactly as a key that does not exist, so this call is not a way of counting somebody else's keys. A key made for a dashboard is refused under key_made_for_a_dashboard, whoever asks and however they came by its identifier: this call reaches the keys a merchant issued for their own code and nothing else, and replacing the one a dashboard holds is POST /v0/keys/dashboard and the forgetting beside it. And the key this call was made with cannot be disabled by it — that one click and no more: the refusal is about the key in front of it, so a merchant holding two keys of their own can still disable either with the other, and two such calls at one moment can leave them with none of their own. That is not refused here or anywhere, and what it costs is their own code going quiet rather than the way back in, which is a key of the other kind.",
+        description: "Stops one of this merchant's keys working, from that instant, and touches no other key. Disabling a key that is already disabled changes nothing and answers the same way, keeping the instant it was first revoked at, so a retry after a dropped connection is safe. Two refusals are worth knowing before a screen is built on this. A key belonging to another merchant is answered exactly as a key that does not exist, so this call is not a way of counting somebody else's keys. And the key this call was made with cannot be disabled by it — that one click and no more: the refusal is about the key in front of it, so a merchant holding two keys of their own can still disable either with the other, and two such calls at one moment can leave them with none of their own. That is not refused here or anywhere, and what it costs is their own code going quiet rather than the way back in, which is signing in to the dashboard with the link mailed to them.",
         response: { document: DisabledKeySchema },
     },
-    issue_dashboard_key: {
-        method: "POST",
-        path: "/v0/keys/dashboard",
-        auth: "merchant_key",
-        description: "Makes a key for a dashboard to call as this merchant with, and hands it back once. This call and the forgetting beside it are not on the public origin: only the dashboard makes them, from inside the stack, and from outside the path answers as one the site does not have. It is a key of a different kind from the ones at /v0/keys: the merchant did not ask for it, never sees it, and it appears in no list of theirs — so nothing comes back but the key itself. What this is for is a dashboard that replaces its own credential every time somebody signs in, which is what keeps a copy of a dashboard's database from being a set of working keys for long. The call is refused to a key made for the merchant's own code, under not_a_dashboard_key: these two calls are the dashboard's own, and a merchant asking for one would be asking for a credential to a dashboard they are not standing in.",
-        response: { document: DashboardKeySchema },
-    },
-    forget_dashboard_key: {
-        method: "DELETE",
-        path: "/v0/keys/dashboard",
-        auth: "merchant_key",
-        description: "Removes the key this call was made with, and no other. Like the call that makes such a key, it is not on the public origin: only the dashboard makes it, from inside the stack. It is removed rather than revoked: a merchant never issued one, never sees one and would never read a revoked one back, so a row kept for the history would be history for nobody. There are no parameters, and that is not a convenience — a key belonging to anybody else, this merchant included, is unreachable here by construction, because the only way to name a key is to be holding it. What a caller does with this is put a key of its own beyond use once it has stopped signing in with it: ask for a fresh key, write it down where the account is kept, then forget the one that was there. A caller that forgets first can be left naming a key that no longer exists, which is the one order that locks somebody out. Made a second time with the same key it is refused as a key that does not exist, which is safe and is the confirmation the first one landed: either way that key is gone and nothing else has moved. It is refused to a key made for the merchant's own code, under not_a_dashboard_key: those are revoked from the list they appear on, at an instant their owner can read back, and removing the row outright would take that history away.",
-        response: { document: ForgottenDashboardKeySchema },
-    },
     get_order: {
         method: "GET",
         path: "/v0/orders/:order_id",
@@ -917,7 +913,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/orders/:order_id/deliver",
         auth: "merchant_key",
-        description: "The goods for an order the merchant took on earlier — the asynchronous mode's closure verb, called by the merchant rather than by the SDK. Idempotent by the order's identifier: called again after a dropped connection it delivers nothing twice and charges nothing twice, so repeating it is safe and keeping a note of what was already sent is not needed. A late call is accepted too — where the delivery deadline has passed and the refund has not yet been paid out, delivering closes the debt.",
+        description: "The goods for an order the merchant took on earlier — the asynchronous mode's closure verb, called by the merchant rather than by the SDK. Idempotent by the order's identifier: called again after a dropped connection it delivers nothing twice and charges nothing twice, so repeating it is safe and keeping a note of what was already sent is not needed. A late call is accepted too — where the delivery deadline has passed and the refund has not yet been paid out, delivering closes the debt. On a parcel's order the body is its shipment instead of goods (the shipment document: a carrier, a tracking number or null, and optionally a tracking page and an expected window). Agentify records the instant the call arrived as when the parcel shipped, the order reads shipped, and the shipment cannot be changed afterwards: the same one sent again succeeds, and a different one is refused with shipment_already_recorded.",
         request: DeliverySchema,
         response: { document: OrderCallResponseSchema },
     },
@@ -965,7 +961,7 @@ export const API_ROUTES = Object.freeze({
         method: "GET",
         path: "/x402/orders/:order_id/status",
         auth: "order_id",
-        description: "What became of a purchase, for the agent that made it: where the order stands, what it sold for, and the goods once they are the buyer's. It is the route an agent that bought a product whose goods come later collects them on, and without it half a catalogue takes money and hands back an order nobody can act on. Every answer that carries the order document names this address in status_url, whole and ready to call, the purchase's own answer included. An order whose goods come later is owed them by the delivery deadline its card carried when the order was opened, counted from its payment: fulfill_deadline_seconds where the card names one, and a day where it names none. An order still without goods at that deadline becomes refund_due, and a paid order the merchant refuses or leaves behind becomes it sooner: the merchant owes the buyer the goods or the money back. That is not an ending, and it carries no further deadline. Goods the merchant delivers after it still appear here and settle the debt, and the order becomes delivered. Nor does refund_due say whether the money has come back: the merchant returns it from their own wallet, the gateway has no way yet to record that they did, and until it has one no order moves on to refunded — a buyer already paid back still reads refund_due here. So an agent holding refund_due can still collect goods here, nothing here tells it when to stop asking, and its own wallet is where a refund shows. Knowing the order's identifier is the proof (ADR-0011), so this call takes no key: an agent has no account and no registration, and the identifier is handed to exactly one party. Two things follow for whoever mounts it. Which door a call is behind is read off auth and never off the address, whatever the prefixes happen to agree on today. And an identifier that names no order must be answered exactly as any other unknown one is, or the refusal becomes a way of counting the orders behind it.",
+        description: "What became of a purchase, for the agent that made it: where the order stands, what it sold for, and the goods once they are the buyer's. It is the route an agent that bought a product whose goods come later collects them on, and without it half a catalogue takes money and hands back an order nobody can act on. Every answer that carries the order document names this address in status_url, whole and ready to call, the purchase's own answer included. An order whose goods come later is owed them by the delivery deadline its card carried when the order was opened, counted from its payment: fulfill_deadline_seconds where the card names one, and a day where it names none. An order still without goods at that deadline becomes refund_due, and a paid order the merchant refuses or leaves behind becomes it sooner: the merchant owes the buyer the goods or the money back. That is not an ending, and it carries no further deadline. Goods the merchant delivers after it still appear here and settle the debt, and the order becomes delivered. Nor does refund_due say whether the money has come back: the merchant returns it from their own wallet, the gateway has no way yet to record that they did, and until it has one no order moves on to refunded — a buyer already paid back still reads refund_due here. So an agent holding refund_due can still collect goods here, nothing here tells it when to stop asking, and its own wallet is where a refund shows. Knowing the order's identifier is the proof (ADR-0011), so this call takes no key: an agent has no account and no registration, and the identifier is handed only to the parties to the sale — the agent that bought, its merchant and Agentify — and appears in no catalog or listing. Two things follow for whoever mounts it. Which door a call is behind is read off auth and never off the address, whatever the prefixes happen to agree on today. And an identifier that names no order must be answered exactly as any other unknown one is, or the refusal becomes a way of counting the orders behind it.",
         response: { document: AgentOrderStatusSchema },
     },
 });

package/dist/card.d.ts

@@ -33,12 +33,16 @@ import type { Money } from "./primitives.js";
  * `sync` — in the answer to the purchase, and the payment executes last, after
  * the merchant has delivered. `async` — later, by a separate call, and the
  * payment executes at the moment of purchase. `confirm` — the merchant is
- * asked first, and the payment executes right after they say yes.
+ * asked first, and the payment executes right after they say yes. `ship` — a
+ * parcel the merchant hands to a carrier (ADR-0033): the payment executes at
+ * the moment of purchase, as in `async`, and the order carries the buyer's
+ * address until the merchant takes it on, or it ends without them.
  */
 export declare const FulfillmentSchema: z.ZodEnum<{
     sync: "sync";
     async: "async";
     confirm: "confirm";
+    ship: "ship";
 }>;
 /**
  * How the price and availability of this card are asked for, if they are.
@@ -66,30 +70,6 @@ export declare const PriceCheckSchema: z.ZodUnion<readonly [z.ZodLiteral<"handle
  * wherever a merchant's listing name is written down.
  */
 export declare const ServiceNameSchema: z.ZodString;
-/**
- * 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;
 /**
  * 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).
@@ -139,7 +119,7 @@ export declare const CardSchema: z.ZodObject<{
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
-    result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+    result: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
             number: "number";
@@ -148,18 +128,20 @@ export declare const CardSchema: z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
+    }, z.core.$strict>>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     fulfillment: z.ZodDefault<z.ZodEnum<{
         sync: "sync";
         async: "async";
         confirm: "confirm";
+        ship: "ship";
     }>>;
     price_check: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strict>]>>;
     confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
     fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+    ship_within_seconds: z.ZodOptional<z.ZodInt>;
 }, z.core.$strict>;
 export type Fulfillment = z.infer<typeof FulfillmentSchema>;
 export type PriceCheck = z.infer<typeof PriceCheckSchema>;
@@ -186,7 +168,8 @@ export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"
     price: Money | string;
     /** Each field whole, or written as its type word alone: `email: 'string'`. */
     params?: ParamSpecInput;
-    result: ParamSpecInput;
+    /** Left out on a parcel's card, whose mode fixes what the agent receives. */
+    result?: ParamSpecInput;
     /** Left out on a card that is delivered in the answer to the purchase. */
     fulfillment?: Fulfillment;
 };
@@ -200,7 +183,11 @@ export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"
  * place that picks.
  */
 export declare const purchaseCheckFor: (card: Card) => z.ZodType;
-/** The check this card's delivery is held to. */
+/**
+ * The check this card's delivery is held to: the goods its `result` declared,
+ * or for a parcel, which is not delivered with goods at all, its shipment
+ * (ADR-0033).
+ */
 export declare const deliveryCheckFor: (card: Card) => z.ZodType;
 /**
  * The fields of a card as an agent reads it in a catalog.
@@ -271,7 +258,7 @@ export declare const PublicCardSchema: z.ZodObject<{
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
-    result: z.ZodRecord<z.ZodString, z.ZodObject<{
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
             number: "number";
@@ -280,7 +267,7 @@ export declare const PublicCardSchema: z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$loose>>;
+    }, z.core.$loose>>>;
     price_checked_at_purchase: z.ZodBoolean;
     seller: z.ZodObject<{
         name: z.ZodNullable<z.ZodString>;
@@ -290,9 +277,11 @@ export declare const PublicCardSchema: z.ZodObject<{
         sync: "sync";
         async: "async";
         confirm: "confirm";
+        ship: "ship";
     }>, z.ZodString]>;
     fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
     confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
+    ship_within_seconds: z.ZodOptional<z.ZodInt>;
 }, z.core.$loose>;
 export type PublicCard = z.infer<typeof PublicCardSchema>;
 /**
@@ -379,7 +368,10 @@ export interface BazaarDeclaration {
     readonly input: Record<string, unknown>;
     /** The JSON Schema that body is held to, derived from the card's `params`. */
     readonly inputSchema: Record<string, unknown>;
-    /** An example of what arrives on delivery, derived from the card's `result`. */
+    /**
+     * An example of what arrives on delivery, derived from the card's `result`,
+     * or for a parcel the record of its shipment.
+     */
     readonly output: {
         readonly example: Record<string, unknown>;
     };
@@ -444,7 +436,7 @@ export declare const MerchantCardSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>>;
-        result: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        result: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
             type: z.ZodEnum<{
                 string: "string";
                 number: "number";
@@ -453,18 +445,20 @@ export declare const MerchantCardSchema: z.ZodObject<{
             }>;
             required: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>;
+        }, z.core.$strict>>>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         fulfillment: z.ZodDefault<z.ZodEnum<{
             sync: "sync";
             async: "async";
             confirm: "confirm";
+            ship: "ship";
         }>>;
         price_check: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
             url: z.ZodURL;
         }, z.core.$strict>]>>;
         confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
         fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
+        ship_within_seconds: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
     selling: z.ZodEnum<{
         open: "open";