@nuanu-ai/agentify 0.5.0 → 0.5.1

package/dist/transport.js

@@ -1,65 +1,25 @@
 /**
- * Making one call of the surface.
+ * Making one call of the surface. Every address, method and answer document
+ * comes from the route table in `@nuanu-ai/agentify-contracts`, and the key's
+ * header is built by `merchantKeyHeaderValue` from the same package, so this
+ * package writes down no path and no header of its own.
  *
- * Every address, method and answer document comes out of the route table in
- * `@nuanu-ai/agentify-contracts`. No path is written down in this package, and the
- * table's own `expandPath` does the substituting, because an identifier we
- * accept may hold a slash or a space and pasted into an address unencoded it
- * becomes two segments and a different route.
+ * The answer is read the same way whatever its HTTP status: the route's
+ * document if it is one, otherwise the gateway's error envelope if it is one,
+ * and only otherwise a failure this package describes itself, with the status.
  *
- * The table deliberately leaves out three things that a program actually
- * making the calls cannot avoid deciding, and it is worth saying here what was
- * decided, because each of them is a place where the two sides can disagree
- * without either of them noticing.
- *
- * The first is the header the merchant's key travels in. The table says which
- * door a call is behind and not how the door is built, so the choice is the
- * gateway's and ours to match — and matching it by each writing the same two
- * strings down was agreement by luck, where a call behind that door fails with
- * an authorisation error and nothing in either repository says why. So the name
- * and the scheme live in `@nuanu-ai/agentify-contracts`, in the one place both sides
- * already import: `merchantKeyHeaderValue` builds the value this package sends,
- * and `merchantKeyFrom` is what the gateway reads it back with.
- *
- * The second is the status code, about which the table says nothing either.
- * Some of the answers this surface gives are refusals that are still documents
- * — a card that was not accepted, an order call that did not go through — and
- * rather than guess which of those arrive under a 200 and which under a 400,
- * the answer is read the same way whatever the status. If the body is the
- * document the route names, that is the answer. Otherwise it is asked whether
- * it is the one envelope every route refuses in, and if it is, what the caller
- * is told is the gateway's own code and its own sentence rather than a
- * complaint from here about a document that did not parse — the gateway is the
- * side that knows why, and the reason it wrote is the only thing the caller
- * can act on. Only a body that is neither is a failure this package has to
- * describe itself, and then the status is part of what it says.
- *
- * The third is what a failure is at all. Nothing here throws: a call comes
- * back either as the document or as a failure carrying a sentence and, where
- * there was one, the body that could not be read. The layer above decides
- * which of those the merchant is entitled to see as a return value and which
- * is an exception, and that decision is in `client.ts`, where the contract
- * says which calls have a failure branch of their own. The body travels with
- * the failure because one caller needs it: a poll answer this SDK cannot parse
- * may still name the contract version the gateway speaks, and that is how a
- * genuine difference of dialects is told apart from a broken gateway.
+ * Nothing here throws. A call comes back as the document or as a failure;
+ * `client.ts` decides which failures a merchant sees returned and which
+ * thrown. The body travels with a failure because a poll answer this SDK
+ * cannot parse may still name the gateway's contract version.
  */
 import { API_ROUTES, ErrorEnvelopeSchema, expandPath, MERCHANT_KEY_HEADER, merchantKeyHeaderValue, } from "@nuanu-ai/agentify-contracts";
 /**
- * What is known about whether the call got there.
- *
- * Three and not two, and the third is the one that matters. A first draft had
- * a boolean, which meant every failure that was not an answer was filed as
- * "it did not reach us" — including a request that was fully sent and then
- * abandoned when the worker stopped, or one whose connection broke after the
- * gateway had it. Those are not the same fact, and a merchant reconciling
- * their books from the wrong one of them is reconciling from something we made
- * up.
- *
- * `not_received` is claimed only where the network says so plainly: the
- * connection was refused or the name did not resolve, so nothing was ever
- * handed over. Everything else that produced no readable answer is `unknown`,
- * because it is.
+ * What is known about whether the call got there. `not_received` is claimed
+ * only where the network says plainly that nothing was handed over: the
+ * connection was refused or the name did not resolve. Everything else without
+ * a readable answer is `unknown`, so that a merchant never reconciles their
+ * books from something this package made up.
  */
 export const REACH = Object.freeze({
     /** No connection was made, so the gateway certainly has nothing. */
@@ -67,31 +27,23 @@ export const REACH = Object.freeze({
     /** The gateway answered, and the answer is not one this package can read. */
     ANSWERED: "answered",
     /**
-     * The exchange was cut short. What the call did is not known here.
-     *
-     * Deliberately silent about direction, because three different things end
-     * up here and they do not agree about it: an abort that may have fired
-     * before the request left, a connection that broke once it was under way,
-     * and an answer that started arriving and stopped. What they share is that
-     * no complete answer was had, and that is all this may be read as saying.
+     * The exchange was cut short, and what the call did is not known here. It
+     * says nothing about direction: an abort may have fired before the request
+     * left, a connection may have broken under way, or an answer may have
+     * stopped arriving.
      */
     UNKNOWN: "unknown",
 });
 /**
- * The three codes the network gives us that mean nothing was handed over.
- *
- * Kept short on purpose: every code not on this list is read as "unknown",
- * which is the answer that claims least. A code added here is a claim that the
- * request certainly never arrived, and it should be added only when that is
- * true of it.
+ * The network codes that mean nothing was handed over. Every other code reads
+ * as unknown, so add one here only if it certainly means the request never
+ * arrived.
  */
 const NOTHING_WAS_SENT = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN"]);
 /**
- * The network's own codes for why a call failed, however many there were.
- *
- * There can be several: a name that resolves to more than one address is tried
- * at each of them, and what comes back is one error holding the others. All of
- * them have to say nothing was sent before we say it.
+ * The network's own codes for why a call failed. A name that resolves to
+ * several addresses is tried at each and fails with one error holding the
+ * others, so there can be several.
  */
 const codesUnder = (cause) => {
     const inner = cause?.cause;
@@ -105,12 +57,9 @@ const codesUnder = (cause) => {
     return typeof code === "string" ? [code] : [];
 };
 /**
- * What a failed `fetch` says about whether anything was handed over.
- *
- * Exported for its own test rather than only through a socket: the rule that
- * every address tried has to say nothing was sent — not merely one of them —
- * is not reachable from a test that can only produce one address at a time,
- * and a rule nothing checks is a rule that will be relaxed by accident.
+ * What a failed `fetch` says about whether anything was handed over: nothing,
+ * only where every address tried says so. Exported for its own test, which
+ * can produce several addresses where a socket test cannot.
  */
 export const reachOf = (cause) => {
     const codes = codesUnder(cause);
@@ -119,13 +68,9 @@ export const reachOf = (cause) => {
         : REACH.UNKNOWN;
 };
 /**
- * How much of an answer we could not read is quoted back in the failure.
- *
- * A quote is worth more than a length — an HTML error page from a proxy names
- * the thing that is actually broken — and a whole one is worth less than
- * nothing, because a gateway can answer with a megabyte and this text ends up
- * in a merchant's log. What is cut is said in the same sentence rather than
- * left as an ellipsis a reader has to interpret.
+ * How much of an unreadable answer is quoted back in the failure. A proxy's
+ * error page often names what is broken, but a whole one can be a megabyte in
+ * a merchant's log; what is cut is said in the same sentence.
  */
 const QUOTED_CHARACTERS = 200;
 const quote = (text) => text.length <= QUOTED_CHARACTERS
@@ -144,36 +89,18 @@ const failure = (route, reason, reach, body, refusal) => ({
     },
 });
 /**
- * What is known about a failed call, in a clause that can be dropped into a
- * sentence about whatever the call was carrying.
- *
- * It lives here rather than in each caller so that the four cases are
- * described in one place and cannot drift into four different vocabularies.
- * Three of them are the reaches; the fourth is a refusal the gateway wrote in
- * words we recognise, which is the one failure here that is not a silence and
- * so does not belong to any of them.
+ * What is known about a failed call, as a clause to put before the failure's
+ * own `reason`: one for each reach, and one for a refusal the gateway wrote in
+ * words this package recognises.
  *
- * Each clause is held to what its own case actually knows, and the last reach
- * is the one that has to be written carefully, because it is one sentence in
- * front of three different situations. A call abandoned on an abort throws
- * with no code at all and may never have left this process. A connection that
- * broke in flight was certainly sent. And an answer that stopped mid-sentence
- * means the gateway certainly had the call — a status and part of a body came
- * back. So this clause says nothing about direction: not that the call was
- * sent, not that nothing came back, and not that whether it arrived is
- * unknown, because on the third road it is known and the answer is yes. What
- * the three share is that the exchange was cut short, and so what the call did
- * is not known — and that is the whole of what may be claimed here. The
- * specifics belong to the failure's own `reason`, which every caller prints
- * immediately after this clause and which names the road it came down.
+ * The clause for `unknown` covers three situations (an abort before sending, a
+ * connection broken in flight, an answer cut off mid-way), so it claims only
+ * that the exchange did not finish and what the call did is not known; the
+ * `reason` that follows names which it was.
  */
 export const whatIsKnown = (failure) => {
-    // The fourth case, ahead of the three reaches. Each of those says some
-    // version of "we cannot tell you what this call did"; here the gateway told
-    // us, in a shape we recognise, that it would not do it. Sending a merchant
-    // "what came back could not be read" in front of a reason we are about to
-    // quote is the message arguing with itself, and the half they believe is the
-    // first one.
+    // A refusal comes first: the gateway said what it would not do, and "what
+    // came back could not be read" in front of its reason would contradict it.
     if (failure.refusal !== undefined) {
         return "it reached us and the answer says the call did not go through";
     }
@@ -188,13 +115,11 @@ export const whatIsKnown = (failure) => {
 };
 /**
  * One call, answered with the route's document or with a sentence about why
- * there is no document.
+ * there is none.
  *
- * The cast at the end is the one place this file steps outside what the
- * compiler can follow. `API_ROUTES[name]` for an unresolved `name` is a union
- * of every route, so the schema reached at runtime is the right one while its
- * static type is the union of all of them. `DocumentOf<N>` names the same
- * schema for the caller, and the two are the same object.
+ * The cast at the end is safe though the compiler cannot follow it: for an
+ * unresolved `name` the static type of the schema is a union of every route's,
+ * while at runtime it is the right one.
  */
 export const callRoute = async (gateway, name, options = {}) => {
     const route = API_ROUTES[name];
@@ -225,9 +150,8 @@ export const callRoute = async (gateway, name, options = {}) => {
         text = await response.text();
     }
     catch (cause) {
-        // The gateway answered and the answer was not read to the end. Saying
-        // "answered with something that is not JSON" here would be blaming it for
-        // a connection that broke on our side of the exchange.
+        // The gateway answered and the answer was not read to the end; calling it
+        // "not JSON" would blame the gateway for a connection broken on our side.
         return failure(name, `${name} at ${url.href} began answering ${response.status} and the answer could not be read to the end: ${String(cause)}`, REACH.UNKNOWN);
     }
     let body;
@@ -241,27 +165,12 @@ export const callRoute = async (gateway, name, options = {}) => {
     if (parsed.success) {
         return { ok: true, document: parsed.data };
     }
-    // A body that is not the route's document is asked whether it is the
-    // envelope every route says no in, and if it is, the caller is handed what
-    // the gateway said rather than our complaint about being unable to read it.
-    // That is the difference between telling a merchant their order is over and
-    // sending them to read our schemas.
-    //
-    // What keeps this from swallowing one of the surface's own documents is not
-    // the order of these two reads. Some of those documents are refusals — an
-    // order call that did not go through says so inside the shape its route
-    // promises — and the envelope declines them on its own: its outer object is
-    // strict, so a body carrying anything beside `error` is not one, and the
-    // `ok` discriminator those answers lead with is exactly such a field. The
-    // guarantee is held where it can be checked rather than here, by a case in
-    // `api.test.ts` that puts an envelope to every route's document and demands
-    // a refusal from each. Reversing these two reads is not what would break it,
-    // which is why this paragraph does not claim the order is load-bearing.
-    //
-    // The status is not consulted, here or above. Which refusals of this surface
-    // arrive under which code is the gateway's to decide and is written down
-    // nowhere both sides read, so a rule keyed on it would be a guess; the shape
-    // of the answer is the agreement, and it is the same at 402 as at 500.
+    // A body that is not the route's document may be the error envelope, and
+    // then the caller gets what the gateway said. Refusals that live inside a
+    // route's own document cannot be mistaken for it, because the envelope's
+    // outer object is strict and those documents carry `ok`; a test in
+    // `api.test.ts` holds that for every route. The HTTP status is not
+    // consulted: which refusal arrives under which status is the gateway's.
     const refused = ErrorEnvelopeSchema.safeParse(body);
     if (refused.success) {
         const { code, message, retryable } = refused.data.error;

package/dist/verify.d.ts

@@ -1,22 +1,13 @@
 /**
- * `agentify verify` — the check a merchant runs on their cards before they
- * publish them.
+ * `agentify verify`: the check a merchant runs on their card files before
+ * publishing them, whether each card is enough for an agent to assemble a
+ * correct purchase, read the way publication reads it.
  *
- * It checks one thing, in full: whether a card is enough for an agent to
- * assemble a correct purchase, read the way publication reads it. Whether the
- * merchant's handler holds against one order delivered twice is not something
- * a command holding only card files can try — no route raises an order for a
- * merchant's own card — so it is not one of this command's checks, and the
- * output says so and where it is proved instead: with a test purchase against
- * the merchant's own delivery system. Counted here as a check that "did not
- * run", it made every complete card answer as something short of success, and
- * a build reading the exit code took a good card for a failure.
- *
- * Which cards are checked is asked for rather than discovered. Nothing in this
- * package, in the contract or in any decision says where a merchant keeps
- * their cards, and a command that went looking would be inventing a
- * convention — a file name, a directory, a manifest — that nobody agreed to
- * and that every merchant would then have to work around.
+ * Whether the merchant's handler holds against one order delivered twice
+ * cannot be tried by a command holding only card files, so the output says it
+ * is not checked here and where it is proved instead; it does not count
+ * against the exit code. The cards to check are named on the command line,
+ * because nothing says where a merchant keeps them.
  */
 /** What the command answers with. */
 export declare const VERIFY_EXIT: Readonly<{

package/dist/verify.js

@@ -1,22 +1,13 @@
 /**
- * `agentify verify` — the check a merchant runs on their cards before they
- * publish them.
+ * `agentify verify`: the check a merchant runs on their card files before
+ * publishing them, whether each card is enough for an agent to assemble a
+ * correct purchase, read the way publication reads it.
  *
- * It checks one thing, in full: whether a card is enough for an agent to
- * assemble a correct purchase, read the way publication reads it. Whether the
- * merchant's handler holds against one order delivered twice is not something
- * a command holding only card files can try — no route raises an order for a
- * merchant's own card — so it is not one of this command's checks, and the
- * output says so and where it is proved instead: with a test purchase against
- * the merchant's own delivery system. Counted here as a check that "did not
- * run", it made every complete card answer as something short of success, and
- * a build reading the exit code took a good card for a failure.
- *
- * Which cards are checked is asked for rather than discovered. Nothing in this
- * package, in the contract or in any decision says where a merchant keeps
- * their cards, and a command that went looking would be inventing a
- * convention — a file name, a directory, a manifest — that nobody agreed to
- * and that every merchant would then have to work around.
+ * Whether the merchant's handler holds against one order delivered twice
+ * cannot be tried by a command holding only card files, so the output says it
+ * is not checked here and where it is proved instead; it does not count
+ * against the exit code. The cards to check are named on the command line,
+ * because nothing says where a merchant keeps them.
  */
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
@@ -56,43 +47,11 @@ const USAGE = [
     "handler holds against an order delivered twice is not checked here.",
 ].join("\n");
 /**
- * Why the bare command the documentation shows does not run.
- *
- * `agentify verify` with nothing after it would check the cards the merchant
- * has already published. The binding reason it cannot is the plainest one:
- * this command takes no key and no address, builds no client and asks the
- * gateway nothing, so it has no way to see anything that was published.
- *
- * The call it would have needed does exist, and saying so is the honest half
- * of the answer: `list_merchant_cards` returns published cards whole, each of
- * them the card its author wrote rather than an agent's projection of it. What
- * that route promises is worth repeating exactly, because every part of it is
- * easy to overstate. Whose cards it returns is settled: the merchant whose key
- * the call was made with, and nobody else. A card reaches that list by being accepted at
- * `publish_card`, which parses the same `CardSchema` and applies the same
- * price rule this package does, so the cards on it passed this check on the
- * day they went out — which is not the same as passing it now. The schema can
- * move, and the price rule is applied only at publication: a stored card is
- * parsed again on its way back out against the schema alone, so a card
- * published before the price rule tightened is read back as it was, and one
- * that no longer fits a schema that moved fails that read. And a
- * command that builds no client can never learn which version of the contract
- * the gateway is speaking. Publishing is more than this check, too: it can
- * refuse a card for reasons the contract does not carry, which `checkCard`
- * says in its own words.
- *
- * Taking no key is a choice and not a hole, which is worth saying here because
- * the first line of the message reads like a limitation somebody would set out
- * to remove. A check that read published cards over that route would all but
- * always pass — they got onto it by passing this very check — and a green that
- * cannot fail teaches a merchant to stop reading it. What would earn a keyed mode is a
- * dry run of publishing, which can refuse for reasons no schema carries; there
- * is no such route (`docs/research/00-open-questions.md`).
- *
- * So this is a stop and not a scolding, and it is answered as a call the
- * command cannot work from. The way through it is to name the card files, which are
- * the copy the merchant can still change — the file is what the next publish
- * carries, whether the card is new or an edit to one already out.
+ * What the bare command, with no card files, answers. This command takes no
+ * key and builds no client, so it cannot see published cards; and checking
+ * them would all but always pass, since a card is published only after the
+ * same check. A green that cannot fail teaches a merchant to stop reading it.
+ * The card files are what the next publish carries, so they are what to name.
  */
 const NOTHING_TO_CHECK = [
     "agentify verify was given no card files, and it does not go looking for them:",
@@ -169,10 +128,8 @@ export const runVerify = async (argv, say) => {
     }
     const faulted = checked.filter((card) => card.problems.length > 0);
     if (faulted.length > 0) {
-        // The truncation, said out loud. A card is checked in two stages and the
-        // second — the rules that compare one field against another — is only
-        // reached when the first passes, so a short list is not a promise that
-        // one round of fixes is enough.
+        // The truncation, said out loud: the rules between fields are reached
+        // only once the shape passes, so one round of fixes may not be enough.
         say("  Fix these and run again: a card whose shape is wrong is not checked against the rules that compare one field with another, so there may be more behind them.");
     }
     say("");