@nuanu-ai/agentify 0.6.0 → 0.7.0

package/README.md

@@ -1,9 +1,9 @@
 # `@nuanu-ai/agentify`
 
-Agentify puts a merchant's existing products where AI agents buy. Each product
-gets a card in an agent-facing storefront and a paid address of its own,
-`/x402/<item>/purchase`, where an agent pays for it with the x402 payment
-protocol. The buyer pays into the merchant's own payout contract, which nobody
+Agentify publishes a merchant's existing products in its own catalogue, which
+AI agents read and buy from. Each product gets a card there and a paid address
+of its own, `/x402/<item>/purchase`, where an agent pays for it with the x402
+payment protocol. The buyer pays into the merchant's own payout contract, which nobody
 owns and nobody can redirect. It keeps the money until it is paid out, which
 the merchant can do at any time, and then sends 99.9% to the merchant's wallet
 and 0.1% to Agentify ([Money](https://agentify.ad/docs/money)).
@@ -14,6 +14,15 @@ each order with the goods or with a refusal. Nothing of the merchant's has to
 be reachable from outside — the process opens that connection itself, so no
 public address and no open port are needed.
 
+## Before the first call
+
+The key comes from the test channel's dashboard at
+[test.agentify.ad/dashboard](https://test.agentify.ad/dashboard): sign in with
+your email, and on API Keys issue a key, which is shown once. Before your first
+card can be published, the dashboard also needs the seller name buyers will
+see and, in Settings, the wallet your share of each sale is paid out to; a
+publish without them is refused with findings that name what is missing.
+
 ## Install
 
 ```sh
@@ -23,7 +32,7 @@ npm install @nuanu-ai/agentify
 Node.js 24 or newer is required. What arrives with it is our own contracts
 package and zod underneath that, and nothing else.
 
-## The address you give it is the world you are in
+## Test or live: the address decides
 
 ```ts
 import { createClient } from '@nuanu-ai/agentify'
@@ -34,12 +43,12 @@ const agentify = createClient({
 })
 ```
 
-There are two addresses, one per world. At `https://test.agentify.ad` you
+There are two channels, one address each. At `https://test.agentify.ad` you
 build: payments settle on a test chain and the money there is not real. At
-`https://agentify.ad` you sell, and it is. A key issued in one does not
-open the other, and the key says which one you are holding: `csk_test_` for the
+`https://agentify.ad` you sell, and it is. A key issued on one does not open
+the other, and the key says which one you are holding: `csk_test_` for the
 first, `csk_live_` for the second. This package picks neither address for you,
-and the worker's first log line names the one it started against and whether
+and your process's first log line names the one it started against and whether
 the money there is real.
 
 ## A card, and the handler that fills the orders
@@ -88,12 +97,39 @@ yours, so its `id` is also its idempotency key: pass it into your own delivery
 system and the second arrival hands back the first result instead of delivering
 again.
 
-A call that can fail hands the failure back rather than throwing it, in one
-envelope: `ok` says which it was, and a failure carries a code, a sentence a
-person can read, and whether repeating could change the outcome. A card we
-would not publish carries its findings under `problems`, and what no envelope
-can carry — a call that reached nothing at all — is thrown as an `AgentifyError`
-under those same codes.
+A card we would not publish comes back as `ok: false`, with a code, a sentence a
+person can read, whether repeating could change the outcome, and its findings
+under `problems`. `deliver`, `refuse`, `accept` and `close` hand every failure back in
+that same envelope, and throw only on a client built with no address. `catalog.publish`, `orders.get` and
+`orders.list` throw an `AgentifyError` whenever no publish result or order came
+back — a refused key included — with the same codes, the flag and the call it
+happened on.
+
+To stop Agentify accepting deliveries for an order, call its `close` method.
+The optional message is your statement to the buyer, which their agent reads
+as your words: plain text of at most 2000 characters, with no markup and no
+control characters. A message that breaks that rule is refused before anything
+is recorded.
+
+```ts
+const order = await agentify.orders.get(orderId)
+const closed = await order.close({ message: 'Please contact our shop to continue.' })
+```
+
+Closing cannot be undone, moves no money and confirms no refund; you and the
+buyer handle any refund or other agreement outside Agentify. A repeat of the
+call keeps the first closure time and message. Two refusals leave the order as
+it was: `fulfillment_complete` where the goods were delivered or the parcel's
+shipment is recorded, and `nothing_to_close` where the order ended with
+nothing charged.
+
+An order read back carries `payment_status` for its original payment and
+`merchant_closure` for your closure. Closing does not cancel a charge Agentify
+had already sent to the facilitator. If that charge completes after you
+closed, you receive `order.unfulfilled` with the reason `paid_after_closure`,
+and the order stays on `orders.list({ open: true })` until you close it again;
+that second closure records its own time and message. The whole rule is on
+[Orders](https://agentify.ad/docs/orders#closing-fulfillment).
 
 ## The check that needs no key
 
@@ -107,15 +143,16 @@ check is exported as `checkCard`, for cards assembled in code rather than kept
 in files.
 
 That is one half of checking yourself. The other half — whether your handler
-holds against a real order, and against that same order arriving twice — is a
-test purchase on the test site rather than anything this command can do; the
-[quickstart](https://agentify.ad/docs/quickstart) walks you through one.
+holds against a real order — is a test purchase you make yourself on the test
+channel, buying your own card with an x402 client and test USDC; the
+[quickstart](https://agentify.ad/docs/quickstart#_6-make-your-first-test-purchase)
+walks you through one.
 
 ## Where the rest of it is written
 
 The merchant documentation is public. [The first test
 sale](https://agentify.ad/docs/quickstart) walks from an empty project to
-a test purchase your side runs end to end. Beside it are [the product
+a test purchase you make yourself. Beside it are [the product
 card](https://agentify.ad/docs/cards) field by field, [orders and fulfillment
 modes](https://agentify.ad/docs/orders) for delivering later rather than in
 the answer to the purchase, and [what can go
@@ -128,11 +165,12 @@ than the engineer.
 ## Versions
 
 This is an early `0.x` pilot surface and the names in it can still change. The
-SDK and the gateway agree on a contract version, and a worker whose version the
-gateway does not share stops before it takes an order. During the pilot that
-version does not move with every change, so a release older than the gateway
-can read a word it does not know as a failure rather than stop: keep the
-package current. Register `agentify.on('problem', …)`, which is where you
+SDK and Agentify agree on a contract version, and a process whose version
+Agentify does not share stops before it takes an order. During the pilot that
+version does not move with every change, so a release older than Agentify can
+read a word it does not know as a failure rather than stop: keep the package
+current. What changed in each release is in the
+[changelog](https://github.com/nuanu-ai/agentify/blob/main/packages/sdk/CHANGELOG.md). Register `agentify.on('problem', …)`, which is where you
 hear about that and about everything else that did not get through.
 
 ## License

package/dist/client.d.ts

@@ -22,7 +22,7 @@
  * that went out and produced no answer its route can carry is an
  * `AgentifyError` under the same codes.
  */
-import type { 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, OrderCloseRequest, OrderCloseResponse, OrderWithStatus, PublishResult, QuoteRequest, QuoteResponse, Refusal } from "@nuanu-ai/agentify-contracts";
 import { type EventHandler, type ProblemReporter, type StreamHandlerKind } from "./worker.js";
 export interface ClientOptions {
     /**
@@ -78,6 +78,26 @@ export interface OrderCalls {
     refuse(refusal: Refusal): Promise<OrderCallResponse>;
     /** Takes the order on from outside a handler. Repeating it is harmless. */
     accept(): Promise<OrderAcceptResponse>;
+    /**
+     * Stops future fulfillment through Agentify for this order. The message is
+     * your statement to the buyer, plain text of at most 2000 characters, which
+     * their agent reads as your words; Agentify confirms no refund or agreement.
+     * Closing cannot be undone, and it causes no new charge.
+     *
+     * Calling it again succeeds and keeps the first closure's time and message,
+     * with one exception. Closing cancels no payment: a payment Agentify had
+     * already asked the facilitator to execute may still go through after you
+     * close. If it does, you receive `order.unfulfilled` with reason
+     * `paid_after_closure`, the order is on `orders.list({ open: true })`, and
+     * closing it again then records that closure's own time and message and
+     * takes it off the list.
+     *
+     * Resolves to `{ ok: true }`, or to `ok: false` with an `error`, leaving the
+     * order unchanged: `fulfillment_complete` where its goods were delivered or
+     * its parcel's shipment is recorded, and `nothing_to_close` where it ended
+     * without a charge and holds nothing for its buyer. Neither is retryable.
+     */
+    close(options?: OrderCloseRequest): Promise<OrderCloseResponse>;
 }
 /**
  * The least an order can be and still be answered: its identifier and the
@@ -162,7 +182,8 @@ export interface OrdersNamespace {
     /**
      * 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
+     * an unfulfilled paid order, one delivered but never paid for, and a closed
+     * one whose payment completed after you closed it. 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.
@@ -197,7 +218,6 @@ export interface AgentifyClient {
      * answer.
      */
     start(): Promise<void>;
-    /**
     /**
      * Stops the subscription and waits for it to finish. Safe to call twice,
      * and on a client that was never started. Handlers stay registered.
@@ -253,5 +273,21 @@ export declare class AgentifyError extends Error {
     readonly retryable: boolean;
     constructor(code: string, route: string, message: string, retryable: boolean);
 }
+/**
+ * Builds the client a merchant's code publishes cards and answers orders with,
+ * against one gateway: `https://test.agentify.ad` while building,
+ * `https://agentify.ad` once live, named in `baseUrl`.
+ *
+ * Building it calls nothing. It throws a `TypeError` at once when `apiKey` is
+ * missing or blank and when `baseUrl` is given but is not an http or https
+ * address. Left without `baseUrl`, it is still built, and every call that has to
+ * reach the gateway throws a `TypeError` naming both addresses, since there is
+ * no default to fall back on. Whether the key opens that gateway is learned at
+ * the first call.
+ *
+ * Returns the client: `catalog.publish` for cards, `orders` to read and close
+ * orders, `on` to register handlers, and `start` and `stop` for the
+ * subscription that brings orders, price questions and order events in.
+ */
 export declare const createClient: (options: ClientOptions) => AgentifyClient;
 export {};

package/dist/client.js

@@ -101,7 +101,7 @@ export class AgentifyError extends Error {
  * statement about what this package knows, not about the order.
  *
  * The sentence saying the call may be repeated safely is added only where the
- * call is idempotent (delivering, accepting; not refusing) and repeating it
+ * call is idempotent (delivering, accepting or closing; not refusing) and repeating it
  * could get anywhere.
  */
 const failedCall = (repeatIsSafe, failure) => {
@@ -175,6 +175,22 @@ const addressOf = (baseUrl) => {
 const assertEveryKindIsRegistered = (kind) => {
     throw new TypeError(`on() has no place to put a handler for ${JSON.stringify(kind)}`);
 };
+/**
+ * Builds the client a merchant's code publishes cards and answers orders with,
+ * against one gateway: `https://test.agentify.ad` while building,
+ * `https://agentify.ad` once live, named in `baseUrl`.
+ *
+ * Building it calls nothing. It throws a `TypeError` at once when `apiKey` is
+ * missing or blank and when `baseUrl` is given but is not an http or https
+ * address. Left without `baseUrl`, it is still built, and every call that has to
+ * reach the gateway throws a `TypeError` naming both addresses, since there is
+ * no default to fall back on. Whether the key opens that gateway is learned at
+ * the first call.
+ *
+ * Returns the client: `catalog.publish` for cards, `orders` to read and close
+ * orders, `on` to register handlers, and `start` and `stop` for the
+ * subscription that brings orders, price questions and order events in.
+ */
 export const createClient = (options) => {
     const gateway = {
         apiKey: keyOf(options.apiKey),
@@ -256,6 +272,14 @@ export const createClient = (options) => {
         },
         deliver: (delivery) => orderCall("deliver_order", orderId, delivery),
         refuse: (refusal) => orderCall("refuse_order", orderId, refusal),
+        close: async (options = {}) => {
+            reachable();
+            const answer = await callRoute(gateway, "close_order", {
+                path: { order_id: orderId },
+                body: options,
+            });
+            return answer.ok ? answer.document : { ok: false, error: failedCall(true, answer.failure) };
+        },
         accept: (...given) => {
             if (given.length > 0)
                 reportSafely(registry.problem, acceptanceArgumentWarning(orderId));

package/dist/index.d.ts

@@ -20,7 +20,7 @@
  * 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 type { CallError, Card, CardInput, Delivery, Fulfillment, HandlerAnswer, MerchantClosure, MerchantFinding, Money, Order, OrderCallResponse, OrderCallResult, OrderCloseRequest, OrderCloseResponse, OrderEvent, OrderList, OrderStatus, OrderWithStatus, PaymentStatus, 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";
 export type { CardCheck } from "./check-card.js";
 export { checkCard } from "./check-card.js";

package/dist/worker.d.ts

@@ -44,7 +44,8 @@ export interface Delivered {
  * question to Agentify afterwards, since an event is answered against nothing.
  * An event is sent at most once, so the risk to write against is an event that
  * never arrives, not one that arrives twice; reading open orders with
- * `orders.list({ open: true })` finds a refund owed whose event went missing.
+ * `orders.list({ open: true })` finds a paid order whose `order.unfulfilled`
+ * went missing, including one paid after you closed it.
  */
 export type EventHandler = (event: OrderEvent, delivered: Delivered) => void | Promise<void>;
 /**

package/dist/worker.js

@@ -369,7 +369,7 @@ deadlineMs = POLL_DEADLINE_MS) => {
                 subject: event.order_id,
                 // An event is sent at most once and carries no acknowledgement, so
                 // nothing here can ask for it again: what the handler failed on is
-                // lost, and the open-orders list is where a refund owed shows up.
+                // lost, and the open-orders list is where an unfulfilled order shows up.
                 message: `the event handler threw on ${event.type} for order ${event.order_id}; nothing here can ask for that event again, and whether it is sent again is not something this SDK knows: ${String(cause)}`,
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Sell your existing products to AI agents: publish product cards to an x402 storefront and fill the paid orders from your own service.",
   "keywords": [
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nuanu-ai/agentify-contracts": "0.11.0"
+    "@nuanu-ai/agentify-contracts": "0.12.0"
   },
   "devDependencies": {
     "vitest": "^4.1.11",