@nuanu-ai/agentify 0.4.0 → 0.5.1

package/dist/client.d.ts

@@ -1,110 +1,56 @@
 /**
  * The client a merchant's engineer holds: a catalog, an order desk, and one
- * place to say what this process answers.
+ * place to say what this process answers. Every method here is one a page of
+ * the documentation tells a merchant to call, and the documentation's examples
+ * are compiled against these types by a test.
  *
- * The shape of it is the portal's, not this file's. Every method here exists
- * because a page of the documentation tells a merchant to call it, with the
- * arguments that page passes and answering with what that page reads — and the
- * examples on those pages are compiled against these types by a test, so the
- * code a merchant copies out of the documentation is code that builds.
+ * One stream carries orders, price questions and order events, so there is one
+ * way to register a handler, `on(kind, handler)`, and one lifecycle, `start`
+ * and `stop`.
  *
- * Three kinds travel one stream, so there is one way to register a handler for
- * one of them — `on(kind, handler)` — and one lifecycle, `start` and `stop`,
- * for the loop that carries all three. What a handler receives carries the
- * calls that answer it, and that is the part worth reading before changing
- * anything here, because two things that look alike are deliberately not.
+ * Two families of calls on an order look alike and are not. `delivered`,
+ * `refused` and `accepted` build the answer a handler returns and send
+ * nothing; returning it is what makes forgetting to answer, or answering
+ * twice, impossible. `deliver`, `refuse` and `accept` send: they are the
+ * asynchronous merchant's calls, made later from anywhere in their code, and
+ * they are on every order this client hands back, including `orders.forId`
+ * for a process that kept only the identifier.
  *
- * `order.delivered(...)`, `order.refused(...)` and `order.accepted(...)`
- * build the answer and send nothing; the handler still returns it. A bot
- * library lets a handler reply and forget, and forgetting there costs a
- * message; forgetting here is an order nobody answered — redelivered, a
- * delivery attempt spent, and in the asynchronous mode a debt to a buyer at
- * the end of it. Returning the answer is what makes forgetting impossible and
- * answering twice impossible.
- *
- * `order.deliver(...)`, `order.refuse(...)` and `order.accept(...)` are the
- * other thing: they send. They are the asynchronous merchant's closure verbs,
- * made hours later and from anywhere in their code, and they exist on the
- * order rather than beside it so that a merchant never holds an identifier of
- * ours. The same calls are on every order this client hands back — off the
- * stream, off `orders.get`, off `orders.list`, and off `orders.forId` for the
- * process that kept nothing but the identifier — because a process that
- * restarted has no object left to hold, and that is exactly the moment
- * juggling identifiers would come back.
- *
- * One rule runs through the whole surface and it is worth stating once. What
- * the contract gives a call a failure branch for is returned, never thrown,
- * and every one of those answers is the same envelope: `ok` says which it was,
- * a card that was not published comes back with its findings under `problems`,
- * and an order call that did not go through comes back as an error with a flag
- * saying whether repeating it could help. A merchant's integration code is
- * expected to read those and branch on them.
- *
- * What is thrown is what has no branch to be read on, and it is two kinds. A
- * client built wrong — no key, an address that is not one, a handler
- * registered twice — is a `TypeError` at the line that is wrong, before
- * anything leaves the process. A call that went out and produced no answer of
- * the kind its route promises, where the route has nowhere to put one, is a
- * `AgentifyError` carrying the same code vocabulary the returned failures use.
- *
- * The one place that rule needed a decision rather than a reading is a
- * `deliver` or a `refuse` whose answer never arrived, or arrived in words this
- * package cannot read. The contract has a branch for it — an error with a flag
- * saying whether calling again could change the outcome is exactly the shape
- * of "the connection dropped, call again" — so it comes back through that
- * branch, under a code this package produces and the gateway never sends. The
- * three codes and what separates them are written down beside them below.
+ * What the contract gives a failure branch is returned, never thrown, in one
+ * envelope whose `ok` says which it was. What has no branch is thrown: a client
+ * built wrong is a `TypeError` before anything leaves the process, and a call
+ * that went out and produced no answer its route can carry is an
+ * `AgentifyError` under the same codes.
  */
-import type { Acceptance, CardInput, Delivery, HandlerAnswer, Money, Order, OrderAcceptResponse, OrderCallResponse, OrderWithStatus, PublishResult, QuoteRequest, QuoteResponse, Refusal } from "@nuanu-ai/agentify-contracts";
+import type { CardInput, Delivery, HandlerAnswer, Money, Order, OrderAcceptResponse, OrderCallResponse, OrderWithStatus, PublishResult, QuoteRequest, QuoteResponse, Refusal } from "@nuanu-ai/agentify-contracts";
 import { type EventHandler, type ProblemReporter, type StreamHandlerKind } from "./worker.js";
 export interface ClientOptions {
     /**
-     * The merchant's API key.
-     *
-     * It admits `undefined` because the thing a merchant actually writes is
-     * `process.env.AGENTIFY_API_KEY`, which is `string | undefined` in every
-     * strict TypeScript project there is. Refusing that at the type level would
-     * teach every merchant to silence it with a non-null assertion, which turns
-     * an unset variable into an authorisation failure much later. It is refused
-     * here instead, at the line that is wrong, with a sentence that names what
-     * is missing.
+     * The merchant's API key. `undefined` is accepted by the type, since that is
+     * what `process.env.AGENTIFY_API_KEY` is, and refused when the client is
+     * built with a `TypeError` naming what is missing.
      */
     readonly apiKey: string | undefined;
     /**
-     * Where the gateway is: `https://test.agentify.ad` while the merchant
-     * is building, `https://agentify.ad` once they are live.
-     *
-     * Optional, and there is deliberately no default behind it. Both addresses
-     * are settled and this package still refuses to pick one, because which of
-     * them a process talks to is not a convenience — it is the difference
-     * between a sale and a rehearsal (ADR-0020). A default would be right for
-     * whoever wrote it and wrong for somebody's production the first time a
-     * deployment inherited it, and that is a mistake nothing downstream can
-     * catch: every answer from the other site parses perfectly.
+     * Where the gateway is: `https://test.agentify.ad` while the merchant is
+     * building, `https://agentify.ad` once they are live.
      *
-     * Leaving it out builds a client, exactly as the quickstart's first step
-     * says it does, and every call that would have to reach the gateway fails
-     * with a sentence naming what is missing and both addresses to choose
-     * between. That is where the failure belongs: the documentation tells the
-     * merchant that the first call is what checks whether they can reach us.
-     * Giving a wrong address, on the other hand, is refused here and now — a
-     * value that is not an address at all cannot become one later.
+     * There is no default on purpose: which of the two a process talks to is the
+     * difference between a sale and a rehearsal, and every answer from the wrong
+     * one parses perfectly. Left out, the client is still built, and every call
+     * that has to reach the gateway throws a `TypeError` naming both addresses.
+     * A value that is not an http or https address is refused when the client
+     * is built.
      */
     readonly baseUrl?: string | undefined;
 }
 /**
  * The calls every order carries, wherever the merchant got it from.
  *
- * The first three build an answer and send nothing: they are what a handler
- * returns, and the return is what this SDK posts. The last three send, and
- * they are the calls an asynchronous merchant makes later — after the supplier
- * answered, from another part of their code, from another process life.
- *
- * There are three of each because the two halves are not the same set of
- * choices seen twice. A synchronous handler chooses between delivering and
- * refusing on the spot; an asynchronous one accepts and then, eventually,
- * delivers or refuses. Accepting from outside a handler exists for the
- * merchant who decides later, in another part of their code.
+ * `delivered`, `refused` and `accepted` build an answer and send nothing: they
+ * are what a handler returns, and the SDK posts the return. `deliver`,
+ * `refuse` and `accept` send, and are what an asynchronous merchant calls
+ * later, from another part of their code or another process.
  */
 export interface OrderCalls {
     /** The goods, as the handler's answer. Building one sends nothing. */
@@ -112,50 +58,47 @@ export interface OrderCalls {
     /** A final "this cannot be delivered", as the handler's answer. */
     refused(refusal: Refusal): HandlerAnswer;
     /**
-     * Taking the order on without delivering yet, as the handler's answer. An
-     * empty acceptance is a complete answer; the expected time is said where it
-     * is known.
+     * Taking the order on without delivering yet, as the handler's answer. It
+     * carries nothing: what the merchant is held to is the delivery deadline on
+     * the card.
      */
-    accepted(acceptance?: Acceptance): HandlerAnswer;
+    accepted(): HandlerAnswer;
     /**
-     * The goods for an order taken on earlier. Idempotent by the order's own
-     * identifier, so repeating it after a dropped connection does no work twice.
+     * The goods for an order taken on earlier. Idempotent by the order's
+     * identifier, so repeating it after a dropped connection delivers nothing
+     * twice and charges nothing twice.
      */
     deliver(delivery: Delivery): Promise<OrderCallResponse>;
-    /** A final "this cannot be delivered" for an order already taken on. */
+    /**
+     * A final "this cannot be delivered" for an order already taken on. Unlike
+     * `deliver`, it is not promised to be safe to repeat: when it fails, and
+     * above all with `outcome_unknown`, read the order back with `orders.get`
+     * before sending it again.
+     */
     refuse(refusal: Refusal): Promise<OrderCallResponse>;
-    /** Takes the order on from outside a handler. Repeats are ordinary. */
-    accept(acceptance?: Acceptance): Promise<OrderAcceptResponse>;
+    /** Takes the order on from outside a handler. Repeating it is harmless. */
+    accept(): Promise<OrderAcceptResponse>;
 }
 /**
- * The least an order can be and still be answerable: its identifier, and the
- * calls that close it.
- *
- * It is what `orders.forId` hands back, and it is the shape a merchant's own
- * function should take when all it does is close an order — every richer order
- * below satisfies it.
+ * The least an order can be and still be answered: its identifier and the
+ * calls that close it. It is what `orders.forId` returns, and the type to take
+ * in a function that only closes orders.
  */
 export type OrderHandle = {
     readonly id: string;
 } & OrderCalls;
 /**
- * An order off the stream, with the calls that close it.
- *
- * "Live" is the whole of the difference from the plain document: this object
- * holds the client that produced it, so it can call home on its own and the
- * merchant never writes an identifier of ours as an argument.
+ * An order off the stream, with the calls that close it. It holds the client
+ * that produced it, so the merchant never passes an identifier back.
  */
 export type LiveOrder = Order & OrderCalls;
-/** The same, read back from our record, so it also says where the order stands. */
+/** An order read back from Agentify, with where it stands and the calls that close it. */
 export type LiveOrderWithStatus = OrderWithStatus & OrderCalls;
 /**
- * The two answers a price question has, built from the question itself.
- *
- * `as_of` is what separates "I went and looked" from "here is what was in the
- * cache", and the gateway reads it to decide how far it trusts the answer. Left
- * out, it is the moment the answer is built — which is the truth for a price
- * computed on the spot, and is why a merchant answering from a cache passes the
- * moment that cache was filled instead.
+ * The two answers a price question has. `asOf` is when the answer was true,
+ * which separates "I went and looked" from "here is what was in the cache";
+ * left out, it is the moment the answer is built, so a merchant answering
+ * from a cache passes the moment that cache was filled.
  */
 export interface QuoteCalls {
     available(price: Money, asOf?: string): QuoteResponse;
@@ -168,22 +111,9 @@ export type OrderHandler = (order: LiveOrder) => HandlerAnswer | Promise<Handler
 /** What the merchant's code answers to "how much is this and is it there". */
 export type QuoteHandler = (question: LiveQuoteRequest) => QuoteResponse | Promise<QuoteResponse>;
 /**
- * Everything a merchant's process can be asked to answer, by the word they
- * register it under.
- *
- * A map rather than four methods, because the stream is one stream and this is
- * the list of what travels on it. The day the contract carries a fourth kind —
- * the confirmation request, whose shape it does not carry yet — `REGISTERED_AS`
- * in `worker.ts` gains its word, and from that word every list in this file
- * follows: what `on` accepts, what `start` counts as an answer, and the
- * sentence that names a missing registration. What does not follow is what
- * answers it, so this map gains an entry and the worker's dispatch gains an
- * arm, and both refuse to compile until they do.
- *
- * `problem` is on the same list although nothing on the wire carries it. It is
- * one registration per process, exactly like the other three, and a second
- * place to register one of four things would put back the split this surface
- * exists to remove.
+ * Everything a merchant's process can be asked to answer, by the word it is
+ * registered under. `problem` is not on the wire; it is where the worker
+ * reports what went wrong, registered like the others.
  */
 export interface Handlers {
     order: OrderHandler;
@@ -191,15 +121,12 @@ export interface Handlers {
     event: EventHandler;
     problem: ProblemReporter;
 }
-/** The word for the reporter, which nothing on the wire carries. */
 declare const PROBLEM = "problem";
 export type HandlerKind = StreamHandlerKind | typeof PROBLEM;
 /**
- * Whether a type is a union of more than one thing.
- *
- * Here for one purpose, at `on` below: to tell a kind that is one kind from a
- * kind that is any of several, because only the first can say which handler is
- * the right one.
+ * Whether a type is a union of more than one thing. `on` uses it to refuse a
+ * kind that could be any of several, since only one kind says which handler
+ * is right.
  */
 type IsUnion<Kind, Each = Kind> = Kind extends unknown ? [Each] extends [Kind] ? false : true : never;
 export interface CatalogNamespace {
@@ -207,50 +134,38 @@ export interface CatalogNamespace {
      * Publishes one product, or says what is wrong with the card.
      *
      * Publishing again under the same `merchant_item_id` changes that card
-     * rather than adding a second one, so a publish script can be run as often
-     * as a merchant likes.
+     * rather than adding a second, so a publish script can be run as often as
+     * a merchant likes. A refused card comes back as `ok: false` with every
+     * finding under `error.problems`.
      *
-     * The card is taken as it may be written rather than as it is stored, which
-     * is what `CardInput` is: the price as one string or as two fields, a
-     * declared field as its type word or written out, the fulfillment mode left
-     * off a card that delivers in the answer to the purchase. Every one of those
-     * is opened out when the card is accepted, so a card read back afterwards is
-     * in the one canonical form.
+     * The card may use the short forms `CardInput` allows: the price as one
+     * string, a declared field as its type word, the fulfillment mode left off.
+     * They are opened out on acceptance, so a card read back is in the
+     * canonical form. Throws `AgentifyError` when the call fails without a
+     * publish result, such as a refused key or an answer that could not be read.
      */
     publish(card: CardInput): Promise<PublishResult>;
 }
 export interface OrdersNamespace {
     /**
-     * The calls for an order named by its identifier, without asking us
-     * anything.
-     *
-     * This is the one place an identifier of ours is written by a merchant, and
-     * it is here for the process that kept nothing else: a job queued against
-     * our identifier, a row in their own database. It reaches no gateway, which
-     * is the point — `get` below would tell them more about the order, and
-     * during an outage it cannot tell them anything at all, while a delivery
-     * that comes back as "the network failed, call again" is exactly the answer
-     * they need to keep retrying.
+     * The calls for an order named by its identifier, without asking Agentify
+     * anything. It is for a process that kept only the identifier, such as a job
+     * queued against it. Because it makes no call, it works during an outage,
+     * when a delivery that comes back as "call again" is the answer needed.
      */
     forId(orderId: string): OrderHandle;
     /**
-     * One order and the state it is in, with the calls that close it.
-     *
-     * A round trip, and what it buys is the order itself: its parameters, what
-     * it was sold for, and where it stands.
+     * One order and the state it is in, with the calls that close it. Throws
+     * `AgentifyError` when the call fails, including an unknown order.
      */
     get(orderId: string): Promise<LiveOrderWithStatus>;
     /**
-     * Orders and the states they are in; with `open`, only the ones this worker
-     * should walk.
-     *
-     * The list is what a process reads after a restart: the orders it was handed
-     * and has not finished, each able to be delivered or refused on the spot,
-     * together with the two that stay open once the purchase itself is over — an
-     * order owing a refund, and one delivered that was never paid for. An order
-     * that was priced and never paid is not on it. That one never reached the
-     * handler, and making the goods for it would be making them for a purchase
-     * that did not happen; it stays readable by its identifier through `get`.
+     * Orders and the states they are in. With `open: true`, only the ones a
+     * restarted worker should walk: orders it was handed and has not finished,
+     * an order owing a refund, and one delivered but never paid for. An order
+     * that was priced and never paid never reached the handler, so it is not on
+     * that list; `get` still reads it. Throws `AgentifyError` when the call
+     * fails.
      */
     list(query?: {
         readonly open?: boolean;
@@ -260,104 +175,70 @@ export interface AgentifyClient {
     readonly catalog: CatalogNamespace;
     readonly orders: OrdersNamespace;
     /**
-     * Registers what this process answers for one kind.
+     * Registers what this process answers for one kind: `'order'`, `'quote'`,
+     * `'event'` or `'problem'`.
      *
-     * Once per kind: a second registration is refused rather than replacing the
-     * first, because one message goes to one handler and a silently replaced
-     * handler is a process that has stopped answering without saying so.
+     * Once per kind: a second registration throws a `TypeError` rather than
+     * silently replacing the first. Handlers may be registered before or after
+     * `start`, and survive `stop`.
      *
-     * Handlers may be registered before or after `start`; the loop reads them
-     * when an envelope arrives, not when it begins.
-     *
-     * The condition on the second parameter is what makes the two halves agree,
-     * and it is worth the sentence it costs. Written plainly as
-     * `(kind: Kind, handler: Handlers[Kind])`, a call whose kind is not a
-     * literal — a loop over `['order', 'quote']`, a kind held in a variable —
-     * infers `Kind` as the union, and `Handlers[Kind]` is then the union of
-     * handlers, so an order handler registered under `'quote'` type-checks. It
-     * fails at the first price question, where the handler calls a method the
-     * question does not have, and every sale of that card quietly falls back to
-     * the card's own price. So a kind that is not one kind admits no handler at
-     * all, and the call has to be narrowed to one of them first.
+     * The kind must be one literal kind. A kind held in a variable or a loop
+     * over several admits no handler, because a union would let an order handler
+     * type-check under `'quote'` and fail at the first price question.
      */
     on<Kind extends HandlerKind>(kind: Kind, handler: IsUnion<Kind> extends true ? never : Handlers[Kind]): void;
     /**
-     * Opens the subscription and returns once it is running.
+     * Opens the subscription and returns once it is running. It is outgoing, so
+     * nothing of the merchant's has to be reachable from outside, and one
+     * subscription carries orders, price questions and order events together.
      *
-     * The subscription is outgoing — this side opens it, and nothing of the
-     * merchant's has to be reachable from outside. It carries the orders, the
-     * price questions and the order events together, so a process needs one of
-     * these and not three.
+     * Throws a `TypeError` when no gateway address was given, when the client is
+     * already started or still stopping, or when nothing is registered to
+     * answer.
      */
     start(): Promise<void>;
     /**
-     * Stops the subscription and waits for it to finish. Safe to call twice, and
-     * safe to call on a client that was never started.
-     *
-     * Two things are abandoned rather than finished, and they are not abandoned
-     * on the same terms. A poll parked at the gateway is dropped, and whatever
-     * it would have carried was never handed to anybody, so it is redelivered.
-     * An answer already on its way — a delivery the handler produced a moment
-     * ago — is dropped too, and there the honest thing to say is that nobody on
-     * this side knows whether it arrived first: the order may already be closed
-     * by it, or may come back. The merchant is told which of their orders that
-     * happened to, because on their side the work happened.
+    /**
+     * Stops the subscription and waits for it to finish. Safe to call twice,
+     * and on a client that was never started. Handlers stay registered.
      *
-     * Stopping does not drain. The contract has a word for a poll that asks for
-     * whatever is queued right now and comes straight back, and it is not what a
-     * worker shutting down wants: draining pulls more work into a process that
-     * is going away.
+     * A poll parked at the gateway is dropped; anything taken in the instant
+     * before is an order, which comes again, or an event, which is sent once.
+     * An answer already on its way is dropped too, and nobody on this side knows
+     * whether it arrived: the order may be closed by it or may come back. The
+     * merchant's problem reporter is told which orders that happened to.
      *
-     * The handlers survive it. A supervisor that stops a client and starts it
-     * again is running the same process, and having to register everything a
-     * second time would be a second place for the two to disagree.
+     * Stopping does not drain the queue, which would pull more work into a
+     * process that is going away.
      */
     stop(): Promise<void>;
 }
 /**
- * The three codes an order call comes back under when the gateway produced no
- * answer this package can read.
+ * The codes an order call or an `AgentifyError` carries when the gateway
+ * produced no answer this package can read. The SDK produces them; the
+ * gateway never sends them.
  *
- * The contract's list of error codes is open exactly so that a case nobody
- * anticipated reaches the merchant in its own words instead of being flattened
- * into the nearest of three. These are three of those, and they are produced
- * here rather than on the wire.
- *
- * Three and not one because the difference is the whole of what a merchant
- * needs at that moment, and they are about their own books. A call that never
- * arrived certainly changed nothing. A call answered in words we could not
- * read reached us and may well have done its work; what is missing is what it
- * said. And a call that was sent into silence — the connection broke, the
- * worker was shut down mid-flight — is neither of those, and saying it did not
- * arrive would be inventing the one fact the merchant came here for.
+ * `call_did_not_reach_us`: the call certainly changed nothing.
+ * `answer_not_understood`: the call reached the gateway and may have done its
+ * work; what it said could not be read. `outcome_unknown`: the call was sent
+ * into silence, such as a dropped connection or a worker shut down
+ * mid-flight, and nobody on this side knows whether it arrived.
  */
 export declare const CALL_DID_NOT_REACH_US = "call_did_not_reach_us";
 export declare const ANSWER_NOT_UNDERSTOOD = "answer_not_understood";
 export declare const OUTCOME_UNKNOWN = "outcome_unknown";
 /**
- * What is thrown where a route has no failure branch to hand a merchant back.
- *
- * Three of this client's calls answer with a document or with nothing at all —
- * publishing a card, reading one order, listing them — so a call that produced
- * no document has nowhere in the contract to be returned. It is thrown, and
- * this is what it is thrown as.
+ * What is thrown where a call has no failure branch to return: publishing a
+ * card, reading one order, listing orders.
  *
- * It carries what the returned failures carry, because the two are the same
- * facts about the same calls and a merchant should not have to learn a second
- * vocabulary for the half of them that throws. `code` is the gateway's own word
- * where the gateway refused in words we recognise, and otherwise one of the
- * three this package produces — `call_did_not_reach_us`, `answer_not_understood`,
- * `outcome_unknown`. `failedCall` below makes that same choice for the order
- * calls, so a refusal has one name on both roads. `route` is the call it
- * happened on, under the name the
- * contract's own table gives it, so a `catch` can say which of three it was
- * without reading the sentence.
+ * `code` is the gateway's own code where it refused in words this package
+ * recognises, and otherwise `call_did_not_reach_us`, `answer_not_understood`
+ * or `outcome_unknown`. `route` names the call as the contract's route table
+ * does, so a `catch` can tell the calls apart without reading the message.
  *
- * What is not this: a client built wrong. A missing key, a `baseUrl` that is
- * not an address, a handler registered twice and a kind nothing delivers are
- * mistakes in the merchant's own code, made before anything left the process,
- * and they stay `TypeError`. A merchant catching this class is catching calls
- * that went out.
+ * A client built wrong (a missing key, a `baseUrl` that is not an address, a
+ * handler registered twice) throws `TypeError` instead, before anything leaves
+ * the process.
  */
 export declare class AgentifyError extends Error {
     /** Why the call did not go through, for the code that branches on it. */
@@ -365,15 +246,9 @@ export declare class AgentifyError extends Error {
     /** The call it happened on, named as the contract's route table names it. */
     readonly route: string;
     /**
-     * Whether making the same call again could get past this.
-     *
-     * Here for the same reason the code is: the calls that throw and the calls
-     * that return are the same calls failing the same ways, and a merchant who
-     * had to work out from a `catch` what a returned error would have told them
-     * outright is being charged twice for one lesson. The gateway's own answer
-     * where the gateway refused in words, and true where nothing readable came
-     * back — which is a statement about what this package knows, not a promise
-     * that the call will work.
+     * Whether making the same call again could get past this: the gateway's own
+     * answer where it refused in words, and true where nothing readable came
+     * back, which says what this package knows, not that the call will work.
      */
     readonly retryable: boolean;
     constructor(code: string, route: string, message: string, retryable: boolean);