@nuanu-ai/agentify-contracts 0.5.0 → 0.7.0

package/dist/merchant.js

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

package/dist/plain-text.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Plain text: what the words on a card are written in.
+ *
+ * A card's title, its description and the title of each field it declares are
+ * read by a buying program exactly as they were written. Nothing between the
+ * merchant and the agent renders HTML, so markup reaches the agent as markup —
+ * `<p>Valid for twelve months.</p>` is read with its angle brackets, and
+ * `Coffee &#038; Brunch` with its number — and a discovery catalog that does
+ * render HTML would swallow some of it and show the rest. Either way the words
+ * an agent acts on are not the words the merchant meant.
+ *
+ * The door refuses such text rather than cleaning it, and that choice is the
+ * whole of this file. Cleaning would make an agent read text the merchant never
+ * wrote: stripping a tag can join two sentences, decoding a reference is a
+ * guess about which table it came from, and dropping an invisible character
+ * changes a string somebody may be matching on. And the merchant would never
+ * learn that their text was being rewritten, so the source stays broken for
+ * every other place it goes. A refusal that names what it found and where is
+ * the version of this a merchant can act on. A shop connector whose source is
+ * HTML turns it into text on its own side, before the door, and asks this same
+ * rule whether it succeeded.
+ *
+ * What is refused is what reads as markup or as a reference, and nothing that
+ * merely shares a character with them. An ampersand between words, a
+ * comparison and an arrow are text: `Tea & coffee`, `5 < 10`, `a -> b`, `AT&T`
+ * and `R&D;` all pass, and so does a space after a bracket, `List< String >`,
+ * which an HTML parser reads as text too.
+ *
+ * Three more shapes pass, and for them the rule is a choice rather than a fact
+ * about HTML: an address in angle brackets, `<jane@example.com>` or
+ * `<https://example.com>`, a bracket that is never closed, `x<y`, and a
+ * bracket before a name HTML would not give an element, `Map<String, Integer>`.
+ * A browser would swallow each of them as a tag, or drop it. They pass because
+ * each is how plain text has always been written, the rule is about text
+ * written as HTML rather than about everything a renderer might misread, and
+ * no reader between the merchant and an agent renders HTML.
+ *
+ * The rule is the publish door's and not the reader's. A card stored before it
+ * may carry anything it refuses, and every answer that carries a stored card is
+ * held to its contract on the way out — so a rule applied on reading would turn
+ * one old row into a failed catalog for every agent and a merchant who cannot
+ * see the card they are meant to fix.
+ */
+/**
+ * Whether a piece of text is one line, as a title is, or may run to several, as
+ * a description may.
+ */
+export type TextLines = "one line" | "several lines";
+/**
+ * What in this text is not plain text, one phrase for each kind of thing found
+ * — markup, character references, control characters — and nothing when all of
+ * it is.
+ *
+ * Each phrase says what was found, how often, and where the first of it is, as
+ * in `HTML markup in 4 places, the first "<p>" at character 1`, and quotes
+ * nothing it would have to print as a control character. It is the one
+ * definition of plain text: the publish door refuses a card with it, and a
+ * connector that turns a shop's HTML into text asks it whether it succeeded.
+ */
+export declare const notPlainTextIn: (text: string, lines: TextLines) => readonly string[];

package/dist/plain-text.js

@@ -0,0 +1,191 @@
+/**
+ * Plain text: what the words on a card are written in.
+ *
+ * A card's title, its description and the title of each field it declares are
+ * read by a buying program exactly as they were written. Nothing between the
+ * merchant and the agent renders HTML, so markup reaches the agent as markup —
+ * `<p>Valid for twelve months.</p>` is read with its angle brackets, and
+ * `Coffee &#038; Brunch` with its number — and a discovery catalog that does
+ * render HTML would swallow some of it and show the rest. Either way the words
+ * an agent acts on are not the words the merchant meant.
+ *
+ * The door refuses such text rather than cleaning it, and that choice is the
+ * whole of this file. Cleaning would make an agent read text the merchant never
+ * wrote: stripping a tag can join two sentences, decoding a reference is a
+ * guess about which table it came from, and dropping an invisible character
+ * changes a string somebody may be matching on. And the merchant would never
+ * learn that their text was being rewritten, so the source stays broken for
+ * every other place it goes. A refusal that names what it found and where is
+ * the version of this a merchant can act on. A shop connector whose source is
+ * HTML turns it into text on its own side, before the door, and asks this same
+ * rule whether it succeeded.
+ *
+ * What is refused is what reads as markup or as a reference, and nothing that
+ * merely shares a character with them. An ampersand between words, a
+ * comparison and an arrow are text: `Tea & coffee`, `5 < 10`, `a -> b`, `AT&T`
+ * and `R&D;` all pass, and so does a space after a bracket, `List< String >`,
+ * which an HTML parser reads as text too.
+ *
+ * Three more shapes pass, and for them the rule is a choice rather than a fact
+ * about HTML: an address in angle brackets, `<jane@example.com>` or
+ * `<https://example.com>`, a bracket that is never closed, `x<y`, and a
+ * bracket before a name HTML would not give an element, `Map<String, Integer>`.
+ * A browser would swallow each of them as a tag, or drop it. They pass because
+ * each is how plain text has always been written, the rule is about text
+ * written as HTML rather than about everything a renderer might misread, and
+ * no reader between the merchant and an agent renders HTML.
+ *
+ * The rule is the publish door's and not the reader's. A card stored before it
+ * may carry anything it refuses, and every answer that carries a stored card is
+ * held to its contract on the way out — so a rule applied on reading would turn
+ * one old row into a failed catalog for every agent and a merchant who cannot
+ * see the card they are meant to fix.
+ */
+/**
+ * Markup: an HTML comment's opening, or a tag.
+ *
+ * A comment is refused on its opening alone, because nobody writing prose
+ * writes `<!--`, and matching on to the close would cost a scan to the end of
+ * the text for every opening in it.
+ *
+ * A tag is an angle bracket, an optional slash, a name, and then the bracket's
+ * close — at once, after a slash, or after whitespace and whatever attributes
+ * follow. The name begins with a letter and carries letters and digits, joined
+ * by a colon or a hyphen where there is one, which is how `<o:p>`, the tag a
+ * word processor leaves in pasted text, and a custom element are written. An
+ * attribute value in quotation marks may carry either bracket, as the alt text
+ * a block editor writes into an image does: `<img alt="Mug <3 coffee">` is one
+ * tag. A quotation mark that opens no value — the apostrophe in
+ * `<img alt=Mom's>`, or `<your friend's name>` — does not hide its tag either:
+ * where the tag cannot be read with its quotation marks paired, it is read to
+ * the first closing bracket, as it was before quoted values were known. What
+ * the name does not take is the rest of what can follow a bracket —
+ * a digit, a space, an `@`, a `:/` — which is why `<3`, `List< String >` and
+ * `<https://example.com>` are not tags here. The close has to be there, so
+ * `x<y` is not one either.
+ *
+ * The scan is linear in the length of the text however it is written: outside
+ * quotation marks everything stops at the next angle bracket, a quoted value
+ * stops at its own closing mark, and a quotation mark can be read only one
+ * way at any point, so no stretch of text is read over and over from one
+ * bracket. The tests hold it at a quarter of a megabyte, which is more than a
+ * publish body may carry, and on the short inputs that turn exponential the
+ * moment a quotation mark may be read two ways.
+ */
+const MARKUP = /<!--|<\/?[A-Za-z][A-Za-z0-9]*(?:[:-][A-Za-z0-9]+)*(?:(?:[\t\n\f\r /](?:[^<>"']|"[^"]*"|'[^']*')*)?>|[\t\n\f\r /][^<>]*>)/g;
+/**
+ * A character reference: an ampersand, a number or a name, and a semicolon.
+ *
+ * The semicolon, and a name of at least two characters, are what separate a
+ * reference from an ampersand in prose. HTML has no name of one letter, so
+ * `AT&T`, `A&B` and `R&D;` are text. A name of two or more is refused whether
+ * or not HTML's own list carries it: `&eacute;` and `&foo;` are both text
+ * written for an HTML reader, and a merchant who meant a character writes the
+ * character.
+ */
+const REFERENCE = /&(?:#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]+);/g;
+/**
+ * Control characters: C0, DEL and C1. A description may carry a line feed,
+ * U+000A, and nothing else from this range.
+ *
+ * A line feed is the one line break every reader agrees on, and a description
+ * is prose of up to five hundred characters that may run to paragraphs. A
+ * carriage return is refused there with the rest, because `\r\n` is a second
+ * spelling of the same break and a carriage return on its own sends a terminal
+ * back to the start of the line it is printing. A title and a field's title are
+ * one line, so they carry no line break at all. The rest of the range shows
+ * nothing, and a character that shows nothing makes two strings that look
+ * identical and are not.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+const CONTROL_IN_ONE_LINE = /[\u0000-\u001F\u007F-\u009F]/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+const CONTROL_IN_LINES = /[\u0000-\u0009\u000B-\u001F\u007F-\u009F]/g;
+/**
+ * The names a merchant knows the commonest control characters by, in text of
+ * each shape.
+ *
+ * A carriage return in a description is nearly always half of the `\r\n` a
+ * form on Windows submits between two lines, so there it is named together
+ * with the one line break a description does take.
+ */
+const CONTROL_NAMES = {
+    "one line": { "\t": "a tab", "\n": "a line break", "\r": "a carriage return" },
+    "several lines": {
+        "\t": "a tab",
+        "\r": "a carriage return; a description breaks its lines with a line feed, U+000A, alone",
+    },
+};
+/**
+ * The longest piece of the text quoted back in a finding.
+ *
+ * A tag can carry an address of any length, and a finding is a line a person
+ * reads; forty characters is enough to recognise the tag by. Where one is cut,
+ * the finding says so.
+ */
+const QUOTED_AT_MOST = 40;
+/** A character by its code point, as `U+0007`. */
+const codeOf = (character) => `U+${(character.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0")}`;
+/**
+ * DEL and C1, which a quotation leaves as they are.
+ *
+ * `JSON.stringify` escapes C0 and a lone surrogate and nothing else, so a
+ * control character inside a quoted tag would otherwise reach the merchant's
+ * terminal as itself — and U+009B is the start of an escape sequence there.
+ */
+const UNESCAPED_BY_JSON = /[\u007F-\u009F]/g;
+/**
+ * A piece of the text as a finding quotes it: in quotation marks, with every
+ * control character escaped, and cut where it is long.
+ *
+ * The cut is made between two characters and never inside one: a character
+ * outside the basic plane is two units long, and a cut through the middle of
+ * it would quote half a character as an escape nobody wrote.
+ */
+const quoted = (fragment) => {
+    const whole = fragment.length <= QUOTED_AT_MOST;
+    const head = whole ? fragment : fragment.slice(0, QUOTED_AT_MOST).replace(/[\uD800-\uDBFF]$/, "");
+    const shown = JSON.stringify(head).replace(UNESCAPED_BY_JSON, (character) => `\\u${(character.codePointAt(0) ?? 0).toString(16).padStart(4, "0")}`);
+    return whole ? shown : `${shown}… (cut short)`;
+};
+/** A control character as a finding names it: by its code, never printed. */
+const namedIn = (lines) => (character) => {
+    const name = CONTROL_NAMES[lines][character];
+    return name === undefined ? codeOf(character) : `${codeOf(character)} (${name})`;
+};
+/**
+ * One kind of thing that is not plain text, said once for all the places it
+ * occurs: how many there are, and the first of them, where it is.
+ *
+ * The position counts from one, in the same units a description's length is
+ * counted in: UTF-16 code units, so a character outside the basic plane — an
+ * emoji — counts as two, and the number can run ahead of what an editor shows
+ * by one for each such character before it. It is the same count in both
+ * places, which is what lets a merchant set one number against the other.
+ */
+const found = (text, pattern, one, many, shown) => {
+    const matches = [...text.matchAll(pattern)];
+    const first = matches[0];
+    if (first === undefined)
+        return null;
+    const where = `${shown(first[0])} at character ${first.index + 1}`;
+    return matches.length === 1
+        ? `${one}, ${where}`
+        : `${many} in ${matches.length} places, the first ${where}`;
+};
+/**
+ * What in this text is not plain text, one phrase for each kind of thing found
+ * — markup, character references, control characters — and nothing when all of
+ * it is.
+ *
+ * Each phrase says what was found, how often, and where the first of it is, as
+ * in `HTML markup in 4 places, the first "<p>" at character 1`, and quotes
+ * nothing it would have to print as a control character. It is the one
+ * definition of plain text: the publish door refuses a card with it, and a
+ * connector that turns a shop's HTML into text asks it whether it succeeded.
+ */
+export const notPlainTextIn = (text, lines) => [
+    found(text, MARKUP, "HTML markup", "HTML markup", quoted),
+    found(text, REFERENCE, "an HTML character reference", "HTML character references", quoted),
+    found(text, lines === "one line" ? CONTROL_IN_ONE_LINE : CONTROL_IN_LINES, "a control character", "control characters", namedIn(lines)),
+].filter((phrase) => phrase !== null);

package/dist/price-rule.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a price a merchant sets has to be before Agentify will sell at it.
+ *
+ * A price comes in by two doors: on a card, when it is published, and in the
+ * answer to a price question, when a purchase is priced live. The gateway holds
+ * both to the rule below, and the merchant SDK's own check of a card holds it
+ * to the same rule, so a card the check passes is not refused at publication
+ * for its price. Three parts, each standing for a payment that cannot be
+ * taken.
+ *
+ * A price of zero is refused, by design. A payment request for nothing asks
+ * for something that cannot be done, and a gateway that took free items would
+ * be hosting content rather than selling it. A merchant gives a free item away
+ * from their own site, with no payment request in front of it (ADR-0002 §2).
+ *
+ * A currency other than the dollar is refused, because there is no exchange
+ * rate anywhere in this system to charge it at.
+ *
+ * An amount is written in dollars with at least two digits after the dot, so
+ * that a merchant who counts in cents and writes "500" for five dollars is
+ * refused rather than listed at five hundred. Fractions of a cent stay allowed,
+ * because a price per call is often below one, down to the finest amount the
+ * token a buyer pays in can carry and no further: past that there is no exact
+ * amount to charge, and a rounded charge is a different charge.
+ *
+ * So a price the door took is a price the payment edge can charge. The edge
+ * reads the currencies from here, and the places its token carries on every
+ * chain it can charge on are held equal to `PAYABLE_DECIMALS` by a test beside
+ * it, so the door and the edge cannot become two answers.
+ *
+ * It is a rule applied at the doors rather than part of any schema, and that is
+ * the point of it being a function. The schemas also read back every document
+ * already written — every answer that carries a card is held to the contract
+ * on its way out — so a rule written into the card's schema would turn the
+ * whole list of a merchant who published such a price before the rule existed
+ * into a failure, for cards they could otherwise see, pause and replace.
+ */
+import type { Money } from "./primitives.js";
+import type { Problem } from "./results.js";
+/**
+ * The currencies a price may be written in, and the one conversion Agentify
+ * makes.
+ *
+ * A card priced in dollars is charged in the network's own dollar-denominated
+ * asset, one for one. That is a decision and not the absence of one, so it is
+ * written here rather than left to be inferred from the fact that it works: a
+ * merchant who writes "USD" is charging their buyer USDC on the configured
+ * chain, and the two are held to be the same number of dollars.
+ *
+ * Everything else is refused. Nobody has decided where an exchange rate would
+ * come from, and a charge based on an invented one would be the clearest
+ * possible claim beyond the evidence.
+ */
+export declare const PAYABLE_CURRENCIES: readonly string[];
+/**
+ * How many places after the dot a price may carry: the places of USDC, which is
+ * what a buyer pays in. Its smallest unit is a millionth of a dollar, so
+ * "0.000001" is the finest price there is an exact charge for.
+ */
+export declare const PAYABLE_DECIMALS = 6;
+/**
+ * What stands between this price and a sale, as findings on the fields of the
+ * document that carried it — empty where nothing does.
+ *
+ * The paths name `price` because a card and a price answer both carry the
+ * price under that name, so one finding reads right in either. An amount gets
+ * at most one finding: zero is said before the places, because "0" written as
+ * "0.00" would only be refused again.
+ *
+ * The amount has already passed `AmountSchema`, so it is digits with at most
+ * one dot, and the places are what follows the dot.
+ */
+export declare function priceProblemsOf(price: Money): Problem[];

package/dist/price-rule.js

@@ -0,0 +1,104 @@
+/**
+ * What a price a merchant sets has to be before Agentify will sell at it.
+ *
+ * A price comes in by two doors: on a card, when it is published, and in the
+ * answer to a price question, when a purchase is priced live. The gateway holds
+ * both to the rule below, and the merchant SDK's own check of a card holds it
+ * to the same rule, so a card the check passes is not refused at publication
+ * for its price. Three parts, each standing for a payment that cannot be
+ * taken.
+ *
+ * A price of zero is refused, by design. A payment request for nothing asks
+ * for something that cannot be done, and a gateway that took free items would
+ * be hosting content rather than selling it. A merchant gives a free item away
+ * from their own site, with no payment request in front of it (ADR-0002 §2).
+ *
+ * A currency other than the dollar is refused, because there is no exchange
+ * rate anywhere in this system to charge it at.
+ *
+ * An amount is written in dollars with at least two digits after the dot, so
+ * that a merchant who counts in cents and writes "500" for five dollars is
+ * refused rather than listed at five hundred. Fractions of a cent stay allowed,
+ * because a price per call is often below one, down to the finest amount the
+ * token a buyer pays in can carry and no further: past that there is no exact
+ * amount to charge, and a rounded charge is a different charge.
+ *
+ * So a price the door took is a price the payment edge can charge. The edge
+ * reads the currencies from here, and the places its token carries on every
+ * chain it can charge on are held equal to `PAYABLE_DECIMALS` by a test beside
+ * it, so the door and the edge cannot become two answers.
+ *
+ * It is a rule applied at the doors rather than part of any schema, and that is
+ * the point of it being a function. The schemas also read back every document
+ * already written — every answer that carries a card is held to the contract
+ * on its way out — so a rule written into the card's schema would turn the
+ * whole list of a merchant who published such a price before the rule existed
+ * into a failure, for cards they could otherwise see, pause and replace.
+ */
+/**
+ * The currencies a price may be written in, and the one conversion Agentify
+ * makes.
+ *
+ * A card priced in dollars is charged in the network's own dollar-denominated
+ * asset, one for one. That is a decision and not the absence of one, so it is
+ * written here rather than left to be inferred from the fact that it works: a
+ * merchant who writes "USD" is charging their buyer USDC on the configured
+ * chain, and the two are held to be the same number of dollars.
+ *
+ * Everything else is refused. Nobody has decided where an exchange rate would
+ * come from, and a charge based on an invented one would be the clearest
+ * possible claim beyond the evidence.
+ */
+export const PAYABLE_CURRENCIES = Object.freeze(["USD", "USDC"]);
+/**
+ * How many places after the dot a price may carry: the places of USDC, which is
+ * what a buyer pays in. Its smallest unit is a millionth of a dollar, so
+ * "0.000001" is the finest price there is an exact charge for.
+ */
+export const PAYABLE_DECIMALS = 6;
+/**
+ * What stands between this price and a sale, as findings on the fields of the
+ * document that carried it — empty where nothing does.
+ *
+ * The paths name `price` because a card and a price answer both carry the
+ * price under that name, so one finding reads right in either. An amount gets
+ * at most one finding: zero is said before the places, because "0" written as
+ * "0.00" would only be refused again.
+ *
+ * The amount has already passed `AmountSchema`, so it is digits with at most
+ * one dot, and the places are what follows the dot.
+ */
+export function priceProblemsOf(price) {
+    const problems = [];
+    const written = JSON.stringify(price.amount);
+    const places = price.amount.split(".")[1]?.length ?? 0;
+    if (!/[1-9]/.test(price.amount)) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and nothing is sold through Agentify at a price of zero: a free item is offered from your own site, without a payment`,
+        });
+    }
+    else if (places < 2) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and a price is written in dollars with at least two digits after the dot — five dollars is "5.00" — so that an amount counted in cents is never charged as dollars`,
+        });
+    }
+    else if (places > PAYABLE_DECIMALS) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and a price carries at most ${PAYABLE_DECIMALS} digits after the dot, the finest amount USDC can be paid in, so there is no exact amount to charge for it`,
+        });
+    }
+    if (!PAYABLE_CURRENCIES.includes(price.currency)) {
+        problems.push({
+            path: ["price", "currency"],
+            code: "custom",
+            message: `the price is in ${JSON.stringify(price.currency)}, which Agentify cannot charge: it takes USD, paid as USDC one for one, or USDC itself, and holds no exchange rate to anything else`,
+        });
+    }
+    return problems;
+}