@nuanu-ai/agentify-contracts 0.3.2

package/dist/order.js

@@ -0,0 +1,78 @@
+/**
+ * The order, as it reaches the merchant's handler.
+ *
+ * By the time an order exists the purchase has already been checked on our
+ * side: the card was found, the parameters passed the card's own declaration,
+ * the price was settled and the payment was verified. Invalid purchases, stale
+ * prices and payments that did not verify never reach a handler, which is why
+ * this schema is short.
+ *
+ * Everything here answers a question the handler would otherwise have to ask
+ * us: what to deliver, to whom, under which of its own keys, at what price,
+ * and whether the money behind it is real.
+ *
+ * What state an order is in is not a field here. Reading state back — one
+ * order, or every order still open — is a separate call, and the words it
+ * answers with are `OrderStatusSchema` in `order-status.ts`.
+ *
+ * A second thing an order does not carry is its deadline. The design canon
+ * says an order carries one and the portal says a synchronous order does, but
+ * the portal's own table of what an order consists of does not list it, and
+ * this schema follows the table. The consequence stands either way: this
+ * package is the whole of the SDK's dependency tree, so nothing in it lets a
+ * synchronous handler learn how long it has — and in that mode the budget is
+ * ours, not something the merchant set and could look up. Which of the two
+ * readings is right is a question for whoever settles the numbers.
+ *
+ * One shape the documentation promises is still missing, and it is named here
+ * rather than left to be found as an absence. In the mode where the merchant
+ * is asked before the money moves, a confirmation request reaches the same
+ * subscription as the orders and is marked as a request rather than an order —
+ * no payment has happened, and delivering against one is not allowed. Nothing
+ * in this package carries that mark, so the two would be indistinguishable on
+ * the wire. Rather than leave that as a trap, the card refuses to publish in
+ * that mode at all until the request has a shape; see `card.ts`.
+ */
+import { z } from "zod";
+import { ParamNameSchema } from "./param-spec.js";
+import { IdentifierSchema, SalePriceSchema } from "./primitives.js";
+export const OrderSchema = z.strictObject({
+    /**
+     * The order's identifier, which is also its idempotency key: the same string
+     * on every redelivery. Delivery is at-least-once, so a handler that answers
+     * from this key instead of delivering twice is not being careful, it is
+     * being correct.
+     */
+    id: IdentifierSchema,
+    /** The merchant's own key for the product, the one their database uses. */
+    merchant_item_id: IdentifierSchema,
+    /**
+     * The purchase parameters, already checked against the card's declaration.
+     * Always present, empty for a card that takes no input — a handler should
+     * never have to tell "no parameters" from "the field did not arrive".
+     */
+    // One key is dropped here rather than carried or refused; the reason is at
+    // `PROTOTYPE_KEY_IS_DROPPED` in `param-spec.ts`.
+    params: z.record(ParamNameSchema, z.unknown()),
+    /**
+     * What the product was actually sold for, which is not always what the card
+     * says: a card with a price check sells at the price the check answered.
+     * Both moments travel with it, so the sale can be written down as it stands.
+     */
+    price: SalePriceSchema,
+    /**
+     * The identifier of the price question this sale came out of, absent when
+     * there was none — a card without a price check sells from its own price and
+     * no question was ever asked. A merchant who set stock aside under this
+     * identifier can release it here.
+     */
+    price_id: IdentifierSchema.optional(),
+    /**
+     * Whether this is a test order.
+     *
+     * Required rather than defaulted. The safe reading of a missing flag is not
+     * obvious in either direction, and a test order taken for a live one is a
+     * real delivery made against money that does not exist.
+     */
+    test: z.boolean(),
+});

package/dist/param-spec.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The small schema language a card writes its purchase parameters and its
+ * delivery result in, and the compiler that turns one of those declarations
+ * into a check.
+ *
+ * Both halves live here on purpose. The gateway validates an agent's purchase
+ * against the card's `params`, and the SDK holds a merchant's delivery to the
+ * card's `result`; if each side compiled the declaration its own way, a card
+ * would mean two different things and the difference would only show up after
+ * someone had paid.
+ *
+ * The language is deliberately small — four scalar types and nothing else.
+ * The portal names the exact schema of parameters as still open, and a richer
+ * language invented here (enumerations, lists, nested objects) would be a
+ * contract nobody agreed to. It grows when a real card needs it to.
+ */
+import { z } from "zod";
+/**
+ * The types a card may declare.
+ *
+ * Every one of them has a check behind it in `paramSpecToValidator`. A type
+ * this list does not carry would promise the agent a validation that nobody
+ * performs, which is why the enumeration and the compiler sit in one file.
+ */
+export declare const ParamTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    integer: "integer";
+}>;
+/**
+ * The name of one parameter.
+ *
+ * A name becomes a property in JSON on both sides of the wire and a segment of
+ * the error path a merchant reads, so it is held to the shape of a plain
+ * identifier. Dots would collide with that path notation and spaces would make
+ * the name unquotable in an error. Both `access_url` and `expiresAt` are fine:
+ * which of the two a merchant writes is theirs to choose.
+ *
+ * One name never gets this far: see `PROTOTYPE_KEY_IS_DROPPED` below.
+ */
+export declare const ParamNameSchema: z.ZodString;
+/**
+ * One declared parameter: what type it holds, whether it has to be there, and
+ * a line of human words explaining what it is for.
+ *
+ * What silence about `required` means depends on which of a card's two
+ * declarations this is, and the compiler below is where that is decided. In
+ * the purchase parameters a field with no flag is one the agent may leave out;
+ * in the delivery result it is one that arrives. Setting the flag says the
+ * same thing in both directions, and it is the only way to say the opposite.
+ */
+export declare const FieldSpecSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        integer: "integer";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The one silent loss in this contract, written down once because five places
+ * have it and a note on one of them was worse than none.
+ *
+ * A key named `__proto__` is removed by zod while a record is parsed, before
+ * any check of ours runs — so it is neither carried nor refused, and nobody is
+ * told. It applies wherever this contract parses a record of free-form names,
+ * and there are five of those: a card's `params` and `result` here, an order's
+ * `params`, a purchase's `params`, a price question's `params`, and a delivery.
+ * The check compiled below is not a sixth. It is built from a spec that has
+ * already been through the record above, so a name that would have been
+ * dropped is gone before the compiler ever sees it.
+ *
+ * Every one of those is a place the portal promises to pass values through
+ * unchanged, so the loss is worth knowing about even though nothing can
+ * legitimately reach it: no card can declare such a field, so a merchant only
+ * meets this by sending a name nobody asked for. The behaviour is zod's, not
+ * ours, and it is the reason the compiler below can never be handed a name
+ * that would set a prototype instead of declaring a field. A test holds it in
+ * place, so a change in zod is noticed here rather than in production.
+ */
+export declare const PROTOTYPE_KEY_IS_DROPPED = "__proto__";
+/** A whole declaration: the parameters of a purchase, or a delivery result. */
+export declare const ParamSpecSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        integer: "integer";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type ParamType = z.infer<typeof ParamTypeSchema>;
+export type FieldSpec = z.infer<typeof FieldSpecSchema>;
+export type ParamSpec = z.infer<typeof ParamSpecSchema>;
+/**
+ * One declared field as a merchant may write it on a card: the whole spec, or
+ * the type word alone.
+ *
+ * The short form belongs to the card and is opened out where a card is parsed,
+ * so this type says what may be written and never what is stored or read back.
+ * The rule and the reasons are in `card.ts`, beside the other two short forms.
+ */
+export type FieldSpecInput = FieldSpec | ParamType;
+/** A whole declaration as a merchant may write it, field by field. */
+export type ParamSpecInput = Record<string, FieldSpecInput>;
+/**
+ * Which of a card's two declarations is being compiled.
+ *
+ * It decides two things, and both come from the same difference: a purchase is
+ * input the agent is being asked for, and a delivery is a promise the card
+ * made to it before it paid.
+ *
+ * What silence about `required` means. In a purchase the portal writes
+ * `required: true` only where it means it, so a field with no flag is one the
+ * agent may leave out. In a delivery a declared field is one that arrives — a
+ * flag-less field treated as optional would make the promise unenforceable,
+ * and a merchant could deliver an empty object against a card that advertised
+ * three fields. A delivery field that genuinely may be absent says so with
+ * `required: false`.
+ *
+ * And whether a string may be empty. It may in a purchase and may not in a
+ * delivery, for the reason written beside the check itself.
+ */
+export type ParamSpecDirection = "purchase" | "delivery";
+/**
+ * Turns a declaration into the check that an instance of it is held to.
+ *
+ * Keys the declaration does not carry are refused, in both directions. The two
+ * alternatives both lie: stripping them is truncation that nobody is told
+ * about, and passing them through hands the merchant's handler fields the card
+ * never declared — a card that does not describe what arrives, and a way to
+ * push input into someone else's code. In a delivery an undeclared field means
+ * the agent paid for something other than the result it read before paying.
+ *
+ * One thing this cannot refuse is a key named `__proto__`; see
+ * `PROTOTYPE_KEY_IS_DROPPED` above.
+ *
+ * The spec is expected to have been parsed by `ParamSpecSchema` already; that
+ * is what the parameter type says.
+ */
+export declare const paramSpecToValidator: (spec: ParamSpec, direction: ParamSpecDirection) => z.ZodType;

package/dist/param-spec.js

@@ -0,0 +1,147 @@
+/**
+ * The small schema language a card writes its purchase parameters and its
+ * delivery result in, and the compiler that turns one of those declarations
+ * into a check.
+ *
+ * Both halves live here on purpose. The gateway validates an agent's purchase
+ * against the card's `params`, and the SDK holds a merchant's delivery to the
+ * card's `result`; if each side compiled the declaration its own way, a card
+ * would mean two different things and the difference would only show up after
+ * someone had paid.
+ *
+ * The language is deliberately small — four scalar types and nothing else.
+ * The portal names the exact schema of parameters as still open, and a richer
+ * language invented here (enumerations, lists, nested objects) would be a
+ * contract nobody agreed to. It grows when a real card needs it to.
+ */
+import { z } from "zod";
+/**
+ * The types a card may declare.
+ *
+ * Every one of them has a check behind it in `paramSpecToValidator`. A type
+ * this list does not carry would promise the agent a validation that nobody
+ * performs, which is why the enumeration and the compiler sit in one file.
+ */
+export const ParamTypeSchema = z.enum(["string", "number", "integer", "boolean"]);
+/**
+ * The name of one parameter.
+ *
+ * A name becomes a property in JSON on both sides of the wire and a segment of
+ * the error path a merchant reads, so it is held to the shape of a plain
+ * identifier. Dots would collide with that path notation and spaces would make
+ * the name unquotable in an error. Both `access_url` and `expiresAt` are fine:
+ * which of the two a merchant writes is theirs to choose.
+ *
+ * One name never gets this far: see `PROTOTYPE_KEY_IS_DROPPED` below.
+ */
+export const ParamNameSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, "a parameter name starts with a letter and carries letters, digits and underscores");
+/**
+ * One declared parameter: what type it holds, whether it has to be there, and
+ * a line of human words explaining what it is for.
+ *
+ * What silence about `required` means depends on which of a card's two
+ * declarations this is, and the compiler below is where that is decided. In
+ * the purchase parameters a field with no flag is one the agent may leave out;
+ * in the delivery result it is one that arrives. Setting the flag says the
+ * same thing in both directions, and it is the only way to say the opposite.
+ */
+export const FieldSpecSchema = z.strictObject({
+    type: ParamTypeSchema,
+    required: z.boolean().optional(),
+    title: z.string().regex(/\S/, "a title must not be empty or blank").optional(),
+});
+/**
+ * The one silent loss in this contract, written down once because five places
+ * have it and a note on one of them was worse than none.
+ *
+ * A key named `__proto__` is removed by zod while a record is parsed, before
+ * any check of ours runs — so it is neither carried nor refused, and nobody is
+ * told. It applies wherever this contract parses a record of free-form names,
+ * and there are five of those: a card's `params` and `result` here, an order's
+ * `params`, a purchase's `params`, a price question's `params`, and a delivery.
+ * The check compiled below is not a sixth. It is built from a spec that has
+ * already been through the record above, so a name that would have been
+ * dropped is gone before the compiler ever sees it.
+ *
+ * Every one of those is a place the portal promises to pass values through
+ * unchanged, so the loss is worth knowing about even though nothing can
+ * legitimately reach it: no card can declare such a field, so a merchant only
+ * meets this by sending a name nobody asked for. The behaviour is zod's, not
+ * ours, and it is the reason the compiler below can never be handed a name
+ * that would set a prototype instead of declaring a field. A test holds it in
+ * place, so a change in zod is noticed here rather than in production.
+ */
+export const PROTOTYPE_KEY_IS_DROPPED = "__proto__";
+/** A whole declaration: the parameters of a purchase, or a delivery result. */
+export const ParamSpecSchema = z.record(ParamNameSchema, FieldSpecSchema, {
+    // What a value that is not a declaration at all is told. The default —
+    // "expected record, received string" — names a word from the schema library
+    // rather than from the card, and it lands on the one mistake the short form
+    // invites: a merchant who has learned that `access_url: 'string'` declares a
+    // field writes `result: 'string'` and has declared nothing. The sentence
+    // shows the shape they meant.
+    //
+    // Only where something was written. A declaration that is simply absent is a
+    // different finding — a required field nobody filled in — and returning
+    // nothing here leaves zod's own words for it, which say exactly that.
+    error: (issue) => issue.input === undefined
+        ? undefined
+        : "a declaration names each field and gives its type, as in { access_url: 'string' }; a type word on its own declares one field and not the whole of it",
+});
+const checkFor = (type, direction) => {
+    switch (type) {
+        case "string":
+            // A delivered string carries something. This is the one place the two
+            // directions hold the same declared type to different rules, and the
+            // asymmetry is the point rather than an oversight.
+            //
+            // In a purchase, an empty string is input the agent chose to give: a
+            // note left blank, a name it does not have. Refusing it would be this
+            // package inventing a requirement no card asked for.
+            //
+            // In a delivery the field is a promise about what the buyer receives,
+            // and an empty access code is not a shorter access code — it is nothing,
+            // arriving under the name of something. Without this the check refuses
+            // `{}` and accepts `{access_code: ""}`, which are the same outcome for
+            // the buyer, and only one of them would be caught. Every other string on
+            // this wire is already held this way — a title, a description, a refusal
+            // code and its message all refuse to be blank — and the one the buyer
+            // actually paid for was the exception.
+            return direction === "delivery"
+                ? z.string().regex(/\S/, "a delivered field carries something, and this one is blank")
+                : z.string();
+        case "number":
+            return z.number();
+        case "integer":
+            return z.int();
+        case "boolean":
+            return z.boolean();
+    }
+};
+/**
+ * Turns a declaration into the check that an instance of it is held to.
+ *
+ * Keys the declaration does not carry are refused, in both directions. The two
+ * alternatives both lie: stripping them is truncation that nobody is told
+ * about, and passing them through hands the merchant's handler fields the card
+ * never declared — a card that does not describe what arrives, and a way to
+ * push input into someone else's code. In a delivery an undeclared field means
+ * the agent paid for something other than the result it read before paying.
+ *
+ * One thing this cannot refuse is a key named `__proto__`; see
+ * `PROTOTYPE_KEY_IS_DROPPED` above.
+ *
+ * The spec is expected to have been parsed by `ParamSpecSchema` already; that
+ * is what the parameter type says.
+ */
+export const paramSpecToValidator = (spec, direction) => {
+    const shape = {};
+    for (const [name, field] of Object.entries(spec)) {
+        const check = checkFor(field.type, direction);
+        const required = field.required ?? direction === "delivery";
+        shape[name] = required ? check : check.optional();
+    }
+    return z.strictObject(shape);
+};

package/dist/primitives.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The vocabulary every other contract in this package is built from: a sum of
+ * money, a currency, a moment in time, an identifier.
+ *
+ * Two rules run through the file and are worth stating once.
+ *
+ * Money never travels as a floating point number. An amount is a decimal
+ * string, because 0.1 + 0.2 is not 0.3 in binary floating point and a price is
+ * a promise about someone else's money. A merchant who writes "5.00" gets
+ * "5.00" back, trailing zero and all, in the order and in the receipt.
+ *
+ * These schemas bound formats, not business policy. How long a title may be,
+ * how far away a deadline may sit, how stale a price may get — those numbers
+ * are named before the pilot and belong to the gateway. A number invented here
+ * would read as a decision that nobody took. Where a bound belongs to the
+ * format itself, it is written down together with the reason.
+ */
+import { z } from "zod";
+/**
+ * A decimal number written as text: digits, optionally a dot and more digits.
+ *
+ * Exponent notation, thousands separators and a leading plus are out, because
+ * the same money must always be the same string — a receipt compares badly
+ * when "5.00" and "5.0e0" both mean five dollars. Leading zeros go for the
+ * same reason. Negative amounts are out because nothing in this contract sells
+ * for less than nothing; a refund is a direction, not a sign on a price.
+ *
+ * The bounds are the format's own. Eighteen fractional digits is the most an
+ * ERC-20 token carries, so any stablecoin amount fits exactly; eighteen digits
+ * before the dot is past any price a catalog will hold. Beyond that a string
+ * of digits is not a price and refusing it early is cheaper than carrying it.
+ */
+export declare const AmountSchema: z.ZodString;
+/**
+ * A currency code, upper case.
+ *
+ * Three to eight characters, starting with a letter, digits allowed after it.
+ * A card is priced in one currency and settled in another and this contract
+ * does not yet say which of the two it carries, so the shape has to admit
+ * both: a national code is three letters (`USD`), and a token ticker is longer
+ * and sometimes carries a digit (`USDC`, `USD1`). Eight admits every ticker
+ * this contract has had to carry; which currencies are accepted is the
+ * gateway's to decide.
+ *
+ * What this does not do is check membership in any list. We hold no currency
+ * table, and a schema that pretended to would be claiming knowledge the
+ * package does not have. Which currencies the gateway accepts is a gateway
+ * question, and it is not answered here.
+ */
+export declare const CurrencyCodeSchema: z.ZodString;
+/** A sum of money: how much, in what. */
+export declare const MoneySchema: z.ZodObject<{
+    amount: z.ZodString;
+    currency: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A moment in time, ISO 8601, with its zone.
+ *
+ * The zone is not decoration. What arrives here is parsed into an instant and
+ * then kept — `as_of` travels into the order the merchant's handler is given
+ * and into the record of the sale, which is what somebody reconciles a charge
+ * against months later — and a local time with no offset is not an instant. It
+ * is an hour of the day, and two machines reading it would land on two
+ * different moments. Both an explicit offset and `Z` are accepted; what a
+ * merchant's clock reports is their business, as long as it names a point in
+ * time.
+ */
+export declare const TimestampSchema: z.ZodISODateTime;
+export declare const IdentifierSchema: z.ZodString;
+/**
+ * The price a purchase actually went through at.
+ *
+ * Four fields because the merchant's handler is meant to write the sale down
+ * without looking the card up: the sum and its currency, `at` — the moment this
+ * price was fixed for this sale, and `as_of` — the moment the price behind it
+ * was true. The two differ on purpose. A merchant whose answer lands at 10:15,
+ * out of a price list published at 10:00, sells at an `at` of 10:15 and an
+ * `as_of` of 10:00; a card with no price check is quoted off its own snapshot
+ * the instant the agent asks, so `at` is that instant and `as_of` is when the
+ * card's price was published.
+ *
+ * Neither of them is when the money moved, and a handler that read `at` as the
+ * charge would file the sale under the wrong minute. On a card with a price
+ * check the agent may take as long as it likes between the answer and the
+ * payment, and in the synchronous mode the charge executes after the goods. The
+ * moment of payment is on the receipt, as `paid_at`, and is not in this shape.
+ *
+ * A card sold from its own price and never checked live also carries `as_of`:
+ * the moment that card price was last published. That is a fact, not a guess,
+ * and it keeps the handler from having to treat a missing field as "fresh".
+ */
+export declare const SalePriceSchema: z.ZodObject<{
+    amount: z.ZodString;
+    currency: z.ZodString;
+    at: z.ZodISODateTime;
+    as_of: z.ZodISODateTime;
+}, z.core.$strict>;
+export type Amount = z.infer<typeof AmountSchema>;
+export type CurrencyCode = z.infer<typeof CurrencyCodeSchema>;
+export type Money = z.infer<typeof MoneySchema>;
+export type Timestamp = z.infer<typeof TimestampSchema>;
+export type Identifier = z.infer<typeof IdentifierSchema>;
+export type SalePrice = z.infer<typeof SalePriceSchema>;

package/dist/primitives.js

@@ -0,0 +1,130 @@
+/**
+ * The vocabulary every other contract in this package is built from: a sum of
+ * money, a currency, a moment in time, an identifier.
+ *
+ * Two rules run through the file and are worth stating once.
+ *
+ * Money never travels as a floating point number. An amount is a decimal
+ * string, because 0.1 + 0.2 is not 0.3 in binary floating point and a price is
+ * a promise about someone else's money. A merchant who writes "5.00" gets
+ * "5.00" back, trailing zero and all, in the order and in the receipt.
+ *
+ * These schemas bound formats, not business policy. How long a title may be,
+ * how far away a deadline may sit, how stale a price may get — those numbers
+ * are named before the pilot and belong to the gateway. A number invented here
+ * would read as a decision that nobody took. Where a bound belongs to the
+ * format itself, it is written down together with the reason.
+ */
+import { z } from "zod";
+/**
+ * A decimal number written as text: digits, optionally a dot and more digits.
+ *
+ * Exponent notation, thousands separators and a leading plus are out, because
+ * the same money must always be the same string — a receipt compares badly
+ * when "5.00" and "5.0e0" both mean five dollars. Leading zeros go for the
+ * same reason. Negative amounts are out because nothing in this contract sells
+ * for less than nothing; a refund is a direction, not a sign on a price.
+ *
+ * The bounds are the format's own. Eighteen fractional digits is the most an
+ * ERC-20 token carries, so any stablecoin amount fits exactly; eighteen digits
+ * before the dot is past any price a catalog will hold. Beyond that a string
+ * of digits is not a price and refusing it early is cheaper than carrying it.
+ */
+export const AmountSchema = z
+    .string()
+    .regex(/^(?:0|[1-9]\d{0,17})(?:\.\d{1,18})?$/, 'an amount is an exact decimal number written as text, such as "5.00"');
+/**
+ * A currency code, upper case.
+ *
+ * Three to eight characters, starting with a letter, digits allowed after it.
+ * A card is priced in one currency and settled in another and this contract
+ * does not yet say which of the two it carries, so the shape has to admit
+ * both: a national code is three letters (`USD`), and a token ticker is longer
+ * and sometimes carries a digit (`USDC`, `USD1`). Eight admits every ticker
+ * this contract has had to carry; which currencies are accepted is the
+ * gateway's to decide.
+ *
+ * What this does not do is check membership in any list. We hold no currency
+ * table, and a schema that pretended to would be claiming knowledge the
+ * package does not have. Which currencies the gateway accepts is a gateway
+ * question, and it is not answered here.
+ */
+export const CurrencyCodeSchema = z
+    .string()
+    .regex(/^[A-Z][A-Z0-9]{2,7}$/, 'a currency code is written in upper case, such as "USD"');
+/** A sum of money: how much, in what. */
+export const MoneySchema = z.strictObject({
+    amount: AmountSchema,
+    currency: CurrencyCodeSchema,
+});
+/**
+ * A moment in time, ISO 8601, with its zone.
+ *
+ * The zone is not decoration. What arrives here is parsed into an instant and
+ * then kept — `as_of` travels into the order the merchant's handler is given
+ * and into the record of the sale, which is what somebody reconciles a charge
+ * against months later — and a local time with no offset is not an instant. It
+ * is an hour of the day, and two machines reading it would land on two
+ * different moments. Both an explicit offset and `Z` are accepted; what a
+ * merchant's clock reports is their business, as long as it names a point in
+ * time.
+ */
+export const TimestampSchema = z.iso.datetime({ offset: true });
+/**
+ * An identifier — ours or the merchant's.
+ *
+ * Three things are asked of it, and each one is a way an identifier stops
+ * identifying. It cannot be blank, because a blank string is what a missing
+ * value turns into on its way through a template and an order keyed by "" is
+ * an order nobody finds again. It cannot begin or end with whitespace: a
+ * merchant's key is what republishing a card matches on, and
+ * `"access-monthly "` would look identical to `"access-monthly"` in every log
+ * and every screen while quietly creating the second card the portal promises
+ * cannot appear. And it carries no control characters, which nothing means to
+ * type and which make a key unreadable wherever it is printed.
+ *
+ * The shape beyond that is deliberately left alone: the merchant's own key is
+ * theirs and our own key formats are ours to change. So is the length. A
+ * ceiling would be a policy number, and the numbers of this contract are named
+ * before the pilot rather than invented here; until then the bound on an
+ * identifier is whatever the transport carrying it allows.
+ */
+const UNPRINTABLE = "\\u0000-\\u001f\\u007f\\u200b-\\u200f\\u2060-\\u2064\\ufeff";
+export const IdentifierSchema = z.string().regex(
+// One pattern, not three checks, because a rule written as a refinement is
+// dropped from the JSON Schema export without a word — the defect this
+// package has already paid for twice. As a pattern it crosses intact, and a
+// generated client refuses the same keys we do.
+//
+// It reads: a first character that is neither whitespace nor unprintable,
+// then anything printable, then a last character under the same rule as the
+// first. One character on its own is allowed; nothing at all is not.
+new RegExp(`^[^\\s${UNPRINTABLE}](?:[^${UNPRINTABLE}]*[^\\s${UNPRINTABLE}])?$`, "u"), "an identifier must not be empty, padded with whitespace, or carry characters that show nothing");
+/**
+ * The price a purchase actually went through at.
+ *
+ * Four fields because the merchant's handler is meant to write the sale down
+ * without looking the card up: the sum and its currency, `at` — the moment this
+ * price was fixed for this sale, and `as_of` — the moment the price behind it
+ * was true. The two differ on purpose. A merchant whose answer lands at 10:15,
+ * out of a price list published at 10:00, sells at an `at` of 10:15 and an
+ * `as_of` of 10:00; a card with no price check is quoted off its own snapshot
+ * the instant the agent asks, so `at` is that instant and `as_of` is when the
+ * card's price was published.
+ *
+ * Neither of them is when the money moved, and a handler that read `at` as the
+ * charge would file the sale under the wrong minute. On a card with a price
+ * check the agent may take as long as it likes between the answer and the
+ * payment, and in the synchronous mode the charge executes after the goods. The
+ * moment of payment is on the receipt, as `paid_at`, and is not in this shape.
+ *
+ * A card sold from its own price and never checked live also carries `as_of`:
+ * the moment that card price was last published. That is a fact, not a guess,
+ * and it keeps the handler from having to treat a missing field as "fresh".
+ */
+export const SalePriceSchema = z.strictObject({
+    amount: AmountSchema,
+    currency: CurrencyCodeSchema,
+    at: TimestampSchema,
+    as_of: TimestampSchema,
+});