@nuanu-ai/agentify-contracts 0.4.0 → 0.5.0

package/dist/api.d.ts

@@ -783,7 +783,7 @@ export type ErrorEnvelope = z.infer<typeof ErrorEnvelopeSchema>;
  * has to act on it belongs to the route that sends it and to the sentence the
  * refusal carries.
  */
-export declare const ERROR_CODES: readonly ["body_too_large", "body_undecodable", "call_refused", "charset_unsupported", "encoding_unsupported", "gateway_failed", "key_made_for_a_cabinet", "key_opened_this_call", "malformed_body", "malformed_query", "merchant_departed", "no_such_item", "no_such_key", "no_such_order", "no_such_route", "not_a_cabinet_key", "not_authorised", "not_invited", "not_selling", "not_this_purchase", "order_closed_before_it_was_priced", "order_not_priced_yet", "params_do_not_fit", "payment_already_spent", "payment_not_taken", "payment_not_verified"];
+export declare const ERROR_CODES: readonly ["body_too_large", "body_undecodable", "call_refused", "charset_unsupported", "encoding_unsupported", "gateway_failed", "key_made_for_a_cabinet", "key_opened_this_call", "malformed_body", "malformed_query", "merchant_departed", "no_such_item", "no_such_key", "no_such_order", "no_such_route", "not_a_cabinet_key", "not_authorised", "not_invited", "not_selling", "not_this_purchase", "order_closed_before_it_was_priced", "order_not_priced_yet", "params_do_not_fit", "payment_already_spent", "payment_not_taken", "payment_not_verified", "wallet_change_not_announced", "wallet_change_nobody_to_tell", "wallet_change_raced", "wallet_change_unconfirmed"];
 /** One of the codes this gateway is known to refuse a call with. */
 export type ErrorCode = (typeof ERROR_CODES)[number];
 /**
@@ -1280,6 +1280,10 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 payout_wallet: z.ZodNullable<z.ZodString>;
+                pending: z.ZodNullable<z.ZodObject<{
+                    payout_wallet: z.ZodString;
+                    takes_effect_at: z.ZodISODateTime;
+                }, z.core.$strict>>;
             }, z.core.$strict>;
         };
     };
@@ -1294,6 +1298,10 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 payout_wallet: z.ZodNullable<z.ZodString>;
+                pending: z.ZodNullable<z.ZodObject<{
+                    payout_wallet: z.ZodString;
+                    takes_effect_at: z.ZodISODateTime;
+                }, z.core.$strict>>;
             }, z.core.$strict>;
         };
     };

package/dist/api.js

@@ -105,7 +105,7 @@ export const MerchantCardListSchema = z
     cards: z.array(MerchantCardSchema),
 })
     .meta({
-    description: "A merchant's own catalog: every card they have published, and whether they are taking new orders at all. The merchant's own selling word is here as well as on each card because the two are different facts, and neither can be worked out from the other. A card reads open only where all of it holds at once: the merchant is selling, the card is not paused in its own right, the merchant has a name for it to be sold under, and — on a deployment that settles on a real chain — a wallet for the money to be paid into. So a card can read paused while this field reads open, and this field does not say which of the reasons it was. What does say is the refusal at the publish and the merchant's own settings, each of which names the piece that is missing. 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.",
+    description: "A merchant's own catalog: every card they have published, and whether they are taking new orders at all. The merchant's own selling word is here as well as on each card because the two are different facts, and neither can be worked out from the other. A card reads open only where all of it holds at once: the merchant is selling, the card is not paused in its own right, the merchant has a name for it to be sold under, on a deployment that settles on a real chain a wallet for the money to be paid into, and on the live deployment the operator's approval. So a card can read paused while this field reads open, and this field does not say which of the reasons it was. What does say is the refusal at the publish, whose findings about the merchant carry the codes no_seller_name, no_payout_wallet and no_operator_approval, and the merchant's own settings. 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.",
 });
 /**
  * Every receipt this merchant has.
@@ -680,6 +680,10 @@ export const ERROR_CODES = Object.freeze([
     "payment_already_spent",
     "payment_not_taken",
     "payment_not_verified",
+    "wallet_change_not_announced",
+    "wallet_change_nobody_to_tell",
+    "wallet_change_raced",
+    "wallet_change_unconfirmed",
 ]);
 /**
  * Every call of the surface, under the name it is known by in both programs.
@@ -714,7 +718,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, with POST /v0/payout-wallet as the way past it: 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 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.",
         request: CardSchema,
         response: { document: PublishResultSchema },
     },
@@ -757,7 +761,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. 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 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.",
         request: RegistrationRequestSchema,
         response: { document: RegisteredMerchantSchema },
     },
@@ -780,14 +784,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. 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. 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.",
+        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.",
         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. The answer is the address as it now stands, read back from what was written rather than echoed, in the mixed-case spelling a wallet shows. Setting the same address twice changes nothing and answers the same way, so a retry after a dropped connection is safe. 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 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.",
         request: PayoutWalletRequestSchema,
         response: { document: PayoutWalletSchema },
     },
@@ -817,14 +821,14 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/keys/cabinet",
         auth: "merchant_key",
-        description: "Makes a key for a cabinet to call as this merchant with, and hands it back once. 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.",
+        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 },
     },
     forget_cabinet_key: {
         method: "DELETE",
         path: "/v0/keys/cabinet",
         auth: "merchant_key",
-        description: "Removes the key this call was made with, and no other. 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.",
+        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 },
     },
     get_order: {

package/dist/index.d.ts

@@ -33,8 +33,8 @@ export type { EvmAddress } from "./evm-address.js";
 export { checksummedAddressOf, EvmAddressSchema } from "./evm-address.js";
 export type { Acceptance, Delivery, HandlerAnswer, Refusal, RefusalCode } from "./handler.js";
 export { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RECOMMENDED_REFUSAL_CODES, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-export type { CabinetKey, DisabledKey, ForgottenCabinetKey, IssuedKey, IssueKeyRequest, MerchantKey, MerchantKeyList, PayoutWallet, PayoutWalletRequest, RegisteredMerchant, RegistrationRequest, SellerName, SellerNameRequest, } from "./merchant.js";
-export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+export type { CabinetKey, DisabledKey, ForgottenCabinetKey, IssuedKey, IssueKeyRequest, MerchantKey, MerchantKeyList, PayoutWallet, PayoutWalletRequest, PendingPayoutWallet, RegisteredMerchant, RegistrationRequest, SellerName, SellerNameRequest, } from "./merchant.js";
+export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 export type { Order } from "./order.js";
 export { OrderSchema } from "./order.js";
 export type { OrderStatus } from "./order-status.js";
@@ -47,8 +47,8 @@ export type { QuotePurpose, QuoteRequest, QuoteResponse } from "./quote.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export type { Receipt, ReceiptOutcome } from "./receipt.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
-export type { CallError, OrderCallResult, Problem, PublishResult } from "./results.js";
-export { CARD_REJECTED, CallErrorSchema, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
+export type { CallError, MerchantFinding, OrderCallResult, Problem, PublishResult, } from "./results.js";
+export { CARD_REJECTED, CallErrorSchema, MERCHANT_FINDINGS, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
 export type { SellingState } from "./selling.js";
 export { SELLING_STATES, SellingStateSchema } from "./selling.js";
 /**
@@ -616,10 +616,18 @@ export declare const schemas: Readonly<{
     }>;
     payout_wallet: z.ZodObject<{
         payout_wallet: z.ZodNullable<z.ZodString>;
+        pending: z.ZodNullable<z.ZodObject<{
+            payout_wallet: z.ZodString;
+            takes_effect_at: z.ZodISODateTime;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     payout_wallet_request: z.ZodObject<{
         payout_wallet: z.ZodPipe<z.ZodString, z.ZodString>;
     }, z.core.$strict>;
+    pending_payout_wallet: z.ZodObject<{
+        payout_wallet: z.ZodString;
+        takes_effect_at: z.ZodISODateTime;
+    }, z.core.$strict>;
     price_check: z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strict>]>;

package/dist/index.js

@@ -27,7 +27,7 @@ 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, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+import { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, 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";
@@ -42,14 +42,14 @@ export { WORKER_ENVELOPE_KINDS, WORKER_ENVELOPE_PAYLOADS, WorkerEnvelopeSchema,
 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, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, 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 { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
-export { CARD_REJECTED, CallErrorSchema, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
+export { CARD_REJECTED, CallErrorSchema, MERCHANT_FINDINGS, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
 export { SELLING_STATES, SellingStateSchema } from "./selling.js";
 /**
  * The version of the public contract. It grows when the meaning of the fields
@@ -109,6 +109,7 @@ export const schemas = Object.freeze({
     param_type: ParamTypeSchema,
     payout_wallet: PayoutWalletSchema,
     payout_wallet_request: PayoutWalletRequestSchema,
+    pending_payout_wallet: PendingPayoutWalletSchema,
     price_check: PriceCheckSchema,
     problem: ProblemSchema,
     public_card: PublicCardSchema,

package/dist/merchant.d.ts

@@ -177,6 +177,25 @@ export declare const SellerNameSchema: z.ZodObject<{
 export declare const SellerNameRequestSchema: z.ZodObject<{
     seller_name: z.ZodPipe<z.ZodString, z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A change of the wallet that has been asked for, announced, and has not taken
+ * effect yet.
+ *
+ * It exists because a replacement does not apply at once where the money is
+ * real (ADR-0019). The address a merchant is paid at is the one setting whose
+ * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * one sitting in their own server's environment — so on the live deployment a
+ * replacement is told to every account of the merchant first and takes effect
+ * forty-eight hours after that. What this document says is the two facts a
+ * merchant needs in that window: what replaces the address, and from when.
+ *
+ * Both are required. An address with no moment says nothing about when the
+ * money moves, and a moment with no address says it moves without saying where.
+ */
+export declare const PendingPayoutWalletSchema: z.ZodObject<{
+    payout_wallet: z.ZodString;
+    takes_effect_at: z.ZodISODateTime;
+}, z.core.$strict>;
 /**
  * The wallet a merchant's sales are paid into, as the merchant reads it back.
  *
@@ -200,9 +219,27 @@ export declare const SellerNameRequestSchema: z.ZodObject<{
  * address in lower case they cannot tell it from a different address without
  * comparing character by character. On the one field money is sent to, that
  * glance is the whole of the checking anybody does.
+ *
+ * `pending` is the change waiting beside it, and it is always present for the
+ * same reason `payout_wallet` is: null says nothing is waiting, and an absent
+ * field would be a silence. It is the field that keeps a caller from taking its
+ * own write for a failure — a merchant who asked for a new address on the live
+ * deployment reads the old one back, correctly, for forty-eight hours, and
+ * without this they would ask again, or conclude the change was lost.
+ *
+ * It is carried without moving `CONTRACT_VERSION`, which is the one known
+ * exception to the rule that a new required field moves it (ADR-0006 §2): no
+ * worker of the SDK reads this route, so the version would stop every
+ * installed worker for a field none of them sees. What that costs is that a
+ * merchant's own code holding this schema from an older release of this
+ * package refuses the answer until the package is upgraded.
  */
 export declare const PayoutWalletSchema: z.ZodObject<{
     payout_wallet: z.ZodNullable<z.ZodString>;
+    pending: z.ZodNullable<z.ZodObject<{
+        payout_wallet: z.ZodString;
+        takes_effect_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * What a merchant sends to change where their sales are paid.
@@ -270,6 +307,7 @@ export type SellerName = z.infer<typeof SellerNameSchema>;
 export type SellerNameRequest = z.infer<typeof SellerNameRequestSchema>;
 export type PayoutWallet = z.infer<typeof PayoutWalletSchema>;
 export type PayoutWalletRequest = z.infer<typeof PayoutWalletRequestSchema>;
+export type PendingPayoutWallet = z.infer<typeof PendingPayoutWalletSchema>;
 export type MerchantKey = z.infer<typeof MerchantKeySchema>;
 export type MerchantKeyList = z.infer<typeof MerchantKeyListSchema>;
 export type IssueKeyRequest = z.infer<typeof IssueKeyRequestSchema>;

package/dist/merchant.js

@@ -51,6 +51,33 @@ import { IdentifierSchema, TimestampSchema } from "./primitives.js";
 const KeyLabelSchema = z
     .string()
     .regex(/^\S(?:[\s\S]*\S)?$/u, "a label must not be empty or padded with spaces");
+/**
+ * The longest label a key is issued with.
+ *
+ * A label used to have no bound, on the argument that no channel outside us
+ * carries it. One does now: on the live deployment the message that tells a
+ * merchant of a new key, or of a wallet change made with one, names the key
+ * by its label (ADR-0019), and that message is Agentify's words in somebody's
+ * inbox. A hundred characters is a line on a list and in a message, and
+ * longer than any name a person gives a worker.
+ */
+const LONGEST_KEY_LABEL = 100;
+/**
+ * A label as a new key is issued with it: the rule above, on one line, and no
+ * longer than {@link LONGEST_KEY_LABEL}.
+ *
+ * Only the request carries the bound. The keys a merchant already holds are
+ * read back under whatever they were named, including a key issued at the
+ * server's terminal, because refusing the list over one old row would hide
+ * every key on it; the message that names such a key cuts it to one line of
+ * the same length itself.
+ */
+const IssuedKeyLabelSchema = KeyLabelSchema.max(LONGEST_KEY_LABEL, `a label is at most ${LONGEST_KEY_LABEL} characters, the one line a key is known by`).regex(
+// Written as code-point ranges rather than a Unicode property, because this
+// pattern is published in the JSON Schema a validator in another language
+// reads, and not every one of those knows the property escapes.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+/^[^\u0000-\u001F\u007F-\u009F\u2028\u2029]*$/u, "a label is one line: it cannot carry a line break, a tab or another control character");
 /**
  * The key itself, in the only form its owner will ever see it.
  *
@@ -164,10 +191,10 @@ export const MerchantKeyListSchema = z
 /** What a merchant sends to have a key made. */
 export const IssueKeyRequestSchema = z
     .strictObject({
-    label: KeyLabelSchema,
+    label: IssuedKeyLabelSchema,
 })
     .meta({
-    description: "What a merchant asks for when they want another key: the name they will know it by, and nothing else. There is nowhere here to put a secret, because a key is generated rather than chosen — one somebody picks is one somebody reuses somewhere else.",
+    description: "What a merchant asks for when they want another key: the name they will know it by, and nothing else. The name is one line of at most 100 characters, not empty and not padded with spaces; on the live deployment it is also how the message telling the merchant of the new key names it. There is nowhere here to put a secret, because a key is generated rather than chosen — one somebody picks is one somebody reuses somewhere else.",
 });
 /**
  * A key that has just been made: the row, and the secret, once.
@@ -306,6 +333,31 @@ export const SellerNameRequestSchema = z
     .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.",
 });
+/**
+ * A change of the wallet that has been asked for, announced, and has not taken
+ * effect yet.
+ *
+ * It exists because a replacement does not apply at once where the money is
+ * real (ADR-0019). The address a merchant is paid at is the one setting whose
+ * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * one sitting in their own server's environment — so on the live deployment a
+ * replacement is told to every account of the merchant first and takes effect
+ * forty-eight hours after that. What this document says is the two facts a
+ * merchant needs in that window: what replaces the address, and from when.
+ *
+ * Both are required. An address with no moment says nothing about when the
+ * money moves, and a moment with no address says it moves without saying where.
+ */
+export const PendingPayoutWalletSchema = z
+    .strictObject({
+    /** The address the merchant will be paid at once the wait is over. */
+    payout_wallet: EvmAddressSchema,
+    /** The moment it replaces the address paid now. */
+    takes_effect_at: TimestampSchema,
+})
+    .meta({
+    description: "A replacement wallet that has been asked for and announced and has not taken effect yet. payout_wallet is the address sales will be paid into from takes_effect_at on, in the mixed-case spelling a wallet shows; until that moment every payment request still names the address paid now. The change takes effect then only if it is still the one waiting: asking for the address paid now cancels it, and asking for a different address replaces it and starts the wait again.",
+});
 /**
  * The wallet a merchant's sales are paid into, as the merchant reads it back.
  *
@@ -329,14 +381,30 @@ export const SellerNameRequestSchema = z
  * address in lower case they cannot tell it from a different address without
  * comparing character by character. On the one field money is sent to, that
  * glance is the whole of the checking anybody does.
+ *
+ * `pending` is the change waiting beside it, and it is always present for the
+ * same reason `payout_wallet` is: null says nothing is waiting, and an absent
+ * field would be a silence. It is the field that keeps a caller from taking its
+ * own write for a failure — a merchant who asked for a new address on the live
+ * deployment reads the old one back, correctly, for forty-eight hours, and
+ * without this they would ask again, or conclude the change was lost.
+ *
+ * It is carried without moving `CONTRACT_VERSION`, which is the one known
+ * exception to the rule that a new required field moves it (ADR-0006 §2): no
+ * worker of the SDK reads this route, so the version would stop every
+ * installed worker for a field none of them sees. What that costs is that a
+ * merchant's own code holding this schema from an older release of this
+ * package refuses the answer until the package is upgraded.
  */
 export const PayoutWalletSchema = z
     .strictObject({
-    /** Where this merchant's sales are paid, or nothing at all. */
+    /** Where this merchant's sales are paid now, or nothing at all. */
     payout_wallet: EvmAddressSchema.nullable(),
+    /** A replacement that has been announced and is waiting, or nothing. */
+    pending: PendingPayoutWalletSchema.nullable(),
 })
     .meta({
-    description: "The address a merchant's sales are paid into. Payments are not held by anybody on the way: a buyer's agent pays this address directly, and it is the payTo of every payment request made for this merchant's products. Null means nobody has set one, which is where every merchant starts; the field is always present rather than left out, because an absent field is indistinguishable from a client that dropped it. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent — so what a merchant reads back on a screen is character for character what they copied out of their wallet. On a deployment that settles on a real chain a merchant with no wallet here cannot publish a card, because the money from that card's sales would have nowhere to go.",
+    description: "The address a merchant's sales are paid into, and any change of it that is waiting. Payments are not held by anybody on the way: a buyer's agent pays payout_wallet directly, and it is the payTo of every payment request made for this merchant's products now. Null means nobody has set one, which is where every merchant starts; the field is always present rather than left out, because an absent field is indistinguishable from a client that dropped it. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent — so what a merchant reads back on a screen is character for character what they copied out of their wallet. On a deployment that settles on a real chain a merchant with no wallet here cannot publish a card, because the money from that card's sales would have nowhere to go. pending is a replacement that has been asked for and has not taken effect: on the live deployment a merchant who already has a wallet and asks for a different one is told of it by message, and the new address takes effect forty-eight hours later, so until takes_effect_at this answer names the address still paid and the waiting one beside it. A caller reading its old address back beside a pending change has not failed to write; the change is waiting. Null means nothing is waiting, which is every answer on the test channel and in a sandbox, where a change applies at once.",
 });
 /**
  * What a merchant sends to change where their sales are paid.

package/dist/results.d.ts

@@ -194,6 +194,30 @@ export declare const CallErrorSchema: z.ZodObject<{
  * writes the branch that reads it.
  */
 export declare const CARD_REJECTED = "card_rejected";
+/**
+ * The findings of a refused publish that are about the merchant rather than
+ * the card.
+ *
+ * Each arrives in the refusal's `problems` with an empty path, beside whatever
+ * is wrong with the card, and none of them is cleared by editing the card: the
+ * merchant has no name set for buyers to read, no wallet set for their sales to
+ * be paid into, or no approval from the operator for the live catalog. The
+ * 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
+ * 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
+ * alone, as the publish route's description says; a program needs no copy of
+ * that rule, because it learns what is missing where it is refused, at the
+ * publish.
+ */
+export declare const MERCHANT_FINDINGS: Readonly<{
+    readonly NO_SELLER_NAME: "no_seller_name";
+    readonly NO_PAYOUT_WALLET: "no_payout_wallet";
+    readonly NO_OPERATOR_APPROVAL: "no_operator_approval";
+}>;
+/** One of the findings about the merchant, as its code travels on the wire. */
+export type MerchantFinding = (typeof MERCHANT_FINDINGS)[keyof typeof MERCHANT_FINDINGS];
 /**
  * The answer to publishing a card: the catalog id, or what stands in its way.
  *

package/dist/results.js

@@ -167,8 +167,16 @@ export const ProblemSchema = z
      * indistinguishable from a path nobody filled in.
      */
     path: z.array(z.string()),
-    /** What kind of finding it is, for the code that reads it. */
-    code: z.string().regex(/\S/, "a finding carries a code"),
+    /**
+     * What kind of finding it is, for the code that reads it.
+     *
+     * Open, because a finding about a field carries whatever the check that
+     * found it calls it. The three about the merchant are promised, and they
+     * are described for the export for the reason the error's codes are.
+     */
+    code: z.string().regex(/\S/, "a finding carries a code").meta({
+        description: 'What kind of finding it is, for the program that reads it. The set is open: a finding about a field of what was sent carries the name the check gave it. Three are promised, always with an empty path, and each says the merchant rather than the card is missing something, so no edit to the card clears it: "no_seller_name" (no name set for buyers to read), "no_payout_wallet" (no wallet set for the sales to be paid into, asked for wherever a payment settles) and "no_operator_approval" (the operator has not admitted this merchant to the live catalog, which only the operator can change).',
+    }),
     /** The same finding in words, for the person who has to fix the card. */
     message: z.string().regex(/\S/, "a finding carries an explanation a person can read"),
 })
@@ -219,7 +227,7 @@ export const CallErrorSchema = z.strictObject({
      * is the field the whole shape is named after.
      */
     problems: z.array(ProblemSchema).min(1).optional().meta({
-        description: 'What was wrong with what was sent, one finding at a time: where it is, a code for the program that reads it, and the same finding in words. Present where the call is refusing what it was handed — a card that was not published, a delivery that is not what its card declares — and absent where the refusal is about a state of the world instead: a refund already settled is about the order, not about a field of the request. Never empty where it is present, and a refused publish always carries it. This field is the complete account of what stands in the way, and it is the one to read the findings from. The error\'s "message" is a single line written to be read in a log and does not carry the list: it says how many findings there are, quotes one or a few of them, and marks the place where a long one was cut — so a reader can always tell a short refusal from a shortened account of a long one.',
+        description: "What was wrong with what was sent, one finding at a time: where it is, a code for the program that reads it, and the same finding in words. Present where the call is refusing what it was handed — a card that was not published, a delivery that is not what its card declares — and absent where the refusal is about a state of the world instead: a refund already settled is about the order, not about a field of the request. Never empty where it is present, and a refused publish always carries it. This field is the complete account of what stands in the way, and it is the one to read the findings from. The error's \"message\" is a single line written to be read in a log and does not carry the list. Where what stands in the way is the merchant's own — no seller name, no payout wallet, no operator approval — the message names each of those plainly; for the rest it says how many findings there are, quotes one of them, and marks the place where a long one was cut — so a reader can always tell a short refusal from a shortened account of a long one.",
     }),
 });
 /**
@@ -230,6 +238,28 @@ export const CallErrorSchema = z.strictObject({
  * writes the branch that reads it.
  */
 export const CARD_REJECTED = "card_rejected";
+/**
+ * The findings of a refused publish that are about the merchant rather than
+ * the card.
+ *
+ * Each arrives in the refusal's `problems` with an empty path, beside whatever
+ * is wrong with the card, and none of them is cleared by editing the card: the
+ * merchant has no name set for buyers to read, no wallet set for their sales to
+ * be paid into, or no approval from the operator for the live catalog. The
+ * 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
+ * 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
+ * alone, as the publish route's description says; a program needs no copy of
+ * that rule, because it learns what is missing where it is refused, at the
+ * publish.
+ */
+export const MERCHANT_FINDINGS = Object.freeze({
+    NO_SELLER_NAME: "no_seller_name",
+    NO_PAYOUT_WALLET: "no_payout_wallet",
+    NO_OPERATOR_APPROVAL: "no_operator_approval",
+});
 /**
  * The error a refused publish carries: the shared shape, with the findings made
  * required.
@@ -237,11 +267,10 @@ export const CARD_REJECTED = "card_rejected";
  * "Refused, and here is nothing" is the one answer a merchant cannot act on,
  * and publishing is the call where that would be easiest to send — a card is
  * refused precisely because something about it is wrong, so there is always
- * something to name. Not every finding is about the card. A merchant who has
- * set no name for buyers to read is refused here too, and so is one who has set
- * no wallet for their sales to be paid into; both ride in the same list, so one
- * answer carries everything standing between this card and the catalog rather
- * than handing it over one round trip at a time.
+ * something to name. Not every finding is about the card: the merchant's own
+ * missing settings (`MERCHANT_FINDINGS`) ride in the same list, so one answer
+ * carries everything standing between this card and the catalog rather than
+ * handing it over one round trip at a time.
  */
 const PublishRefusalSchema = CallErrorSchema.extend({
     problems: z.array(ProblemSchema).min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify-contracts",
-  "version": "0.4.0",
+  "version": "0.5.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": [