@nuanu-ai/agentify-contracts 0.5.0 → 0.7.0

package/dist/primitives.d.ts

@@ -39,13 +39,13 @@ export declare const AmountSchema: z.ZodString;
  * 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.
+ * this contract has had to carry.
  *
- * 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.
+ * What this does not do is check membership in any list. Which currencies a
+ * merchant may set a price in is answered once, by the price rule in
+ * `price-rule.ts`, at the moment a price comes in. This shape also reads back
+ * every document already written, and a list here would make one written
+ * before the list changed unreadable.
  */
 export declare const CurrencyCodeSchema: z.ZodString;
 /** A sum of money: how much, in what. */
@@ -67,6 +67,18 @@ export declare const MoneySchema: z.ZodObject<{
  */
 export declare const TimestampSchema: z.ZodISODateTime;
 export declare const IdentifierSchema: z.ZodString;
+/**
+ * A word of a vocabulary that grows without a version (ADR-0006 §5): a mode
+ * on the card an agent reads, a status on its order.
+ *
+ * The storefront has no version, so a word added later reaches agents that
+ * still hold this contract, and they read it rather than refuse the document.
+ * Open is not anything at all, though: a word is read by a program and shown
+ * to a person, so it has the shape every word in those lists already has —
+ * lower-case letters, digits and underscores, starting with a letter — and
+ * markup, padding or a page of text is not one.
+ */
+export declare const OpenWordSchema: z.ZodString;
 /**
  * The price a purchase actually went through at.
  *
@@ -100,4 +112,5 @@ 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 OpenWord = z.infer<typeof OpenWordSchema>;
 export type SalePrice = z.infer<typeof SalePriceSchema>;

package/dist/primitives.js

@@ -41,13 +41,13 @@ export const AmountSchema = z
  * 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.
+ * this contract has had to carry.
  *
- * 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.
+ * What this does not do is check membership in any list. Which currencies a
+ * merchant may set a price in is answered once, by the price rule in
+ * `price-rule.ts`, at the moment a price comes in. This shape also reads back
+ * every document already written, and a list here would make one written
+ * before the list changed unreadable.
  */
 export const CurrencyCodeSchema = z
     .string()
@@ -100,6 +100,20 @@ export const IdentifierSchema = z.string().regex(
 // 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");
+/**
+ * A word of a vocabulary that grows without a version (ADR-0006 §5): a mode
+ * on the card an agent reads, a status on its order.
+ *
+ * The storefront has no version, so a word added later reaches agents that
+ * still hold this contract, and they read it rather than refuse the document.
+ * Open is not anything at all, though: a word is read by a program and shown
+ * to a person, so it has the shape every word in those lists already has —
+ * lower-case letters, digits and underscores, starting with a letter — and
+ * markup, padding or a page of text is not one.
+ */
+export const OpenWordSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{0,63}$/, "a word of this vocabulary is lower-case letters, digits and underscores, starts with a letter and is at most sixty-four characters long");
 /**
  * The price a purchase actually went through at.
  *

package/dist/quote.js

@@ -82,7 +82,9 @@ export const QuoteRequestSchema = z.strictObject({
 export const QuoteResponseSchema = z.discriminatedUnion("available", [
     z.strictObject({
         available: z.literal(true),
-        price: MoneySchema,
+        price: MoneySchema.meta({
+            description: 'Held to the rule a card\'s price meets at publication: above zero, in USD or USDC, with two to six digits after the dot ("5.00", "0.001"); an answer that breaks it is refused and prices nothing.',
+        }),
         as_of: TimestampSchema,
     }),
     z.strictObject({

package/dist/results.d.ts

@@ -102,9 +102,10 @@ export declare const OrderCallResultSchema: z.ZodEnum<{
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
@@ -203,7 +204,7 @@ export declare const CARD_REJECTED = "card_rejected";
  * merchant has no name set for buyers to read, no wallet set for their sales to
  * be paid into, or no approval from the operator for the live catalog. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment

package/dist/results.js

@@ -103,9 +103,10 @@ export const OrderCallResultSchema = z.enum(ORDER_CALL_RESULTS);
  * merchant in its own words rather than be flattened into the nearest of
  * three. `refund_already_settled` — the debt was paid back, so there is
  * nothing left to deliver against. `order_already_closed` — the order reached
- * an ending that no call reopens. `not_applicable_in_mode` — the call does not
- * exist for this card's mode, as refusing separately does not in the
- * synchronous one, where the handler's own answer is the refusal.
+ * an ending that no call reopens. `not_applicable_in_mode` — the call or the
+ * answer does not exist for this card's mode, as delivering or refusing
+ * separately and taking the order on do not in the synchronous one, where the
+ * handler's own answer is the delivery or the refusal.
  * `delivery_does_not_match_card` — the goods are not the ones the card for
  * this order declares it delivers, so nothing was written down; the message
  * says whether the order still stands or has already ended, and the fields
@@ -211,7 +212,7 @@ export const CallErrorSchema = z.strictObject({
     code: z.string().regex(/\S/, "an error carries a code").meta({
         // Same reason as the refusal code: the dictionary travels with the field
         // or it does not reach the reader the export exists for.
-        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call does not exist for this card\'s mode — refusing separately does not, in the synchronous one, where the handler\'s own answer is the refusal). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
+        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call or the answer does not exist for this card\'s mode — in the synchronous one the handler\'s own answer is the delivery or the refusal, so delivering or refusing separately does not exist there, and neither does taking an order on while it waits for its goods, which promises them later through a call that mode does not have). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
     }),
     message: z.string().regex(/\S/, "an error carries an explanation a person can read"),
     retryable: z.boolean(),
@@ -247,7 +248,7 @@ export const CARD_REJECTED = "card_rejected";
  * merchant has no name set for buyers to read, no wallet set for their sales to
  * be paid into, or no approval from the operator for the live catalog. The
  * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
- * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * the dashboard; the wallet in the dashboard's Settings alone, since no key of the
  * merchant's code may say where the money goes; and the approval is the
  * operator's decision, with no call. The name is asked for everywhere, the
  * wallet wherever a payment settles and the approval on the live deployment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify-contracts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "The Agentify wire contract as code: the schemas for cards, orders, price checks and receipts that the gateway and the merchant SDK both read.",
   "keywords": [