@nuanu-ai/agentify-contracts 0.6.0 → 0.7.0

package/dist/index.js

@@ -22,33 +22,33 @@
  */
 import { z } from "zod";
 import { AgentOrderStatusSchema, CatalogPageSchema, ErrorEnvelopeSchema, MerchantCardListSchema, OrderAcceptResponseSchema, OrderCallResponseSchema, OrderListQuerySchema, OrderListSchema, OrderWithStatusSchema, PurchaseRequestSchema, QuoteAnswerAckSchema, ReceiptListSchema, WorkerPollRequestSchema, WorkerPollResponseSchema, } from "./api.js";
-import { CardSchema, FulfillmentSchema, MerchantCardSchema, PriceCheckSchema, PublicCardSchema, ServiceNameSchema, TagsSchema, } from "./card.js";
+import { CardSchema, FulfillmentSchema, MerchantCardSchema, PriceCheckSchema, PublicCardSchema, SellerSchema, SellerSiteSchema, ServiceNameSchema, TagsSchema, } from "./card.js";
 import { WorkerEnvelopeSchema } from "./envelope.js";
 import { OrderEventSchema, RefundDueReasonSchema } from "./events.js";
 import { EvmAddressSchema } from "./evm-address.js";
 import { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-import { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+import { DashboardKeySchema, DisabledKeySchema, ForgottenDashboardKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 import { OrderSchema } from "./order.js";
 import { OrderStatusSchema } from "./order-status.js";
 import { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, } from "./param-spec.js";
-import { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
+import { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, OpenWordSchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 import { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 import { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
 import { CallErrorSchema, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
 import { SellingStateSchema } from "./selling.js";
-export { AgentOrderStatusSchema, API_ROUTES, AUTH_MODES, CatalogPageSchema, ERROR_CODES, ErrorEnvelopeSchema, expandPath, HTTP_METHODS, MERCHANT_KEY_HEADER, MerchantCardListSchema, merchantKeyFrom, merchantKeyHeaderValue, mountableRoutes, OrderAcceptResponseSchema, OrderCallResponseSchema, OrderListQuerySchema, OrderListSchema, OrderWithStatusSchema, PurchaseRequestSchema, pathParamsOf, QuoteAnswerAckSchema, ReceiptListSchema, WorkerPollRequestSchema, WorkerPollResponseSchema, } from "./api.js";
-export { bazaarDeclarationOf, CardSchema, deliveryCheckFor, FulfillmentSchema, MerchantCardSchema, PriceCheckSchema, PublicCardSchema, publicCardOf, purchaseCheckFor, ServiceNameSchema, TagsSchema, } from "./card.js";
+export { AgentOrderStatusSchema, API_ROUTES, AUTH_MODES, CatalogPageSchema, cardsOf, ERROR_CODES, ErrorEnvelopeSchema, expandPath, HTTP_METHODS, MERCHANT_KEY_HEADER, MerchantCardListSchema, merchantKeyFrom, merchantKeyHeaderValue, mountableRoutes, OrderAcceptResponseSchema, OrderCallResponseSchema, OrderListQuerySchema, OrderListSchema, OrderWithStatusSchema, PurchaseRequestSchema, pathParamsOf, QuoteAnswerAckSchema, ReceiptListSchema, WorkerPollRequestSchema, WorkerPollResponseSchema, } from "./api.js";
+export { bazaarDeclarationOf, CardSchema, deliveryCheckFor, FulfillmentSchema, MerchantCardSchema, PriceCheckSchema, PublicCardSchema, publicCardOf, purchaseCheckFor, SellerSchema, SellerSiteSchema, ServiceNameSchema, TagsSchema, } from "./card.js";
 export { WORKER_ENVELOPE_KINDS, WORKER_ENVELOPE_PAYLOADS, WorkerEnvelopeSchema, } from "./envelope.js";
 export { ORDER_EVENT_TYPES, OrderEventSchema, RefundDueReasonSchema } from "./events.js";
 export { checksummedAddressOf, EvmAddressSchema } from "./evm-address.js";
 export { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RECOMMENDED_REFUSAL_CODES, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+export { DashboardKeySchema, DisabledKeySchema, ForgottenDashboardKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 export { OrderSchema } from "./order.js";
 export { ORDER_STATUSES, OrderStatusSchema } from "./order-status.js";
 export { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, PROTOTYPE_KEY_IS_DROPPED, paramSpecToValidator, } from "./param-spec.js";
 export { notPlainTextIn } from "./plain-text.js";
 export { PAYABLE_CURRENCIES, PAYABLE_DECIMALS, priceProblemsOf } from "./price-rule.js";
-export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
+export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, OpenWordSchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
 export { CARD_REJECTED, CallErrorSchema, MERCHANT_FINDINGS, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
@@ -76,17 +76,17 @@ export const schemas = Object.freeze({
     acceptance: AcceptanceSchema,
     agent_order_status: AgentOrderStatusSchema,
     amount: AmountSchema,
-    cabinet_key: CabinetKeySchema,
     call_error: CallErrorSchema,
     card: CardSchema,
     catalog_page: CatalogPageSchema,
     currency_code: CurrencyCodeSchema,
+    dashboard_key: DashboardKeySchema,
     delivery: DeliverySchema,
     disabled_key: DisabledKeySchema,
     error_envelope: ErrorEnvelopeSchema,
     evm_address: EvmAddressSchema,
     field_spec: FieldSpecSchema,
-    forgotten_cabinet_key: ForgottenCabinetKeySchema,
+    forgotten_dashboard_key: ForgottenDashboardKeySchema,
     fulfillment: FulfillmentSchema,
     handler_answer: HandlerAnswerSchema,
     identifier: IdentifierSchema,
@@ -97,6 +97,7 @@ export const schemas = Object.freeze({
     merchant_key: MerchantKeySchema,
     merchant_key_list: MerchantKeyListSchema,
     money: MoneySchema,
+    open_word: OpenWordSchema,
     order: OrderSchema,
     order_accept_response: OrderAcceptResponseSchema,
     order_call_response: OrderCallResponseSchema,
@@ -130,9 +131,11 @@ export const schemas = Object.freeze({
     refusal: RefusalSchema,
     refusal_code: RefusalCodeSchema,
     sale_price: SalePriceSchema,
+    seller: SellerSchema,
     seller_name: SellerNameSchema,
     seller_name_request: SellerNameRequestSchema,
     selling_state: SellingStateSchema,
+    seller_site: SellerSiteSchema,
     service_name: ServiceNameSchema,
     tags: TagsSchema,
     timestamp: TimestampSchema,

package/dist/merchant.d.ts

@@ -3,7 +3,7 @@
  * wallet their sales are paid into, and the keys they open the door with.
  *
  * The first two belong together because registering is the act that produces
- * both: one call makes the merchant and the key its cabinet will call as them
+ * both: one call makes the merchant and the key its dashboard will call as them
  * with, and what comes back carries that key once. Split across two files, a
  * reader working out what registering leaves a merchant holding would have to
  * read both to find that it is a key of a kind no list here carries. The name is here for the same reason read the other way round — it is a
@@ -52,8 +52,8 @@ export declare const MerchantKeySchema: z.ZodObject<{
  * broken.
  *
  * It is not always one of the keys beside it, and that is the thing a reader is
- * likeliest to assume and be wrong about. A cabinet calls with a key made for a
- * cabinet, and those are in nobody's list, so a client that looked this
+ * likeliest to assume and be wrong about. A dashboard calls with a key made for a
+ * dashboard, and those are in nobody's list, so a client that looked this
  * identifier up among the rows would find nothing — which is an answer rather
  * than an error, and a screen has to be built for it.
  *
@@ -109,10 +109,10 @@ export declare const DisabledKeySchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 /**
- * A key made for a cabinet, which is the secret and nothing else.
+ * A key made for a dashboard, which is the secret and nothing else.
  *
  * Every other answer that makes a key carries the row beside it, and this one
- * cannot. A key made for a cabinet is in no merchant's list — they did not
+ * cannot. A key made for a dashboard is in no merchant's list — they did not
  * issue it and have no reason to know it exists — so an identifier here would
  * name a row that no screen of theirs draws and no call of theirs reaches: not
  * the list it is absent from, and not the revoking, which takes the keys a
@@ -120,7 +120,7 @@ export declare const DisabledKeySchema: z.ZodObject<{
  * is put it on the row of whoever just signed in, and that is the whole of what
  * it needs.
  */
-export declare const CabinetKeySchema: z.ZodObject<{
+export declare const DashboardKeySchema: z.ZodObject<{
     secret: z.ZodString;
 }, z.core.$strict>;
 /**
@@ -133,7 +133,7 @@ export declare const CabinetKeySchema: z.ZodObject<{
  * is done, and it is said in a field rather than left to a status code so that
  * a client reads one document and not two kinds of evidence.
  */
-export declare const ForgottenCabinetKeySchema: z.ZodObject<{
+export declare const ForgottenDashboardKeySchema: z.ZodObject<{
     forgotten: z.ZodLiteral<true>;
 }, z.core.$strict>;
 /**
@@ -155,6 +155,7 @@ export declare const ForgottenCabinetKeySchema: z.ZodObject<{
  */
 export declare const SellerNameSchema: z.ZodObject<{
     seller_name: z.ZodNullable<z.ZodString>;
+    seller_site: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 /**
  * What a merchant sends to change what their products are sold under.
@@ -169,13 +170,14 @@ export declare const SellerNameSchema: z.ZodObject<{
  * which is this same call, or an end to selling, which is the pause — and the
  * pause leaves their cards where they can find them again.
  *
- * So it is two documents rather than one, and a cabinet still reads back the
+ * So it is two documents rather than one, and a dashboard still reads back the
  * shape it sent. The message on a null is written here rather than left to a
  * type error, because "expected string, received null" describes the shape and
  * says nothing about which act the sender was reaching for.
  */
 export declare const SellerNameRequestSchema: z.ZodObject<{
-    seller_name: z.ZodPipe<z.ZodString, z.ZodString>;
+    seller_name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    seller_site: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 /**
  * A change of the wallet that has been asked for, announced, and has not taken
@@ -183,7 +185,7 @@ export declare const SellerNameRequestSchema: z.ZodObject<{
  *
  * It exists because a replacement does not apply at once where the money is
  * real (ADR-0019). The address a merchant is paid at is the one setting whose
- * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * change redirects money, and any key of theirs reaches it — the dashboard's, or
  * one sitting in their own server's environment — so on the live deployment a
  * replacement is told to every account of the merchant first and takes effect
  * forty-eight hours after that. What this document says is the two facts a
@@ -285,10 +287,10 @@ export declare const RegistrationRequestSchema: z.ZodObject<{
     invitation: z.ZodString;
 }, z.core.$strict>;
 /**
- * What registering answers with: a merchant and the key their cabinet will call
+ * What registering answers with: a merchant and the key their dashboard will call
  * as them with.
  *
- * The key is made for a cabinet rather than for the merchant's own code, and
+ * The key is made for a dashboard rather than for the merchant's own code, and
  * that is what the caller of this route is. So it is in no list: a merchant who
  * has just registered has no keys of their own at all, and the first one they
  * do have is one they ask for. No row travels beside the secret for the same
@@ -313,7 +315,7 @@ export type MerchantKeyList = z.infer<typeof MerchantKeyListSchema>;
 export type IssueKeyRequest = z.infer<typeof IssueKeyRequestSchema>;
 export type IssuedKey = z.infer<typeof IssuedKeySchema>;
 export type DisabledKey = z.infer<typeof DisabledKeySchema>;
-export type CabinetKey = z.infer<typeof CabinetKeySchema>;
-export type ForgottenCabinetKey = z.infer<typeof ForgottenCabinetKeySchema>;
+export type DashboardKey = z.infer<typeof DashboardKeySchema>;
+export type ForgottenDashboardKey = z.infer<typeof ForgottenDashboardKeySchema>;
 export type RegistrationRequest = z.infer<typeof RegistrationRequestSchema>;
 export type RegisteredMerchant = z.infer<typeof RegisteredMerchantSchema>;

package/dist/merchant.js

@@ -3,7 +3,7 @@
  * wallet their sales are paid into, and the keys they open the door with.
  *
  * The first two belong together because registering is the act that produces
- * both: one call makes the merchant and the key its cabinet will call as them
+ * both: one call makes the merchant and the key its dashboard will call as them
  * with, and what comes back carries that key once. Split across two files, a
  * reader working out what registering leaves a merchant holding would have to
  * read both to find that it is a key of a kind no list here carries. The name is here for the same reason read the other way round — it is a
@@ -25,7 +25,7 @@
  * nothing, while a flag answers only half.
  */
 import { z } from "zod";
-import { ServiceNameSchema } from "./card.js";
+import { SellerSchema, SellerSiteSchema, ServiceNameSchema } from "./card.js";
 import { EvmAddressSchema } from "./evm-address.js";
 import { IdentifierSchema, TimestampSchema } from "./primitives.js";
 /**
@@ -162,8 +162,8 @@ export const MerchantKeySchema = z
  * broken.
  *
  * It is not always one of the keys beside it, and that is the thing a reader is
- * likeliest to assume and be wrong about. A cabinet calls with a key made for a
- * cabinet, and those are in nobody's list, so a client that looked this
+ * likeliest to assume and be wrong about. A dashboard calls with a key made for a
+ * dashboard, and those are in nobody's list, so a client that looked this
  * identifier up among the rows would find nothing — which is an answer rather
  * than an error, and a screen has to be built for it.
  *
@@ -176,7 +176,7 @@ export const MerchantKeyListSchema = z
      * The keys this merchant made for their own code, the revoked ones among
      * them.
      *
-     * The keys a cabinet holds are not here and never will be: the merchant did
+     * The keys a dashboard holds are not here and never will be: the merchant did
      * not issue one and has nothing to do with one. A list is what somebody
      * acts on, and a row nobody has any business acting on is a row that only
      * raises the question of why it will not go away.
@@ -186,7 +186,7 @@ export const MerchantKeyListSchema = z
     this_call: IdentifierSchema,
 })
     .meta({
-    description: "The keys one merchant made for their own code, working and revoked together, and the identifier of the key this very call was made with. That last field is here because a merchant cannot disable the key they are holding: without it a screen would offer a button the gateway refuses. It is not always among the keys listed — a cabinet calls with a key of its own, and those are in no list here — so a client matching it against the rows has to be built for finding none. The keys a cabinet holds are left out entirely: they are not issued by the merchant and cannot be revoked by them. This document does not say whether it is the whole list either — paging is not designed, and the absence of a field about it is not a promise that there is no more.",
+    description: "The keys one merchant made for their own code, working and revoked together, and the identifier of the key this very call was made with. That last field is here because a merchant cannot disable the key they are holding: without it a screen would offer a button the gateway refuses. It is not always among the keys listed — a dashboard calls with a key of its own, and those are in no list here — so a client matching it against the rows has to be built for finding none. The keys a dashboard holds are left out entirely: they are not issued by the merchant and cannot be revoked by them. This document does not say whether it is the whole list either — paging is not designed, and the absence of a field about it is not a promise that there is no more.",
 });
 /** What a merchant sends to have a key made. */
 export const IssueKeyRequestSchema = z
@@ -211,7 +211,7 @@ export const IssuedKeySchema = z
     secret: KeySecretSchema,
 })
     .meta({
-    description: "A key as it comes back from being issued: the row a merchant will see in their list from now on, and the key itself. It carries the key once. Three answers in this contract carry one — this, what registering gives back, and the key a cabinet asks for — and nothing else does, because what is written down on our side is a digest. A key that is lost is replaced by a new one rather than read back.",
+    description: "A key as it comes back from being issued: the row a merchant will see in their list from now on, and the key itself. It carries the key once. Three answers in this contract carry one — this, what registering gives back, and the key a dashboard asks for — and nothing else does, because what is written down on our side is a digest. A key that is lost is replaced by a new one rather than read back.",
 });
 /**
  * A key that has been revoked, as it now stands.
@@ -228,10 +228,10 @@ export const DisabledKeySchema = z
     description: "The key that was just revoked, with the instant it stopped working on it, so a merchant reads back what happened rather than taking the call's word for it. Revoking a key that was already revoked answers this same way and keeps the first instant, because that is the true one and a retry after a dropped connection must not rewrite it.",
 });
 /**
- * A key made for a cabinet, which is the secret and nothing else.
+ * A key made for a dashboard, which is the secret and nothing else.
  *
  * Every other answer that makes a key carries the row beside it, and this one
- * cannot. A key made for a cabinet is in no merchant's list — they did not
+ * cannot. A key made for a dashboard is in no merchant's list — they did not
  * issue it and have no reason to know it exists — so an identifier here would
  * name a row that no screen of theirs draws and no call of theirs reaches: not
  * the list it is absent from, and not the revoking, which takes the keys a
@@ -239,13 +239,13 @@ export const DisabledKeySchema = z
  * is put it on the row of whoever just signed in, and that is the whole of what
  * it needs.
  */
-export const CabinetKeySchema = z
+export const DashboardKeySchema = z
     .strictObject({
     /** The only moment this is readable. Nothing on our side keeps it. */
     secret: KeySecretSchema,
 })
     .meta({
-    description: "A key made for a cabinet to call as one merchant, carried once and readable nowhere afterwards. There is no row beside it and there is nothing to put one: a key made this way is in no merchant's list of keys, and the call that revokes a key refuses this kind by name — so an identifier for it would name something no answer shows and no call acts on. Whoever asked for this holds it until they ask for another.",
+    description: "A key made for a dashboard to call as one merchant, carried once and readable nowhere afterwards. There is no row beside it and there is nothing to put one: a key made this way is in no merchant's list of keys, and the call that revokes a key refuses this kind by name — so an identifier for it would name something no answer shows and no call acts on. Whoever asked for this holds it until they ask for another.",
 });
 /**
  * That the key a call was made with is gone.
@@ -257,7 +257,7 @@ export const CabinetKeySchema = z
  * is done, and it is said in a field rather than left to a status code so that
  * a client reads one document and not two kinds of evidence.
  */
-export const ForgottenCabinetKeySchema = z
+export const ForgottenDashboardKeySchema = z
     .strictObject({
     /** The key this call was made with no longer exists. */
     forgotten: z.literal(true),
@@ -284,11 +284,20 @@ export const ForgottenCabinetKeySchema = z
  */
 export const SellerNameSchema = z
     .strictObject({
-    /** What buyers read beside this merchant's products, or nothing. */
-    seller_name: ServiceNameSchema.nullable(),
+    /**
+     * What buyers read beside this merchant's products, or nothing — read back
+     * by the rule an agent's `seller` reads it by, which leaves the plain-text
+     * rule to the door that writes it.
+     */
+    seller_name: SellerSchema.shape.name,
+    /**
+     * The https address of the merchant's own shop, where an agent takes what
+     * an order cannot answer (ADR-0034), or nothing where none was given.
+     */
+    seller_site: SellerSiteSchema.nullable(),
 })
     .meta({
-    description: "The name a merchant's products are sold under: what a discovery catalog lists them under and what a buyer's agent is shown beside the price. Null means nobody has chosen one, which is where every merchant starts. The field is always present rather than left out when there is no name: an absent field would be indistinguishable from a client that dropped it. What a name may be is the catalog's rule rather than ours — at most 32 characters of printable ASCII — because a name outside it is dropped there in silence, so it is refused here where somebody is told. A merchant with no name cannot publish a card: a card published without one reaches a buyer's agent inside a payment request that names no seller at all.",
+    description: "The name a merchant's products are sold under: what a discovery catalog lists them under and what a buyer's agent is shown beside the price. Null means nobody has chosen one, which is where every merchant starts. The field is always present rather than left out when there is no name: an absent field would be indistinguishable from a client that dropped it. What a name may be is the catalog's rule rather than ours — at most 32 characters of printable ASCII — because a name outside it is dropped there in silence, so it is refused here where somebody is told. A merchant with no name cannot publish a card: a card published without one reaches a buyer's agent inside a payment request that names no seller at all. seller_site is the https address of the merchant's own shop, which every agent reads beside the name on their cards and orders as where to take what an order cannot answer; null means none was given.",
 });
 /**
  * What a merchant sends to change what their products are sold under.
@@ -303,7 +312,7 @@ export const SellerNameSchema = z
  * which is this same call, or an end to selling, which is the pause — and the
  * pause leaves their cards where they can find them again.
  *
- * So it is two documents rather than one, and a cabinet still reads back the
+ * So it is two documents rather than one, and a dashboard still reads back the
  * shape it sent. The message on a null is written here rather than left to a
  * type error, because "expected string, received null" describes the shape and
  * says nothing about which act the sender was reaching for.
@@ -311,7 +320,8 @@ export const SellerNameSchema = z
 export const SellerNameRequestSchema = z
     .strictObject({
     /**
-     * What buyers are to read beside this merchant's products.
+     * What buyers are to read beside this merchant's products, where it is
+     * changing.
      *
      * The rule lives once, in `ServiceNameSchema`, and this reaches it through
      * a string that carries its own words for "this is not a name at all". A
@@ -320,18 +330,36 @@ export const SellerNameRequestSchema = z
      */
     seller_name: z
         .string({
-        // A field that is missing is a client with a bug and a field holding
-        // null is a client with a misunderstanding. Only the second gets this
-        // sentence; the first falls through to the ordinary words about a
-        // field that is not there, which is what its author needs to read.
+        // A field holding null is a client with a misunderstanding, and only
+        // that gets this sentence.
         error: (issue) => issue.input === undefined
             ? undefined
             : "a seller name cannot be taken away, only changed: a merchant who wants to stop being listed pauses their selling, which leaves their cards where they can put them back on sale",
     })
-        .pipe(ServiceNameSchema),
+        .pipe(ServiceNameSchema)
+        .optional(),
+    /**
+     * The https address of the merchant's own shop, where it is changing
+     * (ADR-0034). Like the name it is changed and never taken away: an agent
+     * holding an order that named a site has been told where to go, and a
+     * site that vanished from the same order would leave it nowhere.
+     */
+    seller_site: z
+        .string({
+        error: (issue) => issue.input === undefined
+            ? undefined
+            : "a seller's site cannot be taken away, only changed: send the address it has moved to",
+    })
+        .pipe(SellerSiteSchema)
+        .optional(),
+})
+    .refine((asked) => asked.seller_name !== undefined || asked.seller_site !== undefined, {
+    // A client that dropped both fields has a bug, and is told what this call
+    // takes rather than anything about taking a name away.
+    message: "a request names seller_name, seller_site or both: one that names neither changes nothing",
 })
     .meta({
-    description: "What a merchant sends to change the name their products are sold under. The same rule as the answer — at most 32 characters of printable ASCII, the catalog's rule rather than ours — and one difference: null is refused. A merchant goes from no name to a name and from one name to another, never back to none, because a payment request names the seller and there would be nobody to name: every card they have published would come off sale, which is an end to their selling arriving under the name of editing a setting. Somebody reaching for null wants one of two other things: a different name, which is this call with a different value, or an end to selling, which is the pause.",
+    description: "What a merchant sends to change the name their products are sold under, the address of their shop's own site, or both; a field left out stays as it was, and one of the two has to be there. The name is held to the catalog's rule rather than ours — at most 32 characters of printable ASCII — and is plain text. The site is an https origin and nothing after it, such as https://shop.example. Null is refused for either. A merchant goes from no name to a name and from one name to another, never back to none, because a payment request names the seller and there would be nobody to name: every card they have published would come off sale, which is an end to their selling arriving under the name of editing a setting. Somebody reaching for null wants one of two other things: a different name, which is this call with a different value, or an end to selling, which is the pause. A site is changed the same way and never taken away.",
 });
 /**
  * A change of the wallet that has been asked for, announced, and has not taken
@@ -339,7 +367,7 @@ export const SellerNameRequestSchema = z
  *
  * It exists because a replacement does not apply at once where the money is
  * real (ADR-0019). The address a merchant is paid at is the one setting whose
- * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * change redirects money, and any key of theirs reaches it — the dashboard's, or
  * one sitting in their own server's environment — so on the live deployment a
  * replacement is told to every account of the merchant first and takes effect
  * forty-eight hours after that. What this document says is the two facts a
@@ -475,10 +503,10 @@ export const RegistrationRequestSchema = z
     description: "What somebody sends to become a merchant: the invitation code they were given, and nothing else. The name their products are sold under is deliberately not here — it is a public answer, and asked for on the way in it is answered by somebody with no products and no idea what the name is for; it is set afterwards, and changed afterwards, through the merchant's own call for it. Nothing about an account is here either: an address and a password belong to whatever signs the person in, and are never sent to the gateway. A document carrying either is refused rather than trimmed, because a field accepted and dropped is somebody believing they said something.",
 });
 /**
- * What registering answers with: a merchant and the key their cabinet will call
+ * What registering answers with: a merchant and the key their dashboard will call
  * as them with.
  *
- * The key is made for a cabinet rather than for the merchant's own code, and
+ * The key is made for a dashboard rather than for the merchant's own code, and
  * that is what the caller of this route is. So it is in no list: a merchant who
  * has just registered has no keys of their own at all, and the first one they
  * do have is one they ask for. No row travels beside the secret for the same
@@ -497,5 +525,5 @@ export const RegisteredMerchantSchema = z
     secret: KeySecretSchema,
 })
     .meta({
-    description: "What registering produced: the merchant, and the key whoever registered them will call as them with. The key is readable here and nowhere afterwards, so whoever made this call is the only party that can keep it. It is a key made for a cabinet rather than one of the merchant's own: it appears in no list of their keys and the call that revokes a key refuses its kind by name, so no row for it comes back here either. A merchant who has just registered has no keys of their own until they ask for one. The merchant is listed under no name yet and this answer carries none — the name their products are sold under is chosen afterwards, and until it is, publishing a card is refused. What this answer does not carry either is any notion of an account or a session: registering makes a merchant and a key, and whatever signs a person in is on the other side of this call.",
+    description: "What registering produced: the merchant, and the key whoever registered them will call as them with. The key is readable here and nowhere afterwards, so whoever made this call is the only party that can keep it. It is a key made for a dashboard rather than one of the merchant's own: it appears in no list of their keys and the call that revokes a key refuses its kind by name, so no row for it comes back here either. A merchant who has just registered has no keys of their own until they ask for one. The merchant is listed under no name yet and this answer carries none — the name their products are sold under is chosen afterwards, and until it is, publishing a card is refused. What this answer does not carry either is any notion of an account or a session: registering makes a merchant and a key, and whatever signs a person in is on the other side of this call.",
 });

package/dist/primitives.d.ts

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

package/dist/primitives.js

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

package/dist/results.d.ts

@@ -102,9 +102,10 @@ export declare const OrderCallResultSchema: z.ZodEnum<{
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
@@ -203,7 +204,7 @@ export declare const CARD_REJECTED = "card_rejected";
  * merchant has no name set for buyers to read, no wallet set for their sales to
  * be paid into, or no approval from the operator for the live catalog. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment

package/dist/results.js

@@ -103,9 +103,10 @@ export const OrderCallResultSchema = z.enum(ORDER_CALL_RESULTS);
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
@@ -211,7 +212,7 @@ export const CallErrorSchema = z.strictObject({
     code: z.string().regex(/\S/, "an error carries a code").meta({
         // Same reason as the refusal code: the dictionary travels with the field
         // or it does not reach the reader the export exists for.
-        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call does not exist for this card\'s mode — refusing separately does not, in the synchronous one, where the handler\'s own answer is the refusal). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
+        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call or the answer does not exist for this card\'s mode — in the synchronous one the handler\'s own answer is the delivery or the refusal, so delivering or refusing separately does not exist there, and neither does taking an order on while it waits for its goods, which promises them later through a call that mode does not have). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
     }),
     message: z.string().regex(/\S/, "an error carries an explanation a person can read"),
     retryable: z.boolean(),
@@ -247,7 +248,7 @@ export const CARD_REJECTED = "card_rejected";
  * merchant has no name set for buyers to read, no wallet set for their sales to
  * be paid into, or no approval from the operator for the live catalog. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment

package/package.json

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