@nuanu-ai/agentify 0.2.4

package/dist/client.d.ts

@@ -0,0 +1,377 @@
+/**
+ * The client a merchant's engineer holds: a catalog, an order desk, and one
+ * place to say what this process answers.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * `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.
+ */
+import type { Acceptance, 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.
+     */
+    readonly apiKey: string | undefined;
+    /**
+     * Where the gateway is: `https://test.agentify.ad` while the merchant
+     * is building, `https://app.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.
+     *
+     * 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.
+     */
+    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.
+ */
+export interface OrderCalls {
+    /** The goods, as the handler's answer. Building one sends nothing. */
+    delivered(delivery: Delivery): HandlerAnswer;
+    /** 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.
+     */
+    accepted(acceptance?: Acceptance): 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.
+     */
+    deliver(delivery: Delivery): Promise<OrderCallResponse>;
+    /** A final "this cannot be delivered" for an order already taken on. */
+    refuse(refusal: Refusal): Promise<OrderCallResponse>;
+    /** Takes the order on from outside a handler. Repeats are ordinary. */
+    accept(acceptance?: Acceptance): 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.
+ */
+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.
+ */
+export type LiveOrder = Order & OrderCalls;
+/** The same, read back from our record, so it also says where the order stands. */
+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.
+ */
+export interface QuoteCalls {
+    available(price: Money, asOf?: string): QuoteResponse;
+    unavailable(asOf?: string): QuoteResponse;
+}
+/** A price question, with the two answers it can be given. */
+export type LiveQuoteRequest = QuoteRequest & QuoteCalls;
+/** What the merchant's code does with one paid order. */
+export type OrderHandler = (order: LiveOrder) => HandlerAnswer | Promise<HandlerAnswer>;
+/** 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.
+ */
+export interface Handlers {
+    order: OrderHandler;
+    quote: QuoteHandler;
+    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.
+ */
+type IsUnion<Kind, Each = Kind> = Kind extends unknown ? [Each] extends [Kind] ? false : true : never;
+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.
+     *
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    get(orderId: string): Promise<LiveOrderWithStatus>;
+    /**
+     * Orders and the states they are in; with `open`, only those still owed
+     * something.
+     *
+     * The list is what a process reads after a restart: every order it still
+     * owes a delivery for, each one able to be delivered or refused on the spot.
+     */
+    list(query?: {
+        readonly open?: boolean;
+    }): Promise<readonly LiveOrderWithStatus[]>;
+}
+export interface AgentifyClient {
+    readonly catalog: CatalogNamespace;
+    readonly orders: OrdersNamespace;
+    /**
+     * Registers what this process answers for one kind.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    on<Kind extends HandlerKind>(kind: Kind, handler: IsUnion<Kind> extends true ? never : Handlers[Kind]): void;
+    /**
+     * Opens the subscription and returns once it is running.
+     *
+     * 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.
+     */
+    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.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    stop(): Promise<void>;
+}
+/**
+ * The three codes an order call comes back under when the gateway produced no
+ * answer this package can read.
+ *
+ * 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.
+ */
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare class AgentifyError extends Error {
+    /** Why the call did not go through, for the code that branches on it. */
+    readonly code: string;
+    /** 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.
+     */
+    readonly retryable: boolean;
+    constructor(code: string, route: string, message: string, retryable: boolean);
+}
+export declare const createClient: (options: ClientOptions) => AgentifyClient;
+export {};