@nuanu-ai/agentify-contracts 0.3.2

package/dist/index.js

@@ -0,0 +1,167 @@
+/**
+ * Agentify contracts — the single source of truth for the card, the order, the
+ * price check, the receipt and everything else that crosses the boundary
+ * between us, a merchant and an agent. Everything that goes outside or arrives
+ * from outside is described here by a zod schema; consumers get their types by
+ * inference from the schema instead of writing them by hand (ADR-0003 §5).
+ *
+ * This package owns the wire vocabulary: the field names, the values an agent
+ * or a merchant can see, the refusal codes, the event names. What the gateway
+ * calls things inside itself is its own business, and the two are tied
+ * together where they meet rather than by one importing the other.
+ *
+ * Two shapes here are read by nobody outside our own two parts, and they are
+ * described anyway. The worker envelope carries orders, price questions and
+ * events on one stream (ADR-0004 §2), and the merchant never sees it, because
+ * the SDK hands a handler an order rather than the wrapper it arrived in. The
+ * route table says which calls exist, at which addresses, with which document
+ * going each way. Both are formats between the gateway and the SDK, read by
+ * both and owned by neither — which is the same reason a card lives here, and
+ * the reason a shape agreed in two places is a shape that has already
+ * disagreed once.
+ */
+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 { 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 { 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 { 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 { 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, 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 { SELLING_STATES, SellingStateSchema } from "./selling.js";
+/**
+ * The version of the public contract. It grows when the meaning of the fields
+ * changes, not when a schema is added: a consumer uses it to decide whether it
+ * understands the other side.
+ */
+export const CONTRACT_VERSION = "2";
+/**
+ * Every schema of the public contract, under the name it is known by outside
+ * TypeScript.
+ *
+ * The registry is what makes the contract readable by something that is not
+ * this package: the JSON Schema export below walks it, and a merchant's
+ * engineer working in another language reads that. It carries the building
+ * blocks as well as the whole documents, because a merchant validating one
+ * amount should not have to lift it out of a card.
+ *
+ * A schema that exists and is not here is a schema nobody outside TypeScript
+ * can see, so a test holds the two in step.
+ */
+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,
+    delivery: DeliverySchema,
+    disabled_key: DisabledKeySchema,
+    error_envelope: ErrorEnvelopeSchema,
+    evm_address: EvmAddressSchema,
+    field_spec: FieldSpecSchema,
+    forgotten_cabinet_key: ForgottenCabinetKeySchema,
+    fulfillment: FulfillmentSchema,
+    handler_answer: HandlerAnswerSchema,
+    identifier: IdentifierSchema,
+    issue_key_request: IssueKeyRequestSchema,
+    issued_key: IssuedKeySchema,
+    merchant_card: MerchantCardSchema,
+    merchant_card_list: MerchantCardListSchema,
+    merchant_key: MerchantKeySchema,
+    merchant_key_list: MerchantKeyListSchema,
+    money: MoneySchema,
+    order: OrderSchema,
+    order_accept_response: OrderAcceptResponseSchema,
+    order_call_response: OrderCallResponseSchema,
+    order_call_result: OrderCallResultSchema,
+    order_event: OrderEventSchema,
+    order_list: OrderListSchema,
+    order_list_query: OrderListQuerySchema,
+    order_status: OrderStatusSchema,
+    order_with_status: OrderWithStatusSchema,
+    param_name: ParamNameSchema,
+    param_spec: ParamSpecSchema,
+    param_type: ParamTypeSchema,
+    payout_wallet: PayoutWalletSchema,
+    payout_wallet_request: PayoutWalletRequestSchema,
+    price_check: PriceCheckSchema,
+    problem: ProblemSchema,
+    public_card: PublicCardSchema,
+    publish_result: PublishResultSchema,
+    purchase_request: PurchaseRequestSchema,
+    quote_answer_ack: QuoteAnswerAckSchema,
+    quote_purpose: QuotePurposeSchema,
+    quote_request: QuoteRequestSchema,
+    quote_response: QuoteResponseSchema,
+    receipt: ReceiptSchema,
+    receipt_list: ReceiptListSchema,
+    receipt_outcome: ReceiptOutcomeSchema,
+    registered_merchant: RegisteredMerchantSchema,
+    registration_request: RegistrationRequestSchema,
+    refund_due_reason: RefundDueReasonSchema,
+    refusal: RefusalSchema,
+    refusal_code: RefusalCodeSchema,
+    sale_price: SalePriceSchema,
+    seller_name: SellerNameSchema,
+    seller_name_request: SellerNameRequestSchema,
+    selling_state: SellingStateSchema,
+    service_name: ServiceNameSchema,
+    tags: TagsSchema,
+    timestamp: TimestampSchema,
+    worker_envelope: WorkerEnvelopeSchema,
+    worker_poll_request: WorkerPollRequestSchema,
+    worker_poll_response: WorkerPollResponseSchema,
+});
+/** The identifier a rendered document carries, so a reader knows what it holds. */
+export const jsonSchemaIdOf = (name) => `urn:agentify:contract:${CONTRACT_VERSION}:${name}`;
+/**
+ * The whole contract as JSON Schema, one document per registry entry.
+ *
+ * A function rather than a constant: the conversion costs something, and a
+ * consumer who only needs to validate a card in TypeScript should not pay for
+ * a description of everything else at import time.
+ *
+ * What the documents carry and what they do not is worth saying plainly,
+ * because the difference is invisible from the outside. Structure crosses
+ * intact — fields, types, which are required, whether unknown keys are
+ * allowed, enumerations, patterns, the branches of a union. Rules that look at
+ * more than one field at a time do not: JSON Schema cannot say "this field
+ * only when that one has this value", and zod drops such a rule without a
+ * word. Every schema that has one says so in its own `description`, which does
+ * cross, so a reader of the document is told what it is not checking rather
+ * than left to assume it checks everything.
+ *
+ * Each document is stamped with the contract version it came from.
+ */
+export const toJsonSchemas = () => {
+    const documents = {};
+    for (const [name, schema] of Object.entries(schemas)) {
+        documents[name] = { $id: jsonSchemaIdOf(name), ...z.toJSONSchema(schema) };
+    }
+    return documents;
+};

package/dist/merchant.d.ts

@@ -0,0 +1,281 @@
+/**
+ * How a merchant comes to exist, the name their products are sold under, the
+ * wallet their sales are paid into, and the keys they open the door with.
+ *
+ * The first two belong together because registering is the act that produces
+ * both: one call makes the merchant and the key its cabinet will call as them
+ * with, and what comes back carries that key once. Split across two files, a
+ * reader working out what registering leaves a merchant holding would have to
+ * read both to find that it is a key of a kind no list here carries. The name is here for the same reason read the other way round — it is a
+ * fact about the merchant and about none of their cards, and the one question a
+ * reader arrives with is which of the two names a merchant has is which.
+ *
+ * Two rules run through the file and are worth saying once.
+ *
+ * The secret appears in exactly three documents, and every one of them is the
+ * answer to a call that has just made a key. Nothing that is ever drawn again —
+ * the list a merchant reads, the row that comes back from disabling one — can
+ * carry it, and the shapes below refuse it rather than merely omit it. What is
+ * kept on our side is a digest, so there is nothing to put in those documents
+ * even if somebody wanted to.
+ *
+ * And a key that has been revoked stays in the list. `disabled_at` is a moment
+ * rather than a flag, and it is always present: after an incident the question
+ * is when a key stopped working, and a list that dropped the key answers
+ * nothing, while a flag answers only half.
+ */
+import { z } from "zod";
+/**
+ * One key a merchant holds, as they read it.
+ *
+ * The secret is not here and cannot be put here. This is the document a screen
+ * lists, drawn again on every visit, and the secret is shown once by the call
+ * that made the key and never again — so a shape that could carry one is a
+ * shape that eventually does.
+ */
+export declare const MerchantKeySchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    created_at: z.ZodISODateTime;
+    last_used_at: z.ZodNullable<z.ZodISODateTime>;
+    disabled_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+/**
+ * The keys one merchant made for their own code, and the one this call was made
+ * with.
+ *
+ * `this_call` is the field the list cannot be assembled without, and the reason
+ * is a rule in the route rather than anything about the shape: a merchant
+ * cannot disable the key their own call was made with (ADR-0014 §5). A screen
+ * that did not know which of these that was would offer a button the route
+ * refuses, on the one page where being refused looks like the product being
+ * broken.
+ *
+ * It is not always one of the keys beside it, and that is the thing a reader is
+ * likeliest to assume and be wrong about. A cabinet calls with a key made for a
+ * cabinet, and those are in nobody's list, so a client that looked this
+ * identifier up among the rows would find nothing — which is an answer rather
+ * than an error, and a screen has to be built for it.
+ *
+ * An object rather than a bare array, for that reason before any other — an
+ * array has nowhere to put it.
+ */
+export declare const MerchantKeyListSchema: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        created_at: z.ZodISODateTime;
+        last_used_at: z.ZodNullable<z.ZodISODateTime>;
+        disabled_at: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    this_call: z.ZodString;
+}, z.core.$strict>;
+/** What a merchant sends to have a key made. */
+export declare const IssueKeyRequestSchema: z.ZodObject<{
+    label: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A key that has just been made: the row, and the secret, once.
+ *
+ * Both halves are needed by the caller. Without the secret there is no key to
+ * hand to a worker; without the row there is a string and nothing to say which
+ * of the merchant's keys it is, which is the thing they need to disable it
+ * later.
+ */
+export declare const IssuedKeySchema: z.ZodObject<{
+    key: z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        created_at: z.ZodISODateTime;
+        last_used_at: z.ZodNullable<z.ZodISODateTime>;
+        disabled_at: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    secret: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A key that has been revoked, as it now stands.
+ *
+ * An object rather than the key itself, so the day this answer has to say
+ * anything beside the key — how many of the merchant's keys still work, say — it
+ * grows a field instead of changing shape under every reader.
+ */
+export declare const DisabledKeySchema: z.ZodObject<{
+    key: z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        created_at: z.ZodISODateTime;
+        last_used_at: z.ZodNullable<z.ZodISODateTime>;
+        disabled_at: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * A key made for a cabinet, which is the secret and nothing else.
+ *
+ * Every other answer that makes a key carries the row beside it, and this one
+ * cannot. A key made for a cabinet is in no merchant's list — they did not
+ * issue it and have no reason to know it exists — so an identifier here would
+ * name a row that no screen of theirs draws and no call of theirs reaches: not
+ * the list it is absent from, and not the revoking, which takes the keys a
+ * merchant issued and refuses this kind by name. What the caller does with this
+ * is put it on the row of whoever just signed in, and that is the whole of what
+ * it needs.
+ */
+export declare const CabinetKeySchema: z.ZodObject<{
+    secret: z.ZodString;
+}, z.core.$strict>;
+/**
+ * That the key a call was made with is gone.
+ *
+ * A constant, and deliberately: the call has one outcome. It removes the key it
+ * was made with and no other, so there is nothing to count — a number here
+ * could only be about rows this call cannot reach — and nothing to name, since
+ * the caller is holding the only key it names. What is left to say is that it
+ * is done, and it is said in a field rather than left to a status code so that
+ * a client reads one document and not two kinds of evidence.
+ */
+export declare const ForgottenCabinetKeySchema: z.ZodObject<{
+    forgotten: z.ZodLiteral<true>;
+}, z.core.$strict>;
+/**
+ * What a merchant's products are sold under, as the merchant reads it back.
+ *
+ * Null is the fact "nobody has chosen one", which is every merchant on the day
+ * they register and is the state they stay in until they do. It is a value
+ * rather than an absent field, because an absent field would be
+ * indistinguishable from a client that dropped it, and a settings screen
+ * reading the second as the first would tell a merchant they are listed under
+ * nothing while they are listed under something.
+ *
+ * The name is held to the rule of the catalog that carries it, which is where
+ * this name is going: at most thirty-two characters of printable ASCII. That
+ * bound is not ours and is not about our own storage — the catalog drops what
+ * it cannot render and tells nobody, so a name refused here is a name the
+ * merchant is told about, and a name accepted here and dropped there is a
+ * seller trading under something they did not choose.
+ */
+export declare const SellerNameSchema: z.ZodObject<{
+    seller_name: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * What a merchant sends to change what their products are sold under.
+ *
+ * The same field held to the same rule, and one difference: there is no null.
+ * A merchant can go from having no name to having one and from one name to
+ * another, and not back. Having none is a starting state rather than a setting,
+ * because a payment request names the seller and there would be nobody to name:
+ * every card they had already published would come off sale, which is an end to
+ * their selling arriving under the name of editing a setting. What somebody
+ * reaching for that actually wants is one of two other acts: a different name,
+ * 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
+ * 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>;
+}, z.core.$strict>;
+/**
+ * The wallet a merchant's sales are paid into, as the merchant reads it back.
+ *
+ * Payments here are not held by anybody on the way: a buyer's agent pays the
+ * merchant's own address directly, and this is that address. There is no
+ * account of theirs on our side with a balance in it and no moment at which
+ * their money is ours, which is why this field exists at all — without it there
+ * would have to be.
+ *
+ * Null is the fact "nobody has said where the money goes", which is every
+ * merchant on the day they register. It is a value rather than an absent field
+ * for the reason the seller name is: a settings screen cannot tell a silence
+ * from a client that dropped the field, and reading the second as the first
+ * tells a merchant they are set up to be paid when nothing of theirs can be.
+ *
+ * What comes back is always the spelling a wallet shows, whichever of the two
+ * accepted spellings was sent. The door takes both and everything behind it
+ * holds one (ADR-0017), and this is the one for a reason that is about the
+ * person rather than about the storage: a merchant pastes forty characters out
+ * of their wallet and reads them back on a settings screen, and handed the same
+ * 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.
+ */
+export declare const PayoutWalletSchema: z.ZodObject<{
+    payout_wallet: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * What a merchant sends to change where their sales are paid.
+ *
+ * The same field held to the same rule, and one difference, which is the same
+ * difference the seller name has and rests on something harder. There is no
+ * null. A merchant goes from having no wallet to having one and from one wallet
+ * to another, and not back: a merchant who took their address away would keep
+ * every card they had already published on sale, and the payment request an
+ * agent is answered with cannot be built at all without an address — so the
+ * products would stop being buyable and nothing anywhere would say why. What
+ * somebody reaching for null actually wants is one of two other acts: a
+ * different address, which is this same call, or an end to selling, which is
+ * the pause, and the pause leaves their cards where they can put them back.
+ *
+ * There is nowhere here to put a key, and a document carrying one is refused
+ * rather than trimmed. This contract knows where a merchant is paid and has no
+ * business knowing anything that could spend it.
+ */
+export declare const PayoutWalletRequestSchema: z.ZodObject<{
+    payout_wallet: z.ZodPipe<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/**
+ * What somebody sends to become a merchant.
+ *
+ * One field, and what is not here is most of what is worth reading. The address
+ * and the password belong to the account rather than to the merchant, and they
+ * stay on the other side of the boundary (ADR-0014 §1) — a gateway that took
+ * either would be holding a person's credentials on the money path, which is
+ * what this route's whole shape is arranged to avoid.
+ *
+ * The name the seller's products are sold under is not here either, and that
+ * omission is a decision rather than a simplification. It is a public answer,
+ * and asking for it here asks for it at the one moment a merchant knows least:
+ * no products, no catalogue seen, no idea what the name is for. It is asked for
+ * on the screen after this one instead, where there is room to say why it
+ * matters, and it can be changed afterwards from the merchant's own settings.
+ *
+ * The shape refuses a name rather than ignoring one, because a field quietly
+ * dropped is a person believing they have chosen what buyers will read.
+ */
+export declare const RegistrationRequestSchema: z.ZodObject<{
+    invitation: z.ZodString;
+}, z.core.$strict>;
+/**
+ * What registering answers with: a merchant and the key their cabinet will call
+ * as them with.
+ *
+ * The key is made for a cabinet rather than for the merchant's own code, and
+ * that is what the caller of this route is. So it is in no list: a merchant who
+ * has just registered has no keys of their own at all, and the first one they
+ * do have is one they ask for. No row travels beside the secret for the same
+ * reason no row appears in the list — the merchant did not issue it and cannot
+ * disable it, so an identifier for it would be a value with nothing to do.
+ *
+ * No name comes back either, because none was chosen. A merchant who has just
+ * registered is listed under nothing at all, and a field here would either be a
+ * name this call invented or a null that says the same thing at more length.
+ */
+export declare const RegisteredMerchantSchema: z.ZodObject<{
+    merchant_id: z.ZodString;
+    secret: z.ZodString;
+}, z.core.$strict>;
+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 MerchantKey = z.infer<typeof MerchantKeySchema>;
+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 RegistrationRequest = z.infer<typeof RegistrationRequestSchema>;
+export type RegisteredMerchant = z.infer<typeof RegisteredMerchantSchema>;