@nuanu-ai/agentify 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -1,36 +1,24 @@
 /**
- * The Agentify merchant SDK: what someone else's engineer installs so that
- * their catalog sells to agents.
+ * The Agentify merchant SDK: what a merchant's engineer installs so that their
+ * catalog sells to agents.
  *
- * There are two things in here and they are one process. `createClient` builds
- * a handle on the gateway from a key and an address; through it a merchant
- * says what their process answers with `on`, opens one outgoing subscription
- * that carries paid orders, price questions and order events together, and
- * closes orders they took on earlier off the orders themselves. Beside it,
- * `checkCard` is the check a merchant runs on their own cards before
- * publishing them — the same check the documentation calls
- * `agentify verify`, which the published package installs as a command of
- * that name. The command's own insides are not exported: what a merchant calls
- * from their code is `checkCard`, and what they run from a terminal is the
- * command, and neither of those needs the other's exit codes.
+ * `createClient` builds a handle on the gateway from a key and an address.
+ * Through it a merchant says what their process answers with `on`, opens one
+ * outgoing subscription that carries paid orders, price questions and order
+ * events together, and closes orders they took on earlier. `checkCard` is the
+ * check a merchant runs on their own cards before publishing them; the package
+ * also installs it as the `agentify verify` command.
  *
- * Every call that can fail answers in one envelope — `ok` says which, and a
+ * Every call that can fail answers in one envelope: `ok` says which, and a
  * failure carries one `error` with a code, a sentence, whether repeating could
- * help, and the findings under `problems` where the call is refusing what it
- * was handed. What throws instead is a call with no such branch, as
- * `AgentifyError`, under the same codes.
+ * help, and the findings under `problems` where the call refuses what it was
+ * handed. A call with no such branch throws `AgentifyError` instead, under the
+ * same codes.
  *
- * The runtime dependency tree is minimal and listed in full: our own
- * `@nuanu-ai/agentify-contracts`, and zod underneath it, and nothing else. A merchant
- * installing the SDK into their production should know exactly what arrives
- * with it, rather than inherit a foreign package tree they would then be
- * maintaining themselves. Every new third-party package in this tree is a
- * recorded decision (ADR-0003 §8), and a test in this package holds the line.
- *
- * The types a merchant needs to write their own functions against — what a
- * card is, what an order carries, what a handler may answer — are re-exported
- * here from the contracts package, so that integration code has one import and
- * not two.
+ * The runtime dependencies are `@nuanu-ai/agentify-contracts` and zod beneath
+ * it, and nothing else. The types an integration is written against — a card,
+ * an order, a handler's answer — are re-exported here, so integration code
+ * needs one import.
  */
 export type { CallError, Card, CardInput, Delivery, Fulfillment, HandlerAnswer, MerchantFinding, Money, Order, OrderCallResponse, OrderCallResult, OrderEvent, OrderList, OrderStatus, OrderWithStatus, Problem, PublishResult, QuotePurpose, QuoteRequest, QuoteResponse, Refusal, RefusalCode, SalePrice, Shipment, ShipTo, } from "@nuanu-ai/agentify-contracts";
 export { CARD_REJECTED, MERCHANT_FINDINGS, ORDER_EVENT_TYPES, RECOMMENDED_REFUSAL_CODES, } from "@nuanu-ai/agentify-contracts";

package/dist/index.js

@@ -1,36 +1,24 @@
 /**
- * The Agentify merchant SDK: what someone else's engineer installs so that
- * their catalog sells to agents.
+ * The Agentify merchant SDK: what a merchant's engineer installs so that their
+ * catalog sells to agents.
  *
- * There are two things in here and they are one process. `createClient` builds
- * a handle on the gateway from a key and an address; through it a merchant
- * says what their process answers with `on`, opens one outgoing subscription
- * that carries paid orders, price questions and order events together, and
- * closes orders they took on earlier off the orders themselves. Beside it,
- * `checkCard` is the check a merchant runs on their own cards before
- * publishing them — the same check the documentation calls
- * `agentify verify`, which the published package installs as a command of
- * that name. The command's own insides are not exported: what a merchant calls
- * from their code is `checkCard`, and what they run from a terminal is the
- * command, and neither of those needs the other's exit codes.
+ * `createClient` builds a handle on the gateway from a key and an address.
+ * Through it a merchant says what their process answers with `on`, opens one
+ * outgoing subscription that carries paid orders, price questions and order
+ * events together, and closes orders they took on earlier. `checkCard` is the
+ * check a merchant runs on their own cards before publishing them; the package
+ * also installs it as the `agentify verify` command.
  *
- * Every call that can fail answers in one envelope — `ok` says which, and a
+ * Every call that can fail answers in one envelope: `ok` says which, and a
  * failure carries one `error` with a code, a sentence, whether repeating could
- * help, and the findings under `problems` where the call is refusing what it
- * was handed. What throws instead is a call with no such branch, as
- * `AgentifyError`, under the same codes.
+ * help, and the findings under `problems` where the call refuses what it was
+ * handed. A call with no such branch throws `AgentifyError` instead, under the
+ * same codes.
  *
- * The runtime dependency tree is minimal and listed in full: our own
- * `@nuanu-ai/agentify-contracts`, and zod underneath it, and nothing else. A merchant
- * installing the SDK into their production should know exactly what arrives
- * with it, rather than inherit a foreign package tree they would then be
- * maintaining themselves. Every new third-party package in this tree is a
- * recorded decision (ADR-0003 §8), and a test in this package holds the line.
- *
- * The types a merchant needs to write their own functions against — what a
- * card is, what an order carries, what a handler may answer — are re-exported
- * here from the contracts package, so that integration code has one import and
- * not two.
+ * The runtime dependencies are `@nuanu-ai/agentify-contracts` and zod beneath
+ * it, and nothing else. The types an integration is written against — a card,
+ * an order, a handler's answer — are re-exported here, so integration code
+ * needs one import.
  */
 export { CARD_REJECTED, MERCHANT_FINDINGS, ORDER_EVENT_TYPES, RECOMMENDED_REFUSAL_CODES, } from "@nuanu-ai/agentify-contracts";
 export { checkCard } from "./check-card.js";

package/dist/schema.d.ts

@@ -1,55 +1,31 @@
 /**
- * The small amount of schema machinery this package needs, written against the
- * shape of a result rather than against the library that produces it.
- *
- * The reason is the dependency tree a merchant installs. The SDK declares one
- * runtime dependency, `@nuanu-ai/agentify-contracts`, and zod arrives underneath it
- * (ADR-0003 §8). Importing zod here by name would add a package to that tree
- * without a recorded decision — and under a strict install it would not even
- * resolve, because zod is the contracts package's dependency and not ours. So
- * the schemas are used through the objects contracts exports, and where a type
- * has to be named at all it is named by its shape.
- *
- * Nothing here reimplements validation. The checking is the contracts
- * schemas', every time; this file only carries their findings across into the
- * shape a merchant reads.
+ * The little schema machinery this package needs, written against the shape of
+ * a result rather than against zod. zod arrives beneath
+ * `@nuanu-ai/agentify-contracts` and is not this package's dependency, so under
+ * a strict install it would not even resolve here. Nothing here validates; it
+ * carries the contract schemas' findings into the shape a merchant reads.
  */
 import type { Problem } from "@nuanu-ai/agentify-contracts";
 /**
- * One finding of a schema, as much of it as this package reads.
- *
- * `code` is optional because it is optional on the shape zod produces, and a
- * finding with no code still has a path and a sentence. Where it is missing
- * the translation below supplies one rather than leaving the field out: a
- * consumer branching on the code should never have to tell "no code" from "the
- * field did not arrive".
+ * One finding of a schema, as much of it as this package reads. A finding
+ * with no code is given `UNNAMED_FINDING`, so a consumer never has to tell "no
+ * code" from "the field did not arrive".
  */
 export interface SchemaIssue {
     readonly code?: string | undefined;
     readonly path: readonly PropertyKey[];
     readonly message: string;
 }
-/** The code a finding travels under when the schema did not name one. */
-export declare const UNNAMED_FINDING = "invalid";
 /**
- * A schema's findings, in the shape the publish call answers in.
- *
- * One shape for both sides is the point. A merchant who ran the check locally
- * and a merchant who published and was refused read the same object under the
- * same word — a path to the field, a code for their code, a sentence for the
- * person fixing it — so neither of the two has a reader of its own.
- *
- * The path is flattened to text because that is what the contract carries. An
- * index inside an array arrives as a number and would otherwise be a number in
- * one finding and a name in the next.
+ * A schema's findings, in the shape the publish call answers in, so a local
+ * check and a refused publish read the same. The path is flattened to text,
+ * since an array index would otherwise be a number in one finding and a name
+ * in the next.
  */
 export declare const problemsOf: (issues: readonly SchemaIssue[]) => Problem[];
 /**
- * The findings of a schema rendered as one block of text, one finding a line,
- * each pointing at the field it is about.
- *
- * A finding about the whole document has an empty path and is written as such
- * rather than with a blank where the field would be, so that "this is about
- * the card" and "the path went missing" do not look the same.
+ * The findings as one block of text, one a line, each pointing at its field.
+ * A finding with an empty path is written as about the card as a whole, so it
+ * cannot be mistaken for a path that went missing.
  */
 export declare const describeProblems: (problems: readonly Problem[]) => string;

package/dist/schema.js

@@ -1,32 +1,17 @@
 /**
- * The small amount of schema machinery this package needs, written against the
- * shape of a result rather than against the library that produces it.
- *
- * The reason is the dependency tree a merchant installs. The SDK declares one
- * runtime dependency, `@nuanu-ai/agentify-contracts`, and zod arrives underneath it
- * (ADR-0003 §8). Importing zod here by name would add a package to that tree
- * without a recorded decision — and under a strict install it would not even
- * resolve, because zod is the contracts package's dependency and not ours. So
- * the schemas are used through the objects contracts exports, and where a type
- * has to be named at all it is named by its shape.
- *
- * Nothing here reimplements validation. The checking is the contracts
- * schemas', every time; this file only carries their findings across into the
- * shape a merchant reads.
+ * The little schema machinery this package needs, written against the shape of
+ * a result rather than against zod. zod arrives beneath
+ * `@nuanu-ai/agentify-contracts` and is not this package's dependency, so under
+ * a strict install it would not even resolve here. Nothing here validates; it
+ * carries the contract schemas' findings into the shape a merchant reads.
  */
 /** The code a finding travels under when the schema did not name one. */
-export const UNNAMED_FINDING = "invalid";
+const UNNAMED_FINDING = "invalid";
 /**
- * A schema's findings, in the shape the publish call answers in.
- *
- * One shape for both sides is the point. A merchant who ran the check locally
- * and a merchant who published and was refused read the same object under the
- * same word — a path to the field, a code for their code, a sentence for the
- * person fixing it — so neither of the two has a reader of its own.
- *
- * The path is flattened to text because that is what the contract carries. An
- * index inside an array arrives as a number and would otherwise be a number in
- * one finding and a name in the next.
+ * A schema's findings, in the shape the publish call answers in, so a local
+ * check and a refused publish read the same. The path is flattened to text,
+ * since an array index would otherwise be a number in one finding and a name
+ * in the next.
  */
 export const problemsOf = (issues) => issues.map((issue) => ({
     path: issue.path.map(String),
@@ -34,12 +19,9 @@ export const problemsOf = (issues) => issues.map((issue) => ({
     message: issue.message,
 }));
 /**
- * The findings of a schema rendered as one block of text, one finding a line,
- * each pointing at the field it is about.
- *
- * A finding about the whole document has an empty path and is written as such
- * rather than with a blank where the field would be, so that "this is about
- * the card" and "the path went missing" do not look the same.
+ * The findings as one block of text, one a line, each pointing at its field.
+ * A finding with an empty path is written as about the card as a whole, so it
+ * cannot be mistaken for a path that went missing.
  */
 export const describeProblems = (problems) => problems
     .map((problem) => problem.path.length === 0

package/dist/transport.d.ts

@@ -1,48 +1,17 @@
 /**
- * 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, type RouteName } from "@nuanu-ai/agentify-contracts";
 /** Where the gateway is and which key opens its doors. */
@@ -52,13 +21,10 @@ export interface Gateway {
 }
 /**
  * The document a route answers with, taken from the schema the table names.
- *
- * It is written against the shape of a parse result rather than with zod's own
- * `infer`, for the reason given in `schema.ts`: zod is not this package's
- * dependency to import. The effect is the same — rename a field in a contract
- * schema and the call sites here stop compiling.
+ * It reads the shape of a parse result rather than using zod's `infer`,
+ * because zod is not this package's to import (see `schema.ts`).
  */
-export type DocumentOf<N extends RouteName> = (typeof API_ROUTES)[N]["response"] extends {
+type DocumentOf<N extends RouteName> = (typeof API_ROUTES)[N]["response"] extends {
     document: {
         safeParse(value: unknown): infer Result;
     };
@@ -67,20 +33,11 @@ export type DocumentOf<N extends RouteName> = (typeof API_ROUTES)[N]["response"]
     data: infer Document;
 } ? Document : never : never;
 /**
- * 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 declare const REACH: Readonly<{
     /** No connection was made, so the gateway certainly has nothing. */
@@ -88,24 +45,18 @@ export declare const REACH: Readonly<{
     /** The gateway answered, and the answer is not one this package can read. */
     readonly 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.
      */
     readonly UNKNOWN: "unknown";
 }>;
 export type Reach = (typeof REACH)[keyof typeof REACH];
 /**
- * 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 declare const reachOf: (cause: unknown) => Reach;
 /** A call that did not produce the document the route promises. */
@@ -116,30 +67,16 @@ export interface TransportFailure {
     /** What is known about whether the gateway got the call. */
     readonly reach: Reach;
     /**
-     * The body, where it was JSON and simply was not the document.
-     *
-     * It is here for one reader: the poll loop, which looks in it for the
-     * contract version, because a gateway of another dialect answers with
-     * something this SDK cannot parse and would otherwise look exactly like a
-     * broken one.
+     * The body, where it was JSON and was not the document. The poll loop looks
+     * in it for the contract version, which tells a gateway of another version
+     * apart from a broken one.
      */
     readonly body?: unknown;
     /**
-     * The gateway's own refusal, where the answer was one.
-     *
-     * Present exactly when the body was the contract's error envelope, and it is
-     * the difference between a failure this package had to describe and one the
-     * gateway described itself. The two want different sentences in front of
-     * them: everything else here is some flavour of "we cannot tell you what
-     * happened", and this one is the gateway saying what it would not do and
-     * why. It carries the code as a value and not only inside the sentence,
-     * because a caller that wants to branch on the reason should not be parsing
-     * prose to find it.
-     *
-     * `retryable` travels with it for the same reason and is the gateway's own
-     * answer about its own refusal: whether making this call again could get
-     * past it. Only the side that refused knows, and this package must not
-     * improve on what it was told.
+     * The gateway's own refusal, present exactly when the body was the
+     * contract's error envelope. Its code and `retryable` are carried as values
+     * so a caller can branch without parsing prose, and `retryable` is the
+     * gateway's own answer, which this package does not second-guess.
      */
     readonly refusal?: {
         readonly code: string;
@@ -160,41 +97,24 @@ export interface CallOptions {
     readonly body?: unknown;
     readonly signal?: AbortSignal;
 }
-/** The address of one call: the gateway's base, then the route's own path. */
-export declare const addressOf: (baseUrl: string, name: RouteName, path: CallOptions["path"]) => string;
 /**
- * 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 declare const whatIsKnown: (failure: TransportFailure) => string;
 /**
  * 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 declare const callRoute: <N extends RouteName>(gateway: Gateway, name: N, options?: CallOptions) => Promise<Answer<N>>;
+export {};