@nuanu-ai/agentify 0.2.4

package/dist/client.js

@@ -0,0 +1,520 @@
+/**
+ * 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 { callRoute, REACH, whatIsKnown, } from "./transport.js";
+import { droppedFieldWarning, REGISTERED_AS, reportSafely, startWorker, } from "./worker.js";
+/** The word for the reporter, which nothing on the wire carries. */
+const PROBLEM = "problem";
+/**
+ * The words `on` accepts, as a map over the kinds themselves.
+ *
+ * A merchant working outside TypeScript, or one who wrote `orders`, would
+ * otherwise register a handler that is never called and hear nothing about it.
+ * Written as a mapped type so that a kind the stream grows and this file
+ * forgets stops it compiling.
+ */
+const HANDLER_KINDS = Object.freeze({
+    order: true,
+    quote: true,
+    event: true,
+    problem: true,
+});
+/**
+ * Every word `on` accepts, in the order this file lists them, for the sentence
+ * a merchant reads when they wrote one that is not on the list.
+ */
+const everyKind = () => Object.keys(HANDLER_KINDS).map((kind) => `'${kind}'`);
+/** The words that answer something on the stream, which `problem` does not. */
+const streamKinds = () => Object.values(REGISTERED_AS);
+/**
+ * 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 const CALL_DID_NOT_REACH_US = "call_did_not_reach_us";
+export const ANSWER_NOT_UNDERSTOOD = "answer_not_understood";
+export const OUTCOME_UNKNOWN = "outcome_unknown";
+const CODE_FOR = {
+    [REACH.NOT_RECEIVED]: CALL_DID_NOT_REACH_US,
+    [REACH.ANSWERED]: ANSWER_NOT_UNDERSTOOD,
+    [REACH.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 class AgentifyError extends Error {
+    /** Why the call did not go through, for the code that branches on it. */
+    code;
+    /** The call it happened on, named as the contract's route table names it. */
+    route;
+    /**
+     * 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.
+     */
+    retryable;
+    constructor(code, route, message, retryable) {
+        super(message);
+        this.name = "AgentifyError";
+        this.code = code;
+        this.route = route;
+        this.retryable = retryable;
+    }
+}
+/**
+ * What an order call hands back when it produced no answer of its own.
+ *
+ * `code` is the gateway's own word where the gateway refused in words we
+ * recognise, and otherwise one of the three this package produces for a
+ * silence. The two halves of the answer have to say the same thing: a refusal
+ * quoted in the message and filed under `answer_not_understood` is the message
+ * arguing with the code, and the code is the half a program reads. It is the
+ * same choice `document` makes for the calls that throw, so one refusal has one
+ * name whether the merchant catches it or branches on it.
+ *
+ * `retryable` says whether calling again could change the outcome, and it has
+ * two sources because there are two situations. Where the gateway refused in
+ * words, the answer is the gateway's own: it is the side that knows whether
+ * the door is shut or was merely shut a moment ago, and this package does not
+ * improve on what it was told. Where no answer arrived, or none that could be
+ * read, there is nothing to defer to and the answer is true — none of those
+ * three is a state of the order, and none will still be true in a minute if a
+ * network settled or a proxy went away.
+ *
+ * The fallback is `true` and not `false` on purpose. It is reached only when
+ * this package could not read an answer, which is a statement about our
+ * knowledge and not about the order; saying "do not call again" there would be
+ * this package inventing the one fact the merchant came for.
+ *
+ * The sentence about repeating safely is added where two things hold at once:
+ * the contract says the call may be repeated — delivering is idempotent by the
+ * order's identifier, and taking an order on happens again on every
+ * redelivery, while refusing is documented as neither — and calling again
+ * could get anywhere. Offering "you may safely repeat this" under a refusal
+ * that will answer the same way for ever is an invitation to do something
+ * pointless, and it reads as encouragement.
+ */
+const failedCall = (repeatIsSafe, failure) => {
+    const retryable = failure.refusal?.retryable ?? true;
+    return {
+        code: failure.refusal?.code ?? CODE_FOR[failure.reach],
+        message: repeatIsSafe && retryable
+            ? `${whatIsKnown(failure)}: ${failure.reason} — this call may be made again without doing its work twice`
+            : `${whatIsKnown(failure)}: ${failure.reason}`,
+        retryable,
+    };
+};
+/**
+ * The reporter a client gets when the merchant registered none.
+ *
+ * A library writing to the console is a small rudeness. A worker that stopped
+ * on a contract mismatch and said nothing to anybody is a merchant learning
+ * about it from a buyer, and between the two this is the cheaper one.
+ */
+const reportToConsole = (problem) => {
+    // The exception goes out beside the sentence rather than inside it. The
+    // message already carries what the exception says; what it cannot carry is
+    // the stack, and the stack is the whole of what a merchant debugging their
+    // own handler is looking for.
+    if (problem.cause === undefined) {
+        console.error(`[agentify] ${problem.kind}: ${problem.message}`);
+        return;
+    }
+    console.error(`[agentify] ${problem.kind}: ${problem.message}`, problem.cause);
+};
+/**
+ * What a key says about the world it was issued in, read from its own prefix.
+ *
+ * ADR-0020 is what makes reading it here legitimate rather than clever: every
+ * key carries the environment it was issued in as its prefix, and whoever holds
+ * a key can read that prefix. So a worker learns which deployment it joined
+ * without a field on the wire, a line in a response document or a step in a
+ * handshake — none of which this adds.
+ *
+ * The rule's home is `packages/core/src/deployment/environment.ts`, where
+ * `keyPrefixFor` writes these prefixes and `environmentOfKeyPrefix` reads them.
+ * The two strings below are a second copy of that rule and not a use of it,
+ * because this package cannot depend on that module at runtime: it is private
+ * to the workspace and unpublished, and the dependency tree a merchant installs
+ * is a recorded decision (ADR-0003 §8) that does not grow to reach it.
+ *
+ * A copy is a thing that drifts, and these two must not. What holds them
+ * together is `which-world.test.ts`: it builds its keys out of core's own
+ * `keyPrefixFor` and asserts the sentences written here, so a prefix changed on
+ * one side and not the other fails `pnpm test` instead of going quiet in
+ * somebody's log. That import is dev-time and reaches nothing published — the
+ * tarball ships `dist`, and the build leaves the tests out. Changing either
+ * side means changing both in the same commit.
+ *
+ * A key matching neither prefix says nothing at all, which is the third case
+ * ADR-0020 names: a key issued before the prefix existed, or one that is not
+ * ours. There is nothing to fall back to. Guessing is wrong in both directions
+ * — telling a merchant their money is play when it is real, or the other way
+ * round — and no line at all is better than a wrong claim about whose money is
+ * at stake.
+ */
+const WHAT_THE_KEY_SAYS = Object.freeze({
+    csk_test_: "with a test key: the money there is not real",
+    csk_live_: "with a live key: the money there is real",
+});
+const whatTheKeySays = (apiKey) => Object.entries(WHAT_THE_KEY_SAYS).find(([prefix]) => apiKey.startsWith(prefix))?.[1];
+const keyOf = (apiKey) => {
+    if (typeof apiKey !== "string" || apiKey.trim() === "") {
+        throw new TypeError("createClient needs the merchant's API key, and was given none — check that the environment variable holding it is set where this process can read it");
+    }
+    return apiKey;
+};
+/**
+ * The address as given, checked as far as it can be checked without using it.
+ *
+ * A value that is not an address is refused at once: it will not become one
+ * later, and the line that produced it is the line to fix. An address that was
+ * not given at all is a different matter, and it is kept as the sentence that
+ * will be raised by the first call that needs it — see `baseUrl` above.
+ */
+const addressOf = (baseUrl) => {
+    if (baseUrl === undefined)
+        return "";
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new TypeError(`baseUrl is not an address: ${JSON.stringify(baseUrl)}`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new TypeError(`baseUrl is not an http address: ${JSON.stringify(baseUrl)} — the gateway is reached over https, and over http only where the two run on one machine`);
+    }
+    return baseUrl;
+};
+/** Refuses to compile if a kind is added to `Handlers` and not registered here. */
+const assertEveryKindIsRegistered = (kind) => {
+    throw new TypeError(`on() has no place to put a handler for ${JSON.stringify(kind)}`);
+};
+export const createClient = (options) => {
+    const gateway = {
+        apiKey: keyOf(options.apiKey),
+        baseUrl: addressOf(options.baseUrl),
+    };
+    const reachable = () => {
+        if (gateway.baseUrl === "") {
+            throw new TypeError("this client has no gateway address: pass baseUrl to createClient — https://test.agentify.ad while you are building, https://app.agentify.ad once you are live. There is no default on purpose: which of the two you talk to is the difference between a sale and a rehearsal, and an address this package chose for you would point somebody's production at the wrong one without a word");
+        }
+    };
+    /**
+     * The handlers, and the loop that dispatches to them.
+     *
+     * The registry belongs to the client and not to any one loop, which is what
+     * lets a merchant stop and start again on the handlers they already
+     * registered. `worker` is the loop currently running, if one is; it also
+     * ends on its own when the gateway turns out to speak another dialect, which
+     * is why every reader asks it whether it is still running rather than
+     * assuming that a worker that exists is a worker that polls.
+     */
+    const registry = { problem: reportToConsole };
+    const registered = new Set();
+    let worker;
+    /** Set while a stop is in flight, and shared by every caller of stop(). */
+    let stopping;
+    /** Whether the world this client works in has already been said. */
+    let worldIsSaid = false;
+    /**
+     * The one line this package writes uninvited: where this worker is pointed
+     * and whether the money there is real.
+     *
+     * Once per client and not once per start. The key cannot change under a
+     * client and neither can the address, so a second line would carry no second
+     * fact — and a supervisor that stops and starts a worker on a schedule would
+     * turn it into the kind of line people learn to scroll past. The question is
+     * closed even where the answer is silence: a key naming no environment is
+     * asked about once and never again.
+     *
+     * It goes to the console because that is where this package already writes
+     * when nobody gave it anywhere else to write, and at the informational level
+     * because that is what it is. `console.error` would put it in front of every
+     * log collector as a fault on a worker that has just started correctly, which
+     * is a false alarm and the one thing this line must never look like.
+     *
+     * It is not a `WorkerProblem`: the merchant's reporter is for what went
+     * wrong, and a process counting problems should not have to filter out the
+     * one that means everything is fine.
+     */
+    const sayWhichWorld = () => {
+        if (worldIsSaid)
+            return;
+        worldIsSaid = true;
+        const words = whatTheKeySays(gateway.apiKey);
+        if (words === undefined)
+            return;
+        console.info(`[agentify] worker started against ${gateway.baseUrl} ${words}`);
+    };
+    const orderCall = async (route, orderId, body) => {
+        reachable();
+        if (route === "deliver_order") {
+            // The road the worker's own warning does not cover, and the one a
+            // merchant delivering asynchronously takes. See `droppedFieldWarning`:
+            // the field goes no further than the gateway's parse, and without this
+            // the merchant's handler had no way to learn that what it sent is not
+            // what went out. A warning and not a refusal — the rest of the delivery
+            // is good, and the call is the merchant's to make.
+            const dropped = droppedFieldWarning(orderId, body);
+            if (dropped !== null)
+                reportSafely(registry.problem, dropped);
+        }
+        const answer = await callRoute(gateway, route, { path: { order_id: orderId }, body });
+        return answer.ok
+            ? answer.document
+            : { ok: false, error: failedCall(route === "deliver_order", answer.failure) };
+    };
+    const acceptCall = async (orderId, acceptance) => {
+        reachable();
+        const answer = await callRoute(gateway, "accept_order", {
+            path: { order_id: orderId },
+            body: acceptance ?? {},
+        });
+        // Accepting the same order again is ordinary: an order is taken on afresh
+        // on every redelivery, so a repeat does no work twice.
+        return answer.ok ? answer.document : { ok: false, error: failedCall(true, answer.failure) };
+    };
+    /**
+     * The calls one order answers to, closed over that order's identifier and
+     * over this client.
+     *
+     * This closure is the whole mechanism. The identifier is captured here, once,
+     * at the moment the order was read — off the stream or out of our record —
+     * and never travels back through a merchant's hands, where it could be the
+     * wrong string. What holds the client is the same closure: `orderCall` and
+     * `acceptCall` above are this client's, so an order kept in a merchant's map
+     * for four hours still knows which gateway to call and with whose key.
+     */
+    const callsFor = (orderId) => ({
+        delivered: (delivery) => ({ delivered: delivery }),
+        refused: (refusal) => ({ refused: refusal }),
+        accepted: (acceptance) => ({ accepted: acceptance ?? {} }),
+        deliver: (delivery) => orderCall("deliver_order", orderId, delivery),
+        refuse: (refusal) => orderCall("refuse_order", orderId, refusal),
+        accept: (acceptance) => acceptCall(orderId, acceptance),
+    });
+    const withCalls = (order) => Object.assign({}, order, callsFor(order.id));
+    const askedWithAnswers = (question) => Object.assign({}, question, {
+        available: (price, asOf) => ({
+            available: true,
+            price,
+            as_of: asOf ?? new Date().toISOString(),
+        }),
+        unavailable: (asOf) => ({
+            available: false,
+            as_of: asOf ?? new Date().toISOString(),
+        }),
+    });
+    const document = async (route, options_) => {
+        reachable();
+        const answer = await callRoute(gateway, route, options_);
+        if (!answer.ok) {
+            const { failure } = answer;
+            // The gateway's own word wherever it wrote one, and one of ours only
+            // where it did not. A refusal we recognise carries the reason a merchant
+            // can act on, and replacing it with "we could not read the answer" would
+            // throw away the one thing they came here for. The same holds for its
+            // answer about calling again — this is the rule `failedCall` applies for
+            // the calls that return, applied here so the two roads agree.
+            throw new AgentifyError(failure.refusal?.code ?? CODE_FOR[failure.reach], failure.route, failure.reason, failure.refusal?.retryable ?? true);
+        }
+        return answer.document;
+    };
+    return {
+        catalog: {
+            publish: (card) => document("publish_card", { body: card }),
+        },
+        orders: {
+            forId: (orderId) => ({ id: orderId, ...callsFor(orderId) }),
+            get: async (orderId) => withCalls(await document("get_order", { path: { order_id: orderId } })),
+            list: async (query) => {
+                const listed = await document("list_orders", {
+                    // The wire carries the two words rather than a boolean, because a
+                    // query string carries text. The merchant writes the boolean their
+                    // language has and this is where the two meet.
+                    query: query?.open === undefined ? {} : { open: query.open ? "true" : "false" },
+                });
+                return listed.orders.map((order) => withCalls(order));
+            },
+        },
+        on(kind, handler) {
+            if (!Object.hasOwn(HANDLER_KINDS, kind)) {
+                throw new TypeError(`on() was given ${JSON.stringify(kind)}, which is not a kind this stream carries: the kinds are ${everyKind().join(", ")}`);
+            }
+            if (registered.has(kind)) {
+                throw new TypeError(`on('${kind}') was called twice on one client: the second handler would silently replace the first, and one message goes to one handler`);
+            }
+            // Narrowed off the generic so that the switch below is exhaustive over
+            // the kinds rather than over whatever this call was instantiated with.
+            const which = kind;
+            switch (which) {
+                case "order": {
+                    // The merchant's handler is wrapped rather than registered as it
+                    // stands: the loop reads a plain order off the envelope, and the
+                    // calls that close it are this client's to attach.
+                    const answering = handler;
+                    registry.order = (arrived) => answering(withCalls(arrived));
+                    break;
+                }
+                case "quote": {
+                    const answering = handler;
+                    registry.quote = (asked) => answering(askedWithAnswers(asked));
+                    break;
+                }
+                case "event": {
+                    registry.event = handler;
+                    break;
+                }
+                case "problem": {
+                    registry.problem = handler;
+                    break;
+                }
+                default:
+                    return assertEveryKindIsRegistered(which);
+            }
+            // Written down only once everything that could refuse this call has
+            // passed, so a call that threw leaves no trace and the same call made
+            // again succeeds.
+            registered.add(which);
+        },
+        start: async () => {
+            reachable();
+            if (stopping !== undefined) {
+                throw new TypeError("this client is being stopped: await that stop() before starting it again, or the loop being started would be racing the one going away");
+            }
+            if (worker?.running() === true) {
+                throw new TypeError("this client is already started: a second loop would open a second long poll for one merchant, and an envelope handed to one of them is not handed to the other");
+            }
+            // Read off the vocabulary rather than written out, so a kind the stream
+            // grows is counted as an answer here without anybody remembering to add
+            // it — a process that answered only the new kind would otherwise be
+            // refused a start on the grounds that it answers nothing.
+            if (!streamKinds().some((kind) => registry[kind] !== undefined)) {
+                throw new TypeError(`this client has nothing registered to answer with: register at least one of ${streamKinds()
+                    .map((kind) => `on('${kind}')`)
+                    .join(", ")} before start(), or the loop would take work off the queue that nobody answers`);
+            }
+            // After every refusal above and before the loop: a start that threw
+            // opened nothing, and a line saying otherwise would be the first thing a
+            // merchant read on the way to an exception.
+            sayWhichWorld();
+            worker = startWorker(gateway, registry);
+        },
+        stop: async () => {
+            const owned = worker;
+            // A client that was never started has nothing to stop, and saying so by
+            // returning is what lets a shutdown routine call this unconditionally.
+            if (owned === undefined)
+                return;
+            // One promise for every caller — a shutdown routine and a signal handler
+            // both calling stop() is ordinary — and what it buys is the bookkeeping
+            // rather than the waiting. Each of them would wait out the same loop
+            // either way, because the worker's own stop() awaits the one promise the
+            // loop ends on. What must happen once is the clearing below: two of them
+            // racing it is two of them deciding whether this client still has a
+            // worker, and the last one to answer wins.
+            stopping ??= owned.stop().finally(() => {
+                if (worker === owned)
+                    worker = undefined;
+                stopping = undefined;
+            });
+            await stopping;
+        },
+    };
+};

package/dist/contract.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which contract this package speaks, and whether it understands another.
+ *
+ * It sits in a file of its own because both ends of the package need it and
+ * neither should reach through the other: the worker checks the version on the
+ * answer to every poll, and `index.ts` publishes the same check to a merchant
+ * who wants to make it themselves.
+ */
+/** The contract version this SDK talks in. */
+export declare const contractVersion = "2";
+/**
+ * Whether the SDK understands a contract of the given version. The gateway
+ * names its own version in the response, the merchant's worker checks it with
+ * this function and fails at startup rather than on the first order, where a
+ * divergence of dialects costs the buyer money.
+ */
+export declare function speaksContract(version: string): boolean;

package/dist/contract.js

@@ -0,0 +1,20 @@
+/**
+ * Which contract this package speaks, and whether it understands another.
+ *
+ * It sits in a file of its own because both ends of the package need it and
+ * neither should reach through the other: the worker checks the version on the
+ * answer to every poll, and `index.ts` publishes the same check to a merchant
+ * who wants to make it themselves.
+ */
+import { CONTRACT_VERSION } from "@nuanu-ai/agentify-contracts";
+/** The contract version this SDK talks in. */
+export const contractVersion = CONTRACT_VERSION;
+/**
+ * Whether the SDK understands a contract of the given version. The gateway
+ * names its own version in the response, the merchant's worker checks it with
+ * this function and fails at startup rather than on the first order, where a
+ * divergence of dialects costs the buyer money.
+ */
+export function speaksContract(version) {
+    return version === CONTRACT_VERSION;
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Agentify merchant SDK: what someone else'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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export type { Acceptance, CallError, Card, CardInput, Delivery, Fulfillment, HandlerAnswer, Money, Order, OrderCallResponse, OrderCallResult, OrderEvent, OrderList, OrderStatus, OrderWithStatus, Problem, PublishResult, QuotePurpose, QuoteRequest, QuoteResponse, Refusal, RefusalCode, SalePrice, } from "@nuanu-ai/agentify-contracts";
+export { CARD_REJECTED, ORDER_EVENT_TYPES, RECOMMENDED_REFUSAL_CODES, } from "@nuanu-ai/agentify-contracts";
+export type { CardCheck } from "./check-card.js";
+export { checkCard } from "./check-card.js";
+export type { AgentifyClient, CatalogNamespace, ClientOptions, HandlerKind, Handlers, LiveOrder, LiveOrderWithStatus, LiveQuoteRequest, OrderCalls, OrderHandle, OrderHandler, OrdersNamespace, QuoteCalls, QuoteHandler, } from "./client.js";
+export { AgentifyError, ANSWER_NOT_UNDERSTOOD, CALL_DID_NOT_REACH_US, createClient, OUTCOME_UNKNOWN, } from "./client.js";
+export { contractVersion, speaksContract } from "./contract.js";
+export type { Delivered, EventHandler, ProblemReporter, WorkerProblem, WorkerProblemKind, } from "./worker.js";
+export { WORKER_PROBLEM_KINDS } from "./worker.js";

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * The Agentify merchant SDK: what someone else'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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export { CARD_REJECTED, ORDER_EVENT_TYPES, RECOMMENDED_REFUSAL_CODES, } from "@nuanu-ai/agentify-contracts";
+export { checkCard } from "./check-card.js";
+export { AgentifyError, ANSWER_NOT_UNDERSTOOD, CALL_DID_NOT_REACH_US, createClient, OUTCOME_UNKNOWN, } from "./client.js";
+export { contractVersion, speaksContract } from "./contract.js";
+export { WORKER_PROBLEM_KINDS } from "./worker.js";