@nuanu-ai/agentify-contracts 0.6.0 → 0.7.0

package/dist/api.js

@@ -47,14 +47,14 @@
  * at all.
  */
 import { z } from "zod";
-import { CardSchema, MerchantCardSchema, PublicCardSchema } from "./card.js";
+import { CardSchema, FulfillmentSchema, MerchantCardSchema, PublicCardSchema, SellerSchema, } from "./card.js";
 import { WorkerEnvelopeSchema } from "./envelope.js";
 import { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RefusalSchema } from "./handler.js";
-import { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+import { DashboardKeySchema, DisabledKeySchema, ForgottenDashboardKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 import { OrderSchema } from "./order.js";
 import { OrderStatusSchema } from "./order-status.js";
 import { ParamNameSchema } from "./param-spec.js";
-import { IdentifierSchema, SalePriceSchema } from "./primitives.js";
+import { IdentifierSchema, OpenWordSchema, SalePriceSchema } from "./primitives.js";
 import { QuoteResponseSchema } from "./quote.js";
 import { ReceiptSchema } from "./receipt.js";
 import { CallErrorSchema, OrderCallResultSchema, PublishResultSchema } from "./results.js";
@@ -345,7 +345,7 @@ export const PurchaseRequestSchema = z
  * because neither was worded by anybody.
  */
 export const AgentOrderStatusSchema = z
-    .strictObject({
+    .looseObject({
     order_id: IdentifierSchema,
     /**
      * Where this order is read again: the whole address of its status route,
@@ -379,7 +379,16 @@ export const AgentOrderStatusSchema = z
     status_url: z
         .url()
         .regex(/^https?:\/\//, "an order's status address is a whole http or https address, not a path"),
-    status: OrderStatusSchema,
+    /**
+     * Where the order stands, as a word whose known values are listed beside
+     * it (ADR-0006 §5). The storefront has no version, so a word added later
+     * reaches agents that still hold this contract: one they do not know is
+     * not an ending they know, and they ask again later rather than buy again
+     * on its strength. The merchant's own view of the order reads the same
+     * words from a closed list. Two branches, as a card's mode is
+     * (`PublicCardSchema`), so the known words still cross into the export.
+     */
+    status: z.union([OrderStatusSchema, OpenWordSchema]),
     /**
      * The price this order was priced at, or null where nobody ever named one
      * for it. It is the order's own price and not the card's number: a card
@@ -393,7 +402,7 @@ export const AgentOrderStatusSchema = z
      * field's, and a reader taking this for an amount charged would be
      * reconciling against sales that never happened.
      */
-    price: SalePriceSchema.nullable(),
+    price: SalePriceSchema.loose().nullable(),
     /**
      * The goods, once they are the buyer's — the delivery as the merchant
      * wrote it, and null until then.
@@ -443,10 +452,21 @@ export const AgentOrderStatusSchema = z
      * present pair is always somebody's actual answer rather than a word this
      * gateway picked for them.
      */
-    refusal: RefusalSchema.optional(),
+    refusal: RefusalSchema.loose().optional(),
+    /**
+     * Who sold it: the name and the site the merchant gave, read as their
+     * merchant stands now (ADR-0034).
+     *
+     * An agent holding an order and nothing else is the one with a question
+     * the order cannot answer — a parcel that did not arrive, a return — and
+     * this is where it learns where to take it. It is what the catalog already
+     * shows every agent beside the merchant's cards and nothing more: not the
+     * merchant's account, not their own key for the product, not the card.
+     */
+    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, 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.',
+    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.',
 });
 /**
  * The catalog as an agent reads it.
@@ -456,13 +476,37 @@ export const AgentOrderStatusSchema = z
  * Until then it makes no claim about completeness, and that is stated in the
  * document itself: an agent must not read the absence of a field about paging
  * as a promise that there is nothing more.
+ *
+ * It is read card by card (ADR-0006 §5). The storefront has no version, so a
+ * card of a mode or a shape added later reaches agents that still hold this
+ * contract, and one card they cannot read must leave every other card for
+ * sale. So the page holds its items as whatever they are, and `cardsOf` reads
+ * each one on its own against the card an agent reads.
  */
 export const CatalogPageSchema = z
-    .strictObject({
-    items: z.array(PublicCardSchema),
+    .looseObject({
+    items: z.array(z.unknown().meta({
+        description: "One product, read on its own as a public_card. An item a reader cannot read as one is passed over, and the rest of the page stands.",
+    })),
 })
     .meta({
-    description: "Products offered for sale, as an agent reads them. This document does not say whether it is the whole catalog: paging is not designed, and when it is, this object grows the field that answers it. Until then the absence of such a field is not a promise that there is no more.",
+    description: "Products offered for sale, as an agent reads them. This document does not say whether it is the whole catalog: paging is not designed, and when it is, this object grows the field that answers it. Until then the absence of such a field is not a promise that there is no more. Each item is read on its own as a public_card, and one a reader cannot read — a mode or a shape added after the contract it holds — is passed over while the rest of the page stands. This document may also gain fields; a reader ignores the ones it does not know.",
+});
+/**
+ * The cards of a catalog page a reader of this contract can buy from, each read
+ * on its own.
+ *
+ * Two kinds of item are passed over, and the rest of the page stands. One that
+ * does not read as a card at all, and one that does but is sold in a mode this
+ * contract does not name: its reader cannot know when such goods arrive or when
+ * the money moves, so it must not buy on it.
+ */
+export const cardsOf = (page) => page.items.flatMap((item) => {
+    const read = PublicCardSchema.safeParse(item);
+    if (!read.success)
+        return [];
+    const mode = FulfillmentSchema.safeParse(read.data.fulfillment);
+    return mode.success ? [{ ...read.data, fulfillment: mode.data }] : [];
 });
 /**
  * The methods this surface uses.
@@ -660,7 +704,7 @@ export const ERROR_CODES = Object.freeze([
     "charset_unsupported",
     "encoding_unsupported",
     "gateway_failed",
-    "key_made_for_a_cabinet",
+    "key_made_for_a_dashboard",
     "key_opened_this_call",
     "malformed_body",
     "malformed_query",
@@ -669,7 +713,7 @@ export const ERROR_CODES = Object.freeze([
     "no_such_key",
     "no_such_order",
     "no_such_route",
-    "not_a_cabinet_key",
+    "not_a_dashboard_key",
     "not_authorised",
     "not_invited",
     "not_selling",
@@ -718,7 +762,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/catalog/publish",
         auth: "merchant_key",
-        description: "Publishes one product, or says what is wrong with the card. Republishing under the same merchant_item_id is how a card is changed rather than how a second one appears. The catalog identifier comes back beside ok, and from then on it is what an agent, a purchase and a receipt all use. A card that is not published comes back as ok:false under the code card_rejected, never retryable, with every finding named in the error's problems. Three findings this can come back with are not about the card at all. A merchant who has not set the name their products are sold under gets no_seller_name, and the way past it is POST /v0/seller-name: a card published without one reaches a buyer's agent inside a payment request that names no seller. On a deployment that settles on a real chain, a merchant who has set no wallet gets no_payout_wallet, and the way past it is the Settings screen of the merchant's cabinet, where a person signed in sets one: the money from that card's sales is paid to the merchant's own address directly, and without one there is nowhere for it to go. On the live deployment, a merchant the operator has not admitted once gets no_operator_approval. That decision has no merchant API: test publication remains available, while live publication remains closed until the operator grants it. Every applicable finding comes back in the same problems list as whatever is wrong with the card, so one answer carries everything standing between this card and the catalog.",
+        description: "Publishes one product, or says what is wrong with the card. Republishing under the same merchant_item_id is how a card is changed rather than how a second one appears. The catalog identifier comes back beside ok, and from then on it is what an agent, a purchase and a receipt all use. A card that is not published comes back as ok:false under the code card_rejected, never retryable, with every finding named in the error's problems. Three findings this can come back with are not about the card at all. A merchant who has not set the name their products are sold under gets no_seller_name, and the way past it is POST /v0/seller-name: a card published without one reaches a buyer's agent inside a payment request that names no seller. On a deployment that settles on a real chain, a merchant who has set no wallet gets no_payout_wallet, and the way past it is the Settings screen of the merchant's dashboard, where a person signed in sets one: the money from that card's sales is paid to the merchant's own address directly, and without one there is nowhere for it to go. On the live deployment, a merchant the operator has not admitted once gets no_operator_approval. That decision has no merchant API: test publication remains available, while live publication remains closed until the operator grants it. Every applicable finding comes back in the same problems list as whatever is wrong with the card, so one answer carries everything standing between this card and the catalog.",
         request: CardSchema,
         response: { document: PublishResultSchema },
     },
@@ -761,7 +805,7 @@ export const API_ROUTES = Object.freeze({
         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 cabinet 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 cabinet: 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 cabinet 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.",
+        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 },
     },
@@ -784,14 +828,14 @@ 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 cabinet 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.",
+        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 cabinet 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 cabinet. 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_cabinet_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 cabinet 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 cabinet, 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.",
+        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,
         response: { document: PayoutWalletSchema },
     },
@@ -799,14 +843,14 @@ export const API_ROUTES = Object.freeze({
         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 cabinet has none of these, and an empty list is that answer rather than a fault: the key a cabinet calls with is made for the cabinet 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 cabinet, 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 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.",
         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 cabinet calls with is asked for at POST /v0/keys/cabinet, 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. 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.",
         request: IssueKeyRequestSchema,
         response: { document: IssuedKeySchema },
     },
@@ -814,22 +858,22 @@ 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 cabinet is refused under key_made_for_a_cabinet, 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 cabinet holds is POST /v0/keys/cabinet 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. 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.",
         response: { document: DisabledKeySchema },
     },
-    issue_cabinet_key: {
+    issue_dashboard_key: {
         method: "POST",
-        path: "/v0/keys/cabinet",
+        path: "/v0/keys/dashboard",
         auth: "merchant_key",
-        description: "Makes a key for a cabinet 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 cabinet 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 cabinet that replaces its own credential every time somebody signs in, which is what keeps a copy of a cabinet'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_cabinet_key: these two calls are the cabinet's own, and a merchant asking for one would be asking for a credential to a cabinet they are not standing in.",
-        response: { document: CabinetKeySchema },
+        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_cabinet_key: {
+    forget_dashboard_key: {
         method: "DELETE",
-        path: "/v0/keys/cabinet",
+        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 cabinet 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_cabinet_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: ForgottenCabinetKeySchema },
+        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",
@@ -865,7 +909,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/orders/:order_id/answer",
         auth: "merchant_key",
-        description: "What the merchant's handler returned for an order it was given: the goods, a refusal, or an acceptance. The SDK sends this itself, in every mode, and it is the only way a synchronous answer reaches us at all — there the handler's return is the delivery and the refusal, and the explicit deliver and refuse calls do not apply. An acceptance is answered with the word accepted — the order is taken on, and the goods follow through the deliver call — or with already_delivered when the order closed before the acceptance reached us, which a redelivered order makes ordinary rather than a fault. A synchronous answer that arrives after its deadline is not an error: the work exists and a repeat purchase collects it, and the answer says so in the word purchase_already_closed.",
+        description: "What the merchant's handler returned for an order it was given: the goods, a refusal, or an acceptance. The SDK sends this itself, in every mode, and it is the only way a synchronous answer reaches us at all — there the handler's return is the delivery and the refusal, and the explicit deliver and refuse calls do not apply. An acceptance is answered with the word accepted — the order is taken on, and the goods follow through the deliver call — or with already_delivered when the order closed before the acceptance reached us, which a redelivered order makes ordinary rather than a fault. A synchronous order still waiting for its goods cannot be taken on, because the deliver call that would carry them later does not exist in that mode: the acceptance is refused with not_applicable_in_mode, the order is not sent to the handler again for it, and it closes on its deadline with nothing charged. A synchronous answer that arrives after its deadline is not an error: the work exists and a repeat purchase collects it, and the answer says so in the word purchase_already_closed.",
         request: HandlerAnswerSchema,
         response: { document: OrderCallResponseSchema },
     },
@@ -889,7 +933,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/orders/:order_id/accept",
         auth: "merchant_key",
-        description: "Takes an order on: the merchant will deliver, and says how long they expect it to take when they know. An empty body is a complete answer. The same order is taken on again every time it is redelivered, and the success carries no word: taking on an order that is already delivered succeeds here too, and this route does not tell the two apart. The answer route does, because it carries whichever of the three things a handler returned.",
+        description: "Takes an order on: the merchant will deliver, and says how long they expect it to take when they know. An empty body is a complete answer. A synchronous order still waiting for its goods cannot be taken on, because its goods travel only in the handler's answer: the call is refused with not_applicable_in_mode. The same order is taken on again every time it is redelivered, and the success carries no word: taking on an order that is already delivered succeeds here too, and this route does not tell the two apart. The answer route does, because it carries whichever of the three things a handler returned.",
         request: AcceptanceSchema,
         response: { document: OrderAcceptResponseSchema },
     },

package/dist/card.d.ts

@@ -66,6 +66,44 @@ 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).
+ *
+ * Both are the merchant's own word and nothing here checked either, which the
+ * description says to the reader who acts on it — a name and a site can be
+ * anybody's. Null is "none given": a merchant who gave no site has none here,
+ * and a name is missing only from an order whose merchant has since lost it.
+ */
+export declare const SellerSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    site: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Seller = z.infer<typeof SellerSchema>;
 /**
  * The words a merchant puts on one product so an agent searching a catalog can
  * find it.
@@ -164,45 +202,64 @@ export type CardInput = Omit<Card, "price" | "params" | "result" | "fulfillment"
 export declare const purchaseCheckFor: (card: Card) => z.ZodType;
 /** The check this card's delivery is held to. */
 export declare const deliveryCheckFor: (card: Card) => z.ZodType;
-export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    description: z.ZodString;
-    price: z.ZodObject<{
-        amount: z.ZodString;
-        currency: z.ZodString;
-    }, z.core.$strict>;
-    as_of: z.ZodISODateTime;
-    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    result: z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    price_checked_at_purchase: z.ZodBoolean;
-    fulfillment: z.ZodLiteral<"sync">;
-}, z.core.$strict>, z.ZodObject<{
+/**
+ * The fields of a card as an agent reads it in a catalog.
+ *
+ * The published card is what a merchant writes; this is what we say about it
+ * to somebody who is about to spend money. Every difference between the two is
+ * a decision, so each one is written down.
+ *
+ * Our catalog identifier replaces the merchant's own key. `id` is what a
+ * purchase, a receipt and a status all use, while `merchant_item_id` is unique
+ * only inside one merchant's catalog and means nothing outside it. An agent
+ * handed both would use the wrong one some of the time, for no gain.
+ *
+ * `price_check` is gone and one fact out of it stays. The address of a
+ * merchant's pricing service is infrastructure of theirs, no agent ever calls
+ * it, and publishing it would put it in front of everyone. What an agent does
+ * act on is that the price will be asked again: the number in the catalog is
+ * what it compares when choosing, and the sale can go through at another. So
+ * the projection carries `price_checked_at_purchase` and nothing else about
+ * how the asking is done. The flag says we ask, not that we get an answer —
+ * what happens when a merchant is silent depends on the mode and is the
+ * gateway's, and this document does not claim to know it.
+ *
+ * Both deadlines stay, because they are the merchant's promise to the agent
+ * about how long it may wait, and the agent is told them before it pays. The
+ * projection writes each only on a mode that has it, and the document says so
+ * in words rather than as structure: it takes fields added later (ADR-0006
+ * §5), so a field an agent does not expect is one it ignores, not one it can
+ * refuse.
+ *
+ * The mode is a word whose known values are listed beside it, for the same
+ * reason. The storefront has no version, so a mode added later reaches agents
+ * that still hold this contract, and to them it has to be a card to pass over
+ * rather than a catalog they cannot read.
+ *
+ * `as_of` is added: the moment the price shown here was published. A price
+ * with no moment behind it cannot be judged stale, and this is the only
+ * freshness claim a catalog makes.
+ *
+ * `tags` are gone as well, and that one is a decision rather than an omission.
+ * They are words a merchant chose so that a search in a discovery catalog finds
+ * this product, held to that catalog's own rule about length and alphabet. Our
+ * own catalog is not searched that way — an agent reading it has the whole
+ * page — so carrying them here would put a foreign catalog's constraint in
+ * front of a reader who has no use for it.
+ *
+ * Who sells is here as the merchant gave it, a name and the site of their
+ * shop (ADR-0034), and as nothing more: no profile, no contact of ours, and no
+ * claim that either was checked. Who "we" are to the buyer is a question this
+ * document still does not answer.
+ */
+export declare const PublicCardSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     description: z.ZodString;
     price: z.ZodObject<{
         amount: z.ZodString;
         currency: z.ZodString;
-    }, z.core.$strict>;
+    }, z.core.$loose>;
     as_of: z.ZodISODateTime;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
@@ -213,7 +270,7 @@ export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
+    }, z.core.$loose>>>;
     result: z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
@@ -223,45 +280,38 @@ export declare const PublicCardSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         required: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
+    }, z.core.$loose>>;
     price_checked_at_purchase: z.ZodBoolean;
-    fulfillment: z.ZodLiteral<"async">;
+    seller: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        site: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>;
+    fulfillment: z.ZodUnion<readonly [z.ZodEnum<{
+        sync: "sync";
+        async: "async";
+        confirm: "confirm";
+    }>, z.ZodString]>;
     fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
-}, z.core.$strict>, z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    description: z.ZodString;
-    price: z.ZodObject<{
-        amount: z.ZodString;
-        currency: z.ZodString;
-    }, z.core.$strict>;
-    as_of: z.ZodISODateTime;
-    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    result: z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    price_checked_at_purchase: z.ZodBoolean;
-    fulfillment: z.ZodLiteral<"confirm">;
     confirm_deadline_seconds: z.ZodOptional<z.ZodInt>;
-    fulfill_deadline_seconds: z.ZodOptional<z.ZodInt>;
-}, z.core.$strict>], "fulfillment">;
+}, z.core.$loose>;
 export type PublicCard = z.infer<typeof PublicCardSchema>;
+/**
+ * A card as `publicCardOf` builds it: the card's own fields without the index
+ * signature the open schema adds, and a mode this version knows.
+ *
+ * An agent reads a card with `PublicCardSchema`, which takes fields and modes
+ * added later (ADR-0006 §5); what is built is held to the opposite. The type
+ * catches part of that: an unknown field written straight into the returned
+ * object is a compile error. It does not reach inside the card's parts, which
+ * keep the open schema's index signatures, nor tie a deadline to its mode. The
+ * gateway's outbound check holds the rest, at every depth, before anything is
+ * sent (`checksBeforeSending`).
+ */
+export type ProjectedCard = {
+    [Field in keyof PublicCard as string extends Field ? never : Field]: PublicCard[Field];
+} & {
+    readonly fulfillment: Fulfillment;
+};
 /**
  * The card as an agent reads it, built from the card the merchant published.
  *
@@ -272,13 +322,15 @@ export type PublicCard = z.infer<typeof PublicCardSchema>;
  * every agent by default, and the first anybody heard of it would be a
  * merchant's pricing address in a public catalog.
  *
- * The two things the card cannot know are passed in: the catalog identifier we
- * issued when it was published, and the moment its price was published.
+ * The three things the card cannot know are passed in: the catalog identifier
+ * we issued when it was published, the moment its price was published, and
+ * who sells it as their merchant stands now.
  */
 export declare const publicCardOf: (card: Card, issued: {
     readonly id: string;
     readonly as_of: string;
-}) => PublicCard;
+    readonly seller: Seller;
+}) => ProjectedCard;
 /**
  * One card as a discovery catalog reads it: what an agent that has never seen
  * our own catalog finds when it searches somewhere else.