@nuanu-ai/agentify-contracts 0.3.2

package/dist/envelope.d.ts

@@ -0,0 +1,174 @@
+/**
+ * One message on the merchant's worker stream.
+ *
+ * The stream carries three different things — an order, a question about a
+ * price, a notification about an order — and it carries them on one connection
+ * because the portal promises the merchant one subscription (ADR-0004 §2).
+ * Everything on it is therefore wrapped in the same envelope, whose marker says
+ * which of the three the wrapper is holding.
+ *
+ * Three decisions are worth arguing rather than leaving to be inferred.
+ *
+ * The payload sits under its own key instead of being spread into the
+ * envelope, and the reason is a collision that would be silent. An order
+ * already carries an `id`, and that identifier is its idempotency key — the
+ * thing a handler answers from on a redelivery. Spread flat, the envelope's own
+ * identifier and the order's would be one field, one of the two would win, and
+ * whichever lost would be lost without a word. Nesting is what keeps the
+ * message's identity and the order's identity from ever being the same string.
+ *
+ * The key is `payload` for every kind rather than `order`, `quote_request` and
+ * `order_event` in turn. Naming it after the kind would say the same thing
+ * twice, and two things that say the same thing can disagree — a message
+ * marked one way and keyed the other has no reading. With one key the marker is
+ * the only place that answers "what is this", and it is checked: the schema
+ * holds the payload to the document its kind names, so a price question inside
+ * an envelope marked as an order is refused at the boundary rather than handed
+ * to an order handler.
+ *
+ * The kinds are the names the contract registry already publishes for those
+ * three documents. That is not decoration: the reader furthest from us has the
+ * JSON Schema export and nothing else, and a kind invented separately would be
+ * a second vocabulary for documents the export names once. A test holds the two
+ * in step.
+ *
+ * What the envelope does not carry is a handle for acking, because the
+ * acknowledgement of each kind is something that already exists: an order is
+ * acked by whatever its handler answers — the goods, a refusal, or taking the
+ * order on, each against the order's own identifier, and the last of those
+ * acknowledges without closing anything — a price question by the reply against
+ * `price_id`, and an event by nothing at all. A handle here would be a fourth
+ * way to name a message that three surfaces already name.
+ *
+ * That third one is a gap and not a design, and it decides how far each kind
+ * travels. Nothing takes a drawn envelope back after a visibility window: an
+ * order arrives again because the order machine decided there should be another
+ * attempt, and an event, which no machine is watching for a reply, does not
+ * arrive again at all. So an order is delivered at least once and an event at
+ * most once, and a consumer that guards one of them the way it guards the other
+ * has the wrong guard on both.
+ *
+ * The merchant never sees any of this. The SDK hands a handler an order, not
+ * the envelope it arrived in (ADR-0004 §5); the envelope is the format between
+ * the gateway and the SDK, and it lives in this package because both of them
+ * read it and neither owns it.
+ */
+import { z } from "zod";
+/**
+ * What each kind of envelope is holding, by the name the marker uses.
+ *
+ * The union below is built from these, so the marker and the check behind it
+ * cannot come apart.
+ */
+export declare const WORKER_ENVELOPE_PAYLOADS: Readonly<{
+    /** A purchase that is paid for as far as its mode requires, waiting to be delivered. */
+    readonly order: z.ZodObject<{
+        id: z.ZodString;
+        merchant_item_id: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        price: z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+            at: z.ZodISODateTime;
+            as_of: z.ZodISODateTime;
+        }, z.core.$strict>;
+        price_id: z.ZodOptional<z.ZodString>;
+        test: z.ZodBoolean;
+    }, z.core.$strict>;
+    /** "How much is this and is it there", asked before a sale goes through. */
+    readonly quote_request: z.ZodObject<{
+        merchant_item_id: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        price_id: z.ZodString;
+        purpose: z.ZodEnum<{
+            purchase: "purchase";
+            poll: "poll";
+        }>;
+        expires_at: z.ZodISODateTime;
+    }, z.core.$strict>;
+    /** Something that happened to an order without the merchant doing anything. */
+    readonly order_event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"order.refund_due">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+        price: z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        reason: z.ZodEnum<{
+            refused: "refused";
+            deadline_passed: "deadline_passed";
+            merchant_left: "merchant_left";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"order.unpaid_after_confirmation">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"order.payment_failed_after_delivery">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>], "type">;
+}>;
+/** The marker one envelope carries, naming what its payload is. */
+export type WorkerEnvelopeKind = keyof typeof WORKER_ENVELOPE_PAYLOADS;
+export declare const WORKER_ENVELOPE_KINDS: readonly WorkerEnvelopeKind[];
+export declare const WorkerEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"order">;
+    id: z.ZodString;
+    sent_at: z.ZodISODateTime;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        merchant_item_id: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        price: z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+            at: z.ZodISODateTime;
+            as_of: z.ZodISODateTime;
+        }, z.core.$strict>;
+        price_id: z.ZodOptional<z.ZodString>;
+        test: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"quote_request">;
+    id: z.ZodString;
+    sent_at: z.ZodISODateTime;
+    payload: z.ZodObject<{
+        merchant_item_id: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        price_id: z.ZodString;
+        purpose: z.ZodEnum<{
+            purchase: "purchase";
+            poll: "poll";
+        }>;
+        expires_at: z.ZodISODateTime;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"order_event">;
+    id: z.ZodString;
+    sent_at: z.ZodISODateTime;
+    payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"order.refund_due">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+        price: z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        reason: z.ZodEnum<{
+            refused: "refused";
+            deadline_passed: "deadline_passed";
+            merchant_left: "merchant_left";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"order.unpaid_after_confirmation">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"order.payment_failed_after_delivery">;
+        order_id: z.ZodString;
+        at: z.ZodISODateTime;
+    }, z.core.$strict>], "type">;
+}, z.core.$strict>], "kind">;
+export type WorkerEnvelope = z.infer<typeof WorkerEnvelopeSchema>;

package/dist/envelope.js

@@ -0,0 +1,101 @@
+/**
+ * One message on the merchant's worker stream.
+ *
+ * The stream carries three different things — an order, a question about a
+ * price, a notification about an order — and it carries them on one connection
+ * because the portal promises the merchant one subscription (ADR-0004 §2).
+ * Everything on it is therefore wrapped in the same envelope, whose marker says
+ * which of the three the wrapper is holding.
+ *
+ * Three decisions are worth arguing rather than leaving to be inferred.
+ *
+ * The payload sits under its own key instead of being spread into the
+ * envelope, and the reason is a collision that would be silent. An order
+ * already carries an `id`, and that identifier is its idempotency key — the
+ * thing a handler answers from on a redelivery. Spread flat, the envelope's own
+ * identifier and the order's would be one field, one of the two would win, and
+ * whichever lost would be lost without a word. Nesting is what keeps the
+ * message's identity and the order's identity from ever being the same string.
+ *
+ * The key is `payload` for every kind rather than `order`, `quote_request` and
+ * `order_event` in turn. Naming it after the kind would say the same thing
+ * twice, and two things that say the same thing can disagree — a message
+ * marked one way and keyed the other has no reading. With one key the marker is
+ * the only place that answers "what is this", and it is checked: the schema
+ * holds the payload to the document its kind names, so a price question inside
+ * an envelope marked as an order is refused at the boundary rather than handed
+ * to an order handler.
+ *
+ * The kinds are the names the contract registry already publishes for those
+ * three documents. That is not decoration: the reader furthest from us has the
+ * JSON Schema export and nothing else, and a kind invented separately would be
+ * a second vocabulary for documents the export names once. A test holds the two
+ * in step.
+ *
+ * What the envelope does not carry is a handle for acking, because the
+ * acknowledgement of each kind is something that already exists: an order is
+ * acked by whatever its handler answers — the goods, a refusal, or taking the
+ * order on, each against the order's own identifier, and the last of those
+ * acknowledges without closing anything — a price question by the reply against
+ * `price_id`, and an event by nothing at all. A handle here would be a fourth
+ * way to name a message that three surfaces already name.
+ *
+ * That third one is a gap and not a design, and it decides how far each kind
+ * travels. Nothing takes a drawn envelope back after a visibility window: an
+ * order arrives again because the order machine decided there should be another
+ * attempt, and an event, which no machine is watching for a reply, does not
+ * arrive again at all. So an order is delivered at least once and an event at
+ * most once, and a consumer that guards one of them the way it guards the other
+ * has the wrong guard on both.
+ *
+ * The merchant never sees any of this. The SDK hands a handler an order, not
+ * the envelope it arrived in (ADR-0004 §5); the envelope is the format between
+ * the gateway and the SDK, and it lives in this package because both of them
+ * read it and neither owns it.
+ */
+import { z } from "zod";
+import { OrderEventSchema } from "./events.js";
+import { OrderSchema } from "./order.js";
+import { IdentifierSchema, TimestampSchema } from "./primitives.js";
+import { QuoteRequestSchema } from "./quote.js";
+/**
+ * What each kind of envelope is holding, by the name the marker uses.
+ *
+ * The union below is built from these, so the marker and the check behind it
+ * cannot come apart.
+ */
+export const WORKER_ENVELOPE_PAYLOADS = Object.freeze({
+    /** A purchase that is paid for as far as its mode requires, waiting to be delivered. */
+    order: OrderSchema,
+    /** "How much is this and is it there", asked before a sale goes through. */
+    quote_request: QuoteRequestSchema,
+    /** Something that happened to an order without the merchant doing anything. */
+    order_event: OrderEventSchema,
+});
+export const WORKER_ENVELOPE_KINDS = Object.freeze(Object.keys(WORKER_ENVELOPE_PAYLOADS));
+/**
+ * The fields every envelope carries, whatever it is holding.
+ *
+ * `id` names this message and `sent_at` names when it went out. What the pair is
+ * not is a way to recognise a repeat, and reading it as one costs a merchant
+ * goods: an order the gateway decides to send again is wrapped in a fresh
+ * envelope with a fresh `id`, so the only thing two attempts at one order have
+ * in common is the order they carry. The gateway does put an envelope back on the stream with its `id`
+ * untouched, but only on the paths where it drew that envelope and then handed
+ * it to nobody — so an identifier a worker has actually seen never comes round a
+ * second time. What holds still across a repeat is the order's own identifier
+ * inside the payload, which is what its handler answers from and what the portal
+ * tells a merchant to key on. An event needs neither, having no repeat to
+ * recognise.
+ */
+const envelopeOf = (kind, payload) => z.strictObject({
+    kind: z.literal(kind),
+    id: IdentifierSchema,
+    sent_at: TimestampSchema,
+    payload,
+});
+export const WorkerEnvelopeSchema = z.discriminatedUnion("kind", [
+    envelopeOf("order", WORKER_ENVELOPE_PAYLOADS.order),
+    envelopeOf("quote_request", WORKER_ENVELOPE_PAYLOADS.quote_request),
+    envelopeOf("order_event", WORKER_ENVELOPE_PAYLOADS.order_event),
+]);

package/dist/events.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The things that happen to an order without the merchant doing anything, and
+ * that they would otherwise only find by reconciling records by hand.
+ *
+ * They arrive on the same subscription as the orders and want no answer: an
+ * event notifies, it does not ask for work. The catalog is a minimum rather
+ * than a closed list, and it grows by a shape being added here — never by a
+ * sender inventing a name, because a consumer switching on the type has to be
+ * able to read an unknown one as a version mismatch rather than a typo.
+ *
+ * The names are prefixed by what they are about. Everything here is about an
+ * order; something that is not will not have to fight for a name.
+ */
+import { z } from "zod";
+export declare const ORDER_EVENT_TYPES: Readonly<{
+    /** The money moved and the delivery did not happen. */
+    readonly REFUND_DUE: "order.refund_due";
+    /** The merchant said they would deliver and the agent never paid. */
+    readonly UNPAID_AFTER_CONFIRMATION: "order.unpaid_after_confirmation";
+    /** The merchant delivered synchronously and the payment did not execute. */
+    readonly PAYMENT_FAILED_AFTER_DELIVERY: "order.payment_failed_after_delivery";
+}>;
+/**
+ * How an order came to owe a refund: the merchant refused after the money had
+ * moved, their delivery deadline passed, or they left and their open orders
+ * closed with them.
+ */
+export declare const RefundDueReasonSchema: z.ZodEnum<{
+    refused: "refused";
+    deadline_passed: "deadline_passed";
+    merchant_left: "merchant_left";
+}>;
+export declare const OrderEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"order.refund_due">;
+    order_id: z.ZodString;
+    at: z.ZodISODateTime;
+    price: z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    reason: z.ZodEnum<{
+        refused: "refused";
+        deadline_passed: "deadline_passed";
+        merchant_left: "merchant_left";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"order.unpaid_after_confirmation">;
+    order_id: z.ZodString;
+    at: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"order.payment_failed_after_delivery">;
+    order_id: z.ZodString;
+    at: z.ZodISODateTime;
+}, z.core.$strict>], "type">;
+export type RefundDueReason = z.infer<typeof RefundDueReasonSchema>;
+export type OrderEvent = z.infer<typeof OrderEventSchema>;

package/dist/events.js

@@ -0,0 +1,54 @@
+/**
+ * The things that happen to an order without the merchant doing anything, and
+ * that they would otherwise only find by reconciling records by hand.
+ *
+ * They arrive on the same subscription as the orders and want no answer: an
+ * event notifies, it does not ask for work. The catalog is a minimum rather
+ * than a closed list, and it grows by a shape being added here — never by a
+ * sender inventing a name, because a consumer switching on the type has to be
+ * able to read an unknown one as a version mismatch rather than a typo.
+ *
+ * The names are prefixed by what they are about. Everything here is about an
+ * order; something that is not will not have to fight for a name.
+ */
+import { z } from "zod";
+import { IdentifierSchema, MoneySchema, TimestampSchema } from "./primitives.js";
+export const ORDER_EVENT_TYPES = Object.freeze({
+    /** The money moved and the delivery did not happen. */
+    REFUND_DUE: "order.refund_due",
+    /** The merchant said they would deliver and the agent never paid. */
+    UNPAID_AFTER_CONFIRMATION: "order.unpaid_after_confirmation",
+    /** The merchant delivered synchronously and the payment did not execute. */
+    PAYMENT_FAILED_AFTER_DELIVERY: "order.payment_failed_after_delivery",
+});
+/**
+ * How an order came to owe a refund: the merchant refused after the money had
+ * moved, their delivery deadline passed, or they left and their open orders
+ * closed with them.
+ */
+export const RefundDueReasonSchema = z.enum(["refused", "deadline_passed", "merchant_left"]);
+export const OrderEventSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal(ORDER_EVENT_TYPES.REFUND_DUE),
+        order_id: IdentifierSchema,
+        at: TimestampSchema,
+        /**
+         * The sum owed, which is the price the sale went through at. The payment
+         * went from the buyer straight to the merchant's wallet and never passed
+         * through us, so sending it back is theirs to do — and an event naming
+         * only the order would leave them looking the sum up.
+         */
+        price: MoneySchema,
+        reason: RefundDueReasonSchema,
+    }),
+    z.strictObject({
+        type: z.literal(ORDER_EVENT_TYPES.UNPAID_AFTER_CONFIRMATION),
+        order_id: IdentifierSchema,
+        at: TimestampSchema,
+    }),
+    z.strictObject({
+        type: z.literal(ORDER_EVENT_TYPES.PAYMENT_FAILED_AFTER_DELIVERY),
+        order_id: IdentifierSchema,
+        at: TimestampSchema,
+    }),
+]);

package/dist/evm-address.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The address money can be sent to on an EVM chain, and the one thing that can
+ * be checked about one before it is used.
+ *
+ * An address is twenty bytes and nothing about those bytes is redundant, so a
+ * character lost or mistyped in one produces another perfectly valid address —
+ * belonging to nobody, or to somebody else, and a payment to it is gone. EIP-55
+ * is the only guard anybody has against that: the capital letters in the
+ * spelling a wallet shows are not decoration, they are a checksum over the
+ * address itself, and a character that is wrong stops the capitals agreeing
+ * with the digits. Checked here, a mistyped address is a sentence a merchant
+ * reads while they still have the right one in front of them; not checked, it
+ * is a stranger's wallet filling up with somebody's sales.
+ *
+ * Two spellings are accepted and no others. All lower case is the spelling that
+ * carries no checksum at all, and it is what a block explorer prints and what
+ * half the tooling in this world hands somebody, so refusing it would refuse
+ * addresses that are perfectly good. The other is the exact output of the
+ * checksum, which is what a wallet puts on the clipboard. Anything between the
+ * two is a string that has been through something: a case-mangling copy, a
+ * document that shouted it, or a keystroke in the wrong place. The refusal says
+ * so and says what to do instead, because "invalid address" leaves a person
+ * staring at forty characters that look fine.
+ *
+ * Of the two, the wallet's is the canon: the door takes both spellings and
+ * everything behind it holds one (ADR-0017), and `checksummedAddressOf` below
+ * is what writes it. The reason is about the person rather than about the
+ * storage, and it is written where that function is.
+ *
+ * The hash is written out below rather than taken from a package, and that is a
+ * decision rather than an oversight. This package's runtime dependency tree is
+ * `zod` and nothing else, and it is the whole of what a merchant installs with
+ * the SDK — ADR-0003 §8 makes every addition to it a decision of its own, and
+ * that decision is not this file's to take. What is written out is therefore
+ * kept as small as the job allows: twenty-four rounds of a fixed permutation
+ * over one block, with no configuration and no second use, and it is pinned by
+ * the vectors the standard publishes, so an implementation that is wrong
+ * anywhere fails against somebody else's arithmetic rather than agreeing with
+ * itself. The cost is named too: this is hand-written cryptographic code in a
+ * published package, and the trigger to replace it with an audited library is
+ * the first other thing in this package that needs a hash.
+ */
+import { z } from "zod";
+/**
+ * One address written the way the wallet it came out of displays it: the
+ * canonical form, and the one anything behind the door keeps.
+ *
+ * The door takes two spellings and everything behind it holds one (ADR-0017),
+ * and this is the one, because it is the one a person recognises. A merchant
+ * pastes forty characters out of their wallet and then reads them back on a
+ * settings screen; handed the same address in lower case they cannot tell it
+ * from a different address without comparing character by character, and the
+ * one field in this system where that matters is the field money is sent to.
+ * Lower case would be the easier canon to compute and the harder one to check
+ * by eye, and the eye is the only thing checking.
+ *
+ * It refuses what the schema refuses rather than quietly repairing it. Given a
+ * mixed-case address whose letters disagree with its digits, capitalising it
+ * afresh would produce a perfectly well-formed address that nobody typed —
+ * which is the exact failure the checksum exists to catch, arrived at by the
+ * thing meant to enforce it.
+ *
+ * Given an address that is already in this form it answers with the same
+ * string, so writing one down twice writes the same thing twice.
+ */
+export declare function checksummedAddressOf(address: string): string;
+/**
+ * An address on an EVM chain, in one of the two spellings anybody writes one
+ * in.
+ *
+ * It carries no chain of its own. The same twenty bytes are an address on every
+ * EVM network, and which network a payment is made on is settled by the payment
+ * requirements rather than by the address inside them; a schema that claimed
+ * otherwise would be claiming knowledge this package does not have.
+ */
+export declare const EvmAddressSchema: z.ZodString;
+export type EvmAddress = z.infer<typeof EvmAddressSchema>;