@artos-commerce/ucp-cli 0.1.0

package/dist/commands/account.js

@@ -0,0 +1,31 @@
+import { formatAccountTools } from '../output.js';
+/** Lists or calls buyer-account tools (require ARTOS_BUYER_BEARER). */
+export async function account(deps, args) {
+    if (!deps.hasBuyer) {
+        deps.io.error('account: set ARTOS_BUYER_BEARER to a buyer OAuth bearer (account tools are buyer-bound).');
+        return 1;
+    }
+    try {
+        if (args.action === 'list') {
+            const tools = await deps.account.listAccountTools();
+            deps.io.write(formatAccountTools(tools, { json: args.json }));
+            return 0;
+        }
+        if (args.action === 'call') {
+            if (!args.tool) {
+                deps.io.error('account call: a tool name is required.');
+                return 1;
+            }
+            const res = await deps.account.callAccountTool(args.tool, args.toolArgs ?? {});
+            deps.io.write(JSON.stringify(res, null, 2));
+            return 0;
+        }
+        deps.io.error(`Unknown account subcommand: ${args.action}`);
+        return 1;
+    }
+    catch (err) {
+        deps.io.error(`account: ${err.message}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=account.js.map

package/dist/commands/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../src/commands/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAsBlD,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAiB,EACjB,IAAiB;IAEjB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,IAAI,CAAC,EAAE,CAAC,KAAK,CACX,0FAA0F,CAC3F,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;YACpD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAC9D,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;gBACxD,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAC5C,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,QAAQ,IAAI,EAAE,CACpB,CAAC;YACF,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC5C,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,+BAA+B,IAAI,CAAC,MAAgB,EAAE,CAAC,CAAC;QACtE,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,YAAa,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/commands/cart.d.ts

@@ -0,0 +1,17 @@
+import type { CheckoutLineItem } from '@artos-commerce/ucp-client/checkout';
+import type { StoreCaller } from '../agent.js';
+import type { Io } from '../io.js';
+export type CartAction = 'create' | 'view' | 'update';
+export interface CartArgs {
+    action: CartAction;
+    store: string;
+    id?: string;
+    items?: CheckoutLineItem[];
+    json?: boolean;
+}
+export interface CartDeps {
+    store: StoreCaller;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/** Creates, views, or updates a store cart. */
+export declare function cart(deps: CartDeps, args: CartArgs): Promise<number>;

package/dist/commands/cart.js

@@ -0,0 +1,51 @@
+import { isUcpError, messageOf } from '@artos-commerce/ucp-client/ucp';
+import { lineItems } from '../args.js';
+import { formatEntity } from '../output.js';
+/** Creates, views, or updates a store cart. */
+export async function cart(deps, args) {
+    if (!args.store.trim()) {
+        deps.io.error('cart: --store <slug> is required.');
+        return 1;
+    }
+    let res;
+    switch (args.action) {
+        case 'create': {
+            if (!args.items?.length) {
+                deps.io.error('cart create: at least one --item is required.');
+                return 1;
+            }
+            res = await deps.store.call(args.store, 'create_cart', { cart: { line_items: lineItems(args.items) } }, { idempotent: true });
+            break;
+        }
+        case 'view': {
+            if (!args.id) {
+                deps.io.error('cart view: --id is required.');
+                return 1;
+            }
+            res = await deps.store.call(args.store, 'get_cart', { id: args.id });
+            break;
+        }
+        case 'update': {
+            if (!args.id) {
+                deps.io.error('cart update: --id is required.');
+                return 1;
+            }
+            if (!args.items?.length) {
+                deps.io.error('cart update: at least one --item is required.');
+                return 1;
+            }
+            res = await deps.store.call(args.store, 'update_cart', { id: args.id, cart: { line_items: lineItems(args.items) } }, { idempotent: true });
+            break;
+        }
+        default:
+            deps.io.error(`Unknown cart subcommand: ${args.action}`);
+            return 1;
+    }
+    if (isUcpError(res)) {
+        deps.io.error(messageOf(res) ?? 'The store returned an error.');
+        return 1;
+    }
+    deps.io.write(formatEntity('Cart', res, { json: args.json }));
+    return 0;
+}
+//# sourceMappingURL=cart.js.map

package/dist/commands/cart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.js","sourceRoot":"","sources":["../../src/commands/cart.ts"],"names":[],"mappings":"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"}

package/dist/commands/catalog-search.d.ts

@@ -0,0 +1,22 @@
+import type { UcpResponse } from '@artos-commerce/ucp-client/ucp';
+import type { Io } from '../io.js';
+/** The transport surface this command needs (a subset of `UcpClient`). */
+export interface CatalogSearcher {
+    globalSearch(catalog: {
+        query?: string;
+        filters?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+}
+export interface CatalogSearchArgs {
+    query: string;
+    /** Max price in MAJOR units (dollars); converted to minor units on the wire. */
+    max?: number;
+    currency?: string;
+    json?: boolean;
+}
+export interface CatalogSearchDeps {
+    client: CatalogSearcher;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/** Runs a cross-store catalog search and prints the results. */
+export declare function catalogSearch(deps: CatalogSearchDeps, args: CatalogSearchArgs): Promise<number>;

package/dist/commands/catalog-search.js

@@ -0,0 +1,27 @@
+import { normalizeSearchFilters } from '@artos-commerce/ucp-client/checkout';
+import { formatSearchResults } from '../output.js';
+/** Runs a cross-store catalog search and prints the results. */
+export async function catalogSearch(deps, args) {
+    if (!args.query.trim()) {
+        deps.io.error('catalog search: a query is required.');
+        return 1;
+    }
+    const filters = args.max != null
+        ? normalizeSearchFilters({
+            price: { max: args.max, currency: args.currency },
+        })
+        : undefined;
+    try {
+        const res = await deps.client.globalSearch({
+            query: args.query,
+            ...(filters ? { filters } : {}),
+        });
+        deps.io.write(formatSearchResults(res, { json: args.json }));
+        return 0;
+    }
+    catch (err) {
+        deps.io.error(`Search failed: ${err.message}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=catalog-search.js.map

package/dist/commands/catalog-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-search.js","sourceRoot":"","sources":["../../src/commands/catalog-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAwBnD,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAuB,EACvB,IAAuB;IAEvB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,OAAO,GACX,IAAI,CAAC,GAAG,IAAI,IAAI;QACd,CAAC,CAAC,sBAAsB,CAAC;YACrB,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;SAClD,CAAC;QACJ,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;YACzC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC,CAAC,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,mBAAmB,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7D,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/commands/checkout.d.ts

@@ -0,0 +1,20 @@
+import type { CheckoutLineItem } from '@artos-commerce/ucp-client/checkout';
+import type { StoreCaller } from '../agent.js';
+import type { Io } from '../io.js';
+export type CheckoutAction = 'create' | 'view' | 'update';
+export interface CheckoutArgs {
+    action: CheckoutAction;
+    store: string;
+    id?: string;
+    cartId?: string;
+    items?: CheckoutLineItem[];
+    /** Nested patch from `--set` (e.g. `{ shipping_address: { country: 'US' } }`). */
+    set?: Record<string, unknown>;
+    json?: boolean;
+}
+export interface CheckoutDeps {
+    store: StoreCaller;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/** Creates, views, or updates a store checkout. */
+export declare function checkout(deps: CheckoutDeps, args: CheckoutArgs): Promise<number>;

package/dist/commands/checkout.js

@@ -0,0 +1,52 @@
+import { isUcpError, messageOf } from '@artos-commerce/ucp-client/ucp';
+import { lineItems } from '../args.js';
+import { formatEntity } from '../output.js';
+/** Creates, views, or updates a store checkout. */
+export async function checkout(deps, args) {
+    if (!args.store.trim()) {
+        deps.io.error('checkout: --store <slug> is required.');
+        return 1;
+    }
+    let res;
+    switch (args.action) {
+        case 'create': {
+            const body = { ...(args.set ?? {}) };
+            if (args.cartId)
+                body.cart_id = args.cartId;
+            if (args.items?.length)
+                body.line_items = lineItems(args.items);
+            res = await deps.store.call(args.store, 'create_checkout', { checkout: body }, { idempotent: true });
+            break;
+        }
+        case 'view': {
+            if (!args.id) {
+                deps.io.error('checkout view: --id is required.');
+                return 1;
+            }
+            res = await deps.store.call(args.store, 'get_checkout', { id: args.id });
+            break;
+        }
+        case 'update': {
+            if (!args.id) {
+                deps.io.error('checkout update: --id is required.');
+                return 1;
+            }
+            if (!args.set || Object.keys(args.set).length === 0) {
+                deps.io.error('checkout update: at least one --set key=value is required.');
+                return 1;
+            }
+            res = await deps.store.call(args.store, 'update_checkout', { id: args.id, checkout: args.set }, { idempotent: true });
+            break;
+        }
+        default:
+            deps.io.error(`Unknown checkout subcommand: ${args.action}`);
+            return 1;
+    }
+    if (isUcpError(res)) {
+        deps.io.error(messageOf(res) ?? 'The store returned an error.');
+        return 1;
+    }
+    deps.io.write(formatEntity('Checkout', res, { json: args.json }));
+    return 0;
+}
+//# sourceMappingURL=checkout.js.map

package/dist/commands/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../src/commands/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAsB5C,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAkB,EAClB,IAAkB;IAElB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,GAAG,CAAC;IACR,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,IAAI,GAA4B,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9D,IAAI,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;YAC5C,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM;gBAAE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChE,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CACzB,IAAI,CAAC,KAAK,EACV,iBAAiB,EACjB,EAAE,QAAQ,EAAE,IAAI,EAAE,EAClB,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;YACF,MAAM;QACR,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;gBAClD,OAAO,CAAC,CAAC;YACX,CAAC;YACD,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YACzE,MAAM;QACR,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;gBACpD,OAAO,CAAC,CAAC;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpD,IAAI,CAAC,EAAE,CAAC,KAAK,CACX,4DAA4D,CAC7D,CAAC;gBACF,OAAO,CAAC,CAAC;YACX,CAAC;YACD,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CACzB,IAAI,CAAC,KAAK,EACV,iBAAiB,EACjB,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EACnC,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;YACF,MAAM;QACR,CAAC;QACD;YACE,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,gCAAgC,IAAI,CAAC,MAAgB,EAAE,CAAC,CAAC;YACvE,OAAO,CAAC,CAAC;IACb,CAAC;IAED,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,8BAA8B,CAAC,CAAC;QAChE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/commands/discover.d.ts

@@ -0,0 +1,13 @@
+import type { Io } from '../io.js';
+export interface DiscoverArgs {
+    store: string;
+    json?: boolean;
+}
+export interface DiscoverDeps {
+    /** Fetches and parses a JSON document, throwing on a non-2xx response. */
+    fetchJson: (url: string) => Promise<Record<string, unknown>>;
+    baseUrl: string;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/** Fetches a store's UCP profile and prints its keys, handlers, and capabilities. */
+export declare function discover(deps: DiscoverDeps, args: DiscoverArgs): Promise<number>;

package/dist/commands/discover.js

@@ -0,0 +1,27 @@
+import { formatStoreProfile } from '../output.js';
+/** Fetches a store's UCP profile and prints its keys, handlers, and capabilities. */
+export async function discover(deps, args) {
+    if (!args.store.trim()) {
+        deps.io.error('discover: --store <slug> is required.');
+        return 1;
+    }
+    const url = `${deps.baseUrl}/s/${args.store}/.well-known/ucp`;
+    try {
+        const raw = await deps.fetchJson(url);
+        // The endpoint returns HTTP 200 with a UCP error envelope for an unknown
+        // store, so surface that as a failure instead of printing an empty profile.
+        const ucp = raw.ucp;
+        if (ucp?.status === 'error') {
+            const messages = raw.messages;
+            deps.io.error(`discover: ${messages?.[0]?.content ?? `store "${args.store}" not found`}`);
+            return 1;
+        }
+        deps.io.write(formatStoreProfile(args.store, raw, { json: args.json }));
+        return 0;
+    }
+    catch (err) {
+        deps.io.error(`Failed to fetch ${url}: ${err.message}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=discover.js.map

package/dist/commands/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAelD,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAkB,EAClB,IAAkB;IAElB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,MAAM,IAAI,CAAC,KAAK,kBAAkB,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACtC,yEAAyE;QACzE,4EAA4E;QAC5E,MAAM,GAAG,GAAG,GAAG,CAAC,GAAsC,CAAC;QACvD,IAAI,GAAG,EAAE,MAAM,KAAK,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAmD,CAAC;YACzE,IAAI,CAAC,EAAE,CAAC,KAAK,CACX,aAAa,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,UAAU,IAAI,CAAC,KAAK,aAAa,EAAE,CAC3E,CAAC;YACF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,mBAAmB,GAAG,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,16 @@
+import type { Io } from '../io.js';
+/** The starter project's files, keyed by path relative to the target directory. */
+export declare function starterFiles(opts: {
+    name: string;
+}): Record<string, string>;
+export interface InitDeps {
+    io: Pick<Io, 'write' | 'error' | 'mkdir' | 'writeFile' | 'exists'>;
+}
+export interface InitArgs {
+    /** Project name (used in package.json + README). */
+    name: string;
+    /** Absolute target directory to scaffold into. */
+    outDir: string;
+}
+/** Scaffolds a Build-track agent starter project into `outDir`. */
+export declare function initProject(deps: InitDeps, args: InitArgs): number;

package/dist/commands/init.js

@@ -0,0 +1,222 @@
+import { join } from 'node:path';
+/** Pinned dependency versions for the generated starter. */
+const UCP_CLIENT_VERSION = '^0.2.0';
+const STARTER_INDEX = `import 'dotenv/config';
+import {
+  UcpClient,
+  Ap2Signer,
+  createCheckoutHandlers,
+  createAccountHandlers,
+  OAuthClient,
+  createPkce,
+  isUcpError,
+} from '@artos-commerce/ucp-client';
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error('Missing required env var: ' + name);
+  return value;
+}
+
+const config = {
+  artosBaseUrl: process.env.ARTOS_BASE_URL ?? 'https://api.artos.sh',
+  platformApiKey: required('UCP_PLATFORM_API_KEY'),
+  platformProfileUrl: required('PLATFORM_PROFILE_URL'),
+};
+
+// The buyer bearer is optional; account tools + the crypto rail need it.
+const buyerToken = process.env.ARTOS_BUYER_BEARER || undefined;
+const client = new UcpClient(config, { buyerToken });
+
+// AP2 signer (needed to PLACE orders). Generate a key with:
+//   npx @artos-commerce/ucp-cli profile init
+const signer = process.env.AGENT_PRIVATE_JWK
+  ? new Ap2Signer(
+      JSON.parse(process.env.AGENT_PRIVATE_JWK),
+      process.env.AGENT_KID ?? '',
+    )
+  : undefined;
+
+async function main() {
+  // 1) Search the cross-store catalog (works anonymously).
+  const results = await client.globalSearch({
+    query: 'shoes',
+    filters: { price: { max: 150, currency: 'USD' } },
+  });
+  const products =
+    (results.products as Array<{ title?: string }> | undefined) ?? [];
+  console.log('Found ' + products.length + ' product(s):');
+  for (const p of products.slice(0, 5)) {
+    console.log('  • ' + (p.title ?? '(untitled)'));
+  }
+
+  // 2) Build + confirm a checkout (needs a real platform key + the agent signer).
+  if (signer) {
+    const shop = createCheckoutHandlers({ client, signer });
+    // const checkout = await shop.createCheckout({ storeSlug, items: [{ id, quantity: 1 }] });
+    // const outcome = await shop.confirmPurchase({
+    //   storeSlug,
+    //   checkoutId: checkout.id,
+    //   paymentMethod: 'sh.artos.card',
+    // });
+    void shop;
+  }
+
+  // 3) Buyer-account tools (needs ARTOS_BUYER_BEARER — see signIn() below).
+  if (buyerToken) {
+    const account = createAccountHandlers({ client });
+    const me = await account.getBuyerContext();
+    console.log('Buyer context: ' + (isUcpError(me) ? 'error' : 'ok'));
+  }
+}
+
+// 4) Buyer sign-in (PKCE). Run this once to obtain a buyer bearer, then set it as
+//    ARTOS_BUYER_BEARER for the account + crypto steps above.
+export async function signIn() {
+  const oauth = new OAuthClient({ artosBaseUrl: config.artosBaseUrl });
+  const pkce = createPkce();
+  const { url, state } = await oauth.authorizeUrl({
+    clientId:
+      process.env.OAUTH_CLIENT_ID ??
+      'https://your-app.example/well-known/oauth-client.json',
+    redirectUri:
+      process.env.OAUTH_REDIRECT_URI ?? 'http://localhost:8898/callback',
+    codeChallenge: pkce.challenge,
+  });
+  console.log('Open this URL to sign in (state=' + state + '):');
+  console.log(url);
+  // On the redirect (verify state!), exchange the code:
+  //   const tokens = await oauth.exchangeCode({
+  //     code, codeVerifier: pkce.verifier, clientId, redirectUri,
+  //   });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+`;
+const STARTER_ENV = `# Artos API base URL
+ARTOS_BASE_URL=https://api.artos.sh
+
+# Platform (cross-store) UCP API key: "<clientId>.<secret>"
+UCP_PLATFORM_API_KEY=
+
+# HTTPS URL of your published agent UCP profile (signing_keys + capabilities)
+PLATFORM_PROFILE_URL=https://your-app.example/.well-known/ucp
+
+# Agent AP2 signing key (generate with: npx @artos-commerce/ucp-cli profile init)
+AGENT_PRIVATE_JWK=
+AGENT_KID=
+
+# Optional: a buyer OAuth bearer (account tools + crypto rail). Obtain via signIn().
+ARTOS_BUYER_BEARER=
+
+# Optional: OAuth client for buyer sign-in (PKCE)
+OAUTH_CLIENT_ID=
+OAUTH_REDIRECT_URI=http://localhost:8898/callback
+`;
+const STARTER_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`;
+const STARTER_GITIGNORE = `node_modules
+.env
+dist
+*.log
+`;
+function starterPackageJson(name) {
+    return (JSON.stringify({
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        scripts: { start: 'tsx src/index.ts' },
+        dependencies: {
+            '@artos-commerce/ucp-client': UCP_CLIENT_VERSION,
+            dotenv: '^16.4.5',
+        },
+        devDependencies: {
+            '@types/node': '^20.19.42',
+            tsx: '^4.19.2',
+            typescript: '^5.6.0',
+        },
+        engines: { node: '>=20' },
+    }, null, 2) + '\n');
+}
+function starterReadme(name) {
+    return `# ${name}
+
+A Build-track Artos agent starter, wired with
+[\`@artos-commerce/ucp-client\`](https://www.npmjs.com/package/@artos-commerce/ucp-client):
+cross-store catalog search, checkout + \`confirmPurchase\`, buyer-account tools,
+and buyer OAuth (PKCE).
+
+## Setup
+
+\`\`\`bash
+npm install
+cp .env.example .env   # then fill it in
+npm start
+\`\`\`
+
+Generate an agent signing key + profile with:
+
+\`\`\`bash
+npx @artos-commerce/ucp-cli profile init
+\`\`\`
+
+Publish the printed \`ucp.json\` at your \`PLATFORM_PROFILE_URL\`, and load the
+private key as \`AGENT_PRIVATE_JWK\` (never commit it).
+
+## What's inside
+
+- \`src/index.ts\` — searches the catalog, then shows how to checkout, call
+  account tools, and sign a buyer in (PKCE). Edit it for your use case.
+`;
+}
+/** The starter project's files, keyed by path relative to the target directory. */
+export function starterFiles(opts) {
+    return {
+        'package.json': starterPackageJson(opts.name),
+        'tsconfig.json': STARTER_TSCONFIG,
+        '.env.example': STARTER_ENV,
+        '.gitignore': STARTER_GITIGNORE,
+        'README.md': starterReadme(opts.name),
+        'src/index.ts': STARTER_INDEX,
+    };
+}
+/** Scaffolds a Build-track agent starter project into `outDir`. */
+export function initProject(deps, args) {
+    if (deps.io.exists(join(args.outDir, 'package.json'))) {
+        deps.io.error(`init: ${args.outDir} already contains a package.json — choose an empty directory (--out <dir>).`);
+        return 1;
+    }
+    const files = starterFiles({ name: args.name });
+    deps.io.mkdir(args.outDir);
+    deps.io.mkdir(join(args.outDir, 'src'));
+    for (const [rel, contents] of Object.entries(files)) {
+        deps.io.writeFile(join(args.outDir, rel), contents);
+    }
+    deps.io.write([
+        `Scaffolded ${args.name} into ${args.outDir}`,
+        '',
+        'Next steps:',
+        `  cd ${args.outDir}`,
+        '  npm install',
+        '  cp .env.example .env   # then fill it in',
+        '  npm start',
+    ].join('\n'));
+    return 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/profile-init.d.ts

@@ -0,0 +1,22 @@
+import type { GeneratedProfile } from '../profile.js';
+import type { Io } from '../io.js';
+export interface ProfileInitArgs {
+    outDir: string;
+    /** The public URL the profile will be hosted at. */
+    url: string;
+    kid?: string;
+}
+export interface ProfileInitDeps {
+    generate: (opts: {
+        url: string;
+        kid?: string;
+    }) => Promise<GeneratedProfile>;
+    mkdir: (path: string) => void;
+    writeFile: (path: string, contents: string) => void;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/**
+ * Generates an agent UCP profile + keypair and writes the public profile and the
+ * private signing key to `outDir`. Prints the env vars needed to use them.
+ */
+export declare function profileInit(deps: ProfileInitDeps, args: ProfileInitArgs): Promise<number>;

package/dist/commands/profile-init.js

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+/**
+ * Generates an agent UCP profile + keypair and writes the public profile and the
+ * private signing key to `outDir`. Prints the env vars needed to use them.
+ */
+export async function profileInit(deps, args) {
+    try {
+        const generated = await deps.generate({ url: args.url, kid: args.kid });
+        deps.mkdir(args.outDir);
+        const profilePath = join(args.outDir, 'ucp.json');
+        const keyPath = join(args.outDir, 'private-jwk.json');
+        deps.writeFile(profilePath, `${JSON.stringify(generated.profile, null, 2)}\n`);
+        deps.writeFile(keyPath, `${JSON.stringify(generated.privateJwk, null, 2)}\n`);
+        deps.io.write([
+            `Generated agent profile (kid ${generated.kid}).`,
+            '',
+            `  ${profilePath}`,
+            `    → host this publicly at ${args.url}`,
+            `  ${keyPath}`,
+            '    → SECRET: load as AGENT_PRIVATE_JWK; never commit it',
+            '',
+            'Next:',
+            `  export PLATFORM_PROFILE_URL=${args.url}`,
+            `  export AGENT_KID=${generated.kid}`,
+            `  export AGENT_PRIVATE_JWK="$(cat ${keyPath})"`,
+        ].join('\n'));
+        return 0;
+    }
+    catch (err) {
+        deps.io.error(`profile init failed: ${err.message}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=profile-init.js.map

package/dist/commands/profile-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-init.js","sourceRoot":"","sources":["../../src/commands/profile-init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAkBjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAqB,EACrB,IAAqB;IAErB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAExB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,CACZ,WAAW,EACX,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAClD,CAAC;QACF,IAAI,CAAC,SAAS,CACZ,OAAO,EACP,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACrD,CAAC;QAEF,IAAI,CAAC,EAAE,CAAC,KAAK,CACX;YACE,gCAAgC,SAAS,CAAC,GAAG,IAAI;YACjD,EAAE;YACF,KAAK,WAAW,EAAE;YAClB,+BAA+B,IAAI,CAAC,GAAG,EAAE;YACzC,KAAK,OAAO,EAAE;YACd,0DAA0D;YAC1D,EAAE;YACF,OAAO;YACP,iCAAiC,IAAI,CAAC,GAAG,EAAE;YAC3C,sBAAsB,SAAS,CAAC,GAAG,EAAE;YACrC,qCAAqC,OAAO,IAAI;SACjD,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,wBAAyB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAChE,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/commands/purchase.d.ts

@@ -0,0 +1,22 @@
+import type { ConfirmFn } from '../agent.js';
+import type { Io } from '../io.js';
+export interface PurchaseArgs {
+    store: string;
+    id: string;
+    /** Chosen rail handler id (e.g. `sh.artos.card`). Omit to be asked. */
+    pay?: string;
+    /** Server-side allowance (PaymentMandate) UUID. */
+    mandate?: string;
+    /** `true` apply best coupon, `false` strip it, `undefined` leave untouched. */
+    applyCoupon?: boolean;
+    json?: boolean;
+}
+export interface PurchaseDeps {
+    confirm: ConfirmFn;
+    io: Pick<Io, 'write' | 'error'>;
+}
+/**
+ * Exit codes: 0 = order placed; 2 = action required (escalation / pick a rail);
+ * 1 = error.
+ */
+export declare function purchaseConfirm(deps: PurchaseDeps, args: PurchaseArgs): Promise<number>;

package/dist/commands/purchase.js

@@ -0,0 +1,29 @@
+import { formatOutcome } from '../output.js';
+/**
+ * Exit codes: 0 = order placed; 2 = action required (escalation / pick a rail);
+ * 1 = error.
+ */
+export async function purchaseConfirm(deps, args) {
+    if (!args.store.trim() || !args.id.trim()) {
+        deps.io.error('purchase confirm: --store <slug> and --id <checkoutId> are required.');
+        return 1;
+    }
+    const outcome = await deps.confirm({
+        storeSlug: args.store,
+        checkoutId: args.id,
+        paymentMethod: args.pay,
+        paymentMandateId: args.mandate,
+        applyCoupon: args.applyCoupon,
+    });
+    deps.io.write(formatOutcome(outcome, { json: args.json }));
+    switch (outcome.status) {
+        case 'completed':
+            return 0;
+        case 'escalation_required':
+        case 'payment_selection_required':
+            return 2;
+        case 'error':
+            return 1;
+    }
+}
+//# sourceMappingURL=purchase.js.map