@commercelayer/agent-cli 0.0.0-stage → 0.1.0

package/dist/ucp/buy.js

@@ -0,0 +1,88 @@
+// Buying from a store the way any shopping agent would: discover, search, cart,
+// checkout, address, pay with the sandbox handler, read the order back.
+import { fail } from '../output.js';
+import { discover, replay, shopping, UcpError } from './client.js';
+import { SANDBOX_CREDENTIAL_TYPE, SANDBOX_HANDLER_ID, SANDBOX_TOKEN_DECLINED, SANDBOX_TOKEN_SUCCESS } from './platform.js';
+export const TEST_BUYER = { first_name: 'Test', last_name: 'Buyer', email: 'buyer@example.com', phone_number: '+10000000000' };
+export function testAddress(country) {
+    return { id: 'dest_1', first_name: 'Test', last_name: 'Buyer', street_address: '1 Test Street', address_locality: 'Testville', postal_code: '00000', address_country: country };
+}
+export function sandboxInstrument(decline = false) {
+    return {
+        id: 'pi_1',
+        handler_id: SANDBOX_HANDLER_ID,
+        type: 'card',
+        selected: true,
+        display: { brand: 'visa', last_digits: '4242', expiry_month: 12, expiry_year: 2030 },
+        credential: { type: SANDBOX_CREDENTIAL_TYPE, token: decline ? SANDBOX_TOKEN_DECLINED : SANDBOX_TOKEN_SUCCESS, expiry: new Date(Date.now() + 1800_000).toISOString() },
+    };
+}
+export const TEST_SIGNALS = { 'dev.ucp.buyer_ip': '203.0.113.1', 'dev.ucp.user_agent': 'c11r' };
+function note(steps, step, call, result) {
+    steps.push({ step, request: `${call.method} ${new URL(call.url).pathname}`, status: call.status, result, ...(call.signature ? { signature: call.signature } : {}) });
+    return call.body;
+}
+/** Country the product ships to: from the catalog's fulfillment data, else from the caller. */
+function shipTo(variant, wanted) {
+    if (wanted)
+        return wanted.toUpperCase();
+    const plain = variant.fulfillment?.methods?.[0]?.description?.plain ?? '';
+    const m = plain.match(/Ships to ([A-Z]{2})/);
+    return m ? m[1] : 'US';
+}
+export async function buy(origin, opts = {}) {
+    const steps = [];
+    const store = await discover(origin);
+    steps.push({ step: 'discover', request: 'GET /.well-known/ucp', status: 200, result: `UCP ${store.profile.ucp.version}, ${store.capabilities.size} shared capabilities` });
+    try {
+        const search = note(steps, 'search', await shopping.search(store, { query: opts.sku ?? '', context: opts.country ? { address_country: opts.country.toUpperCase() } : {} }), '');
+        steps[steps.length - 1].result = `${search.products.length} products`;
+        const product = opts.sku ? search.products.find((p) => p.variants.some((v) => v.id === opts.sku || v.sku === opts.sku)) : search.products[0];
+        if (!product)
+            fail('no_product', opts.sku ? `The catalog has no product ${opts.sku}.` : 'The catalog is empty.', 'Add products to .commercelayer/store.yml or .commercelayer/products/ and run `c11r apply`.');
+        const variant = opts.sku ? product.variants.find((v) => v.id === opts.sku || v.sku === opts.sku) : product.variants[0];
+        const country = shipTo(variant, opts.country);
+        const quantity = opts.quantity ?? 1;
+        const context = { address_country: country, currency: variant.price.currency };
+        const lineItems = [{ item: { id: variant.id }, quantity }];
+        const discounts = opts.code ? { discounts: { codes: [opts.code] } } : {};
+        let create;
+        if (opts.viaCart && store.capabilities.has('dev.ucp.shopping.cart')) {
+            const cart = note(steps, 'cart', await shopping.createCart(store, { line_items: lineItems, context, ...discounts }), '');
+            steps[steps.length - 1].result = `cart ${cart.id}, ${cart.totals.at(-1).amount} ${cart.currency}`;
+            create = { cart_id: cart.id, buyer: TEST_BUYER, context };
+        }
+        else
+            create = { line_items: lineItems, buyer: TEST_BUYER, context, ...discounts };
+        let checkout = note(steps, 'checkout', await shopping.createCheckout(store, create), '');
+        steps[steps.length - 1].result = `checkout ${checkout.id} ${checkout.status}`;
+        const update = replay(checkout);
+        update.buyer = { ...TEST_BUYER, ...(checkout.buyer?.consent ? { consent: checkout.buyer.consent } : {}) };
+        if (update.fulfillment) {
+            update.fulfillment.methods[0].destinations = [testAddress(country)];
+            update.fulfillment.methods[0].selected_destination_id = 'dest_1';
+        }
+        checkout = note(steps, 'address', await shopping.updateCheckout(store, checkout.id, update), '');
+        steps[steps.length - 1].result = `${checkout.status}, total ${checkout.totals.at(-1).amount} ${checkout.currency}`;
+        if (checkout.status !== 'ready_for_complete') {
+            const why = (checkout.messages ?? []).filter((m) => m.type === 'error').map((m) => `${m.code} at ${m.path}: ${m.content}`).join('; ');
+            fail('checkout_not_ready', `The checkout is ${checkout.status}: ${why}`, 'Fix the store (markets, countries, prices) and run the command again.');
+        }
+        const completeCall = await shopping.completeCheckout(store, checkout.id, { payment: { instruments: [sandboxInstrument(opts.decline)] }, signals: TEST_SIGNALS });
+        checkout = note(steps, 'pay', completeCall, '');
+        steps[steps.length - 1].result = checkout.status === 'completed' ? `completed, order ${checkout.order.id}` : `${checkout.status}: ${(checkout.messages ?? []).map((m) => m.code).join(', ')}`;
+        let order = null;
+        if (checkout.order) {
+            order = note(steps, 'order', await shopping.getOrder(store, checkout.order.id), '');
+            steps[steps.length - 1].result = `${order.label}, ${order.line_items.length} line item(s), ${order.totals.at(-1).amount} ${order.currency}`;
+        }
+        return { store, steps, checkout, order };
+    }
+    catch (e) {
+        if (e instanceof UcpError) {
+            steps.push({ step: 'failed', request: `${e.call.method} ${new URL(e.call.url).pathname}`, status: e.call.status, result: e.message });
+            fail('ucp_error', e.message, `The store answered in a way the buyer could not continue from. Steps so far: ${steps.map((s) => `${s.step} (${s.result})`).join(' → ')}. Run \`c11r ucp check\` for the full conformance report.`);
+        }
+        throw e;
+    }
+}

package/dist/ucp/check.js

@@ -0,0 +1,355 @@
+// Walks every UCP capability a store advertises and reports what passes. This is
+// what the ucp skill's "done when" uses: a store that passes can be bought from
+// by any shopping agent, not only by this CLI.
+import crypto from 'node:crypto';
+import { send } from '../api/transport.js';
+import { sandboxInstrument, TEST_BUYER, testAddress } from './buy.js';
+import { discover, replay, request, shopping } from './client.js';
+import { EXTENSIONS, SHOPPING_CAPABILITIES, UCP_VERSION } from './platform.js';
+class Fail extends Error {
+}
+const must = (cond, detail) => {
+    if (!cond)
+        throw new Fail(detail);
+};
+const sum = (totals) => totals.filter((t) => t.type !== 'total').reduce((s, t) => s + t.amount, 0);
+const total = (totals) => totals.find((t) => t.type === 'total')?.amount;
+export async function check(origin) {
+    const checks = [];
+    let store = null;
+    const run = async (capability, name, fn) => {
+        try {
+            checks.push({ capability, name, pass: true, detail: await fn() });
+        }
+        catch (e) {
+            checks.push({ capability, name, pass: false, detail: e instanceof Error ? e.message : String(e) });
+        }
+    };
+    // ---- profile
+    await run('profile', 'served at /.well-known/ucp', async () => {
+        const res = await send('GET', `${origin}/.well-known/ucp`, { accept: 'application/json' });
+        must(res.status === 200, `answered ${res.status}`);
+        must(/public/.test(res.headers['cache-control'] ?? '') && /max-age=(\d+)/.test(res.headers['cache-control'] ?? '') && Number(res.headers['cache-control'].match(/max-age=(\d+)/)[1]) >= 60, `Cache-Control must be public with max-age >= 60; got "${res.headers['cache-control']}"`);
+        const p = JSON.parse(res.body);
+        must(/^\d{4}-\d{2}-\d{2}$/.test(p.ucp?.version), `ucp.version must be a date; got ${p.ucp?.version}`);
+        must(p.ucp.services && p.ucp.payment_handlers, 'ucp.services and ucp.payment_handlers must be present');
+        for (const [name, entries] of Object.entries({ ...p.ucp.services, ...p.ucp.capabilities })) {
+            if (!name.startsWith('dev.ucp.'))
+                continue;
+            for (const e of entries)
+                must(e.version === p.ucp.version, `${name} declares version ${e.version}, profile is ${p.ucp.version}`);
+        }
+        must(Array.isArray(p.keys) && p.keys.some((k) => k.kid && k.kty === 'EC' && k.crv === 'P-256' && !k.d), 'keys[] must hold a public P-256 key with a kid and no private members');
+        return `UCP ${p.ucp.version}, ${Object.keys(p.ucp.capabilities ?? {}).length} capabilities, ${Object.keys(p.ucp.payment_handlers).length} payment handler(s)`;
+    });
+    await run('profile', 'negotiates with this CLI', async () => {
+        store = await discover(origin);
+        const missing = SHOPPING_CAPABILITIES.filter((c) => !store.capabilities.has(c));
+        must(missing.length === 0, `not shared: ${missing.join(', ')}`);
+        const exts = Object.keys(EXTENSIONS).filter((e) => store.capabilities.has(e));
+        return `REST at ${store.endpoint}; extensions: ${exts.map((e) => e.split('.').pop()).join(', ') || 'none'}`;
+    });
+    if (!store)
+        return finish(origin, checks);
+    const s = store;
+    // ---- transport rules
+    await run('transport', 'rejects a request without UCP-Agent', async () => {
+        const c = await request(s, 'POST', `${s.endpoint}/catalog/search`, { query: '' }, { omit: ['ucp-agent'] });
+        must(c.status === 400 && c.body?.code === 'invalid_profile_url', `expected 400 invalid_profile_url, got ${c.status} ${c.body?.code ?? ''}`);
+        return '400 invalid_profile_url';
+    });
+    await run('transport', 'rejects a request without Request-Id', async () => {
+        const c = await request(s, 'POST', `${s.endpoint}/catalog/search`, { query: '' }, { omit: ['request-id'] });
+        must(c.status === 400, `expected 400, got ${c.status}`);
+        return `400 ${c.body?.code ?? ''}`;
+    });
+    await run('transport', 'requires Idempotency-Key on state changes', async () => {
+        const c = await request(s, 'POST', `${s.endpoint}/carts`, { line_items: [] }, { omit: ['idempotency-key'] });
+        must(c.status === 400, `expected 400, got ${c.status}`);
+        return `400 ${c.body?.code ?? ''}`;
+    });
+    await run('transport', 'verifies Content-Digest', async () => {
+        const res = await send('POST', `${s.endpoint}/catalog/search`, { 'ucp-agent': 'profile="https://example.com/p"', 'request-id': crypto.randomUUID(), 'content-digest': 'sha-256=:AAAA:', 'content-type': 'application/json' }, '{}');
+        must(res.status === 400, `expected 400 digest_mismatch, got ${res.status}`);
+        return '400 digest_mismatch';
+    });
+    // ---- catalog
+    let variant = null;
+    let country = 'US';
+    await run('dev.ucp.shopping.catalog.search', 'search returns well-formed products', async () => {
+        const c = await shopping.search(s, { query: '' });
+        must(c.body.ucp?.version === UCP_VERSION && c.body.ucp.capabilities?.['dev.ucp.shopping.catalog.search'], 'ucp envelope must carry version and the search capability');
+        must(Array.isArray(c.body.products) && c.body.products.length > 0, 'no products; apply a store with products first');
+        must(c.body.pagination?.has_next_page !== undefined, 'pagination.has_next_page is required');
+        for (const p of c.body.products) {
+            must(p.id && p.title && p.description?.plain && p.price_range?.min?.amount !== undefined && p.variants?.length, `product ${p.id ?? '?'} misses a required field`);
+            must(Number.isInteger(p.variants[0].price?.amount) && /^[A-Z]{3}$/.test(p.variants[0].price?.currency), `variant ${p.variants[0].id} price must be integer minor units with a currency`);
+        }
+        variant = c.body.products[0].variants[0];
+        const m = String(variant.fulfillment?.methods?.[0]?.description?.plain ?? '').match(/Ships to ([A-Z]{2})/);
+        if (m)
+            country = m[1];
+        return `${c.body.products.length} products, first variant ${variant.id} at ${variant.price.amount} ${variant.price.currency}`;
+    });
+    if (!variant)
+        return finish(origin, checks);
+    const v = variant;
+    await run('dev.ucp.shopping.catalog.search', 'search filters by query and price', async () => {
+        const c = await shopping.search(s, { query: 'zzz-no-such-product-zzz' });
+        must(c.body.products.length === 0, 'an unmatched query must return no products');
+        const p = await shopping.search(s, { filters: { price: { max: v.price.amount } }, context: { currency: v.price.currency } });
+        must(p.body.products.some((x) => x.variants[0].id === v.id), 'a price filter including the variant must return it');
+        return 'query and price filters apply';
+    });
+    await run('dev.ucp.shopping.catalog.lookup', 'lookup by variant id carries inputs', async () => {
+        const c = await shopping.lookup(s, { ids: [v.id, v.id, 'no-such-id'] });
+        const found = c.body.products.flatMap((p) => p.variants).find((x) => x.id === v.id);
+        must(found, `variant ${v.id} not returned`);
+        must(found.inputs?.some((i) => i.id === v.id && i.match === 'exact'), 'returned variant must list inputs with match exact');
+        must(c.body.products.filter((p) => p.variants.some((x) => x.id === v.id)).length === 1, 'duplicate ids must be deduplicated');
+        return `inputs ok, unknown id reported as ${c.body.messages?.[0]?.code ?? 'nothing'}`;
+    });
+    await run('dev.ucp.shopping.catalog.lookup', 'get product by id, not_found for unknown', async () => {
+        const c = await shopping.product(s, { id: v.id });
+        must(c.body.product?.variants?.[0]?.id === v.id, 'product must be returned with the variant first');
+        const miss = await request(s, 'POST', `${s.endpoint}/catalog/product`, { id: 'no-such-id' });
+        must(miss.status === 200 && miss.body?.ucp?.status === 'error' && miss.body.messages?.[0]?.code === 'not_found', 'unknown id must be a 200 error_response with not_found');
+        return 'ok';
+    });
+    // ---- cart
+    const context = { address_country: country, currency: v.price.currency };
+    let cartId = null;
+    await run('dev.ucp.shopping.cart', 'create, get, update, totals', async () => {
+        const c = await shopping.createCart(s, { line_items: [{ item: { id: v.id }, quantity: 1 }], context });
+        must(c.status === 201, `create must answer 201, got ${c.status}`);
+        const cart = c.body;
+        must(cart.id && cart.currency && cart.line_items?.length === 1 && cart.totals, 'cart misses id, currency, line_items or totals');
+        must(cart.line_items[0].item.price === v.price.amount, 'line item price must match the catalog');
+        must(total(cart.totals) === sum(cart.totals), 'totals: sum of non-total entries must equal total');
+        cartId = cart.id;
+        const got = await shopping.getCart(s, cart.id);
+        must(got.body.id === cart.id, 'get cart must return it');
+        const up = await shopping.updateCart(s, cart.id, { line_items: [{ id: cart.line_items[0].id, item: { id: v.id }, quantity: 2 }], context });
+        must(up.body.line_items[0].quantity === 2 && total(up.body.totals) === v.price.amount * 2, 'update must replace lines and recompute totals');
+        return `cart ${cart.id}, total ${total(up.body.totals)} ${cart.currency} for 2`;
+    });
+    if (s.capabilities.has('dev.ucp.shopping.discount')) {
+        await run('dev.ucp.shopping.discount', 'codes apply and invalid codes warn', async () => {
+            const c = await shopping.createCart(s, { line_items: [{ item: { id: v.id }, quantity: 1 }], context, discounts: { codes: ['SANDBOX10', 'NOPE'] } });
+            const cart = c.body;
+            must(cart.discounts?.applied?.length === 1 && cart.discounts.applied[0].amount > 0, 'SANDBOX10 must be applied with a positive amount');
+            must(cart.totals.some((t) => t.type === 'discount' && t.amount < 0), 'a negative discount total must appear');
+            must(cart.messages?.some((m) => m.type === 'warning' && m.code === 'discount_code_invalid' && m.path === '$.discounts.codes[1]'), 'NOPE must produce a discount_code_invalid warning at its path');
+            must(total(cart.totals) === sum(cart.totals), 'totals identity must hold with discounts');
+            return `${cart.discounts.applied[0].title}: ${cart.discounts.applied[0].amount} off`;
+        });
+    }
+    await run('dev.ucp.shopping.cart', 'cancel returns the cart, then not_found', async () => {
+        const c = await shopping.createCart(s, { line_items: [{ item: { id: v.id }, quantity: 1 }], context });
+        const canceled = await shopping.cancelCart(s, c.body.id);
+        must(canceled.body.id === c.body.id, 'cancel must return the cart');
+        const gone = await request(s, 'GET', `${s.endpoint}/carts/${c.body.id}`);
+        must(gone.body?.ucp?.status === 'error' && gone.body.messages?.[0]?.code === 'not_found', 'a canceled cart must be not_found');
+        return 'ok';
+    });
+    // ---- checkout
+    let ready = null;
+    await run('dev.ucp.shopping.checkout', 'create is incomplete with recoverable messages', async () => {
+        const c = await shopping.createCheckout(s, { line_items: [{ item: { id: v.id }, quantity: 1 }], context });
+        must(c.status === 201, `create must answer 201, got ${c.status}`);
+        const ck = c.body;
+        must(ck.status === 'incomplete', `expected incomplete, got ${ck.status}`);
+        must(ck.ucp?.payment_handlers && Object.keys(ck.ucp.payment_handlers).length, 'checkout responses must carry ucp.payment_handlers');
+        must(Array.isArray(ck.links) && ck.links.some((l) => l.type === 'privacy_policy') && ck.links.some((l) => l.type === 'terms_of_service'), 'links must include privacy_policy and terms_of_service');
+        must(ck.messages?.every((m) => m.type !== 'error' || m.severity === 'recoverable'), 'errors on a fresh checkout must be recoverable');
+        must(/^https:\/\//.test(ck.continue_url ?? ''), 'continue_url must be an absolute HTTPS URL');
+        ready = ck;
+        return `${ck.id}: ${(ck.messages ?? []).map((m) => m.code).join(', ')}`;
+    });
+    if (!ready)
+        return finish(origin, checks);
+    let ck = ready;
+    await run('dev.ucp.shopping.checkout', 'rejects an update without line_items', async () => {
+        const c = await shopping.updateCheckout(s, ck.id, { buyer: TEST_BUYER });
+        must(c.body.messages?.some((m) => m.type === 'error'), 'update without line_items must be refused with an error message');
+        return 'refused';
+    });
+    if (s.capabilities.has('dev.ucp.shopping.fulfillment')) {
+        await run('dev.ucp.shopping.fulfillment', 'address selection yields options and the fulfillment total', async () => {
+            const u = replay(ck);
+            u.buyer = TEST_BUYER;
+            u.fulfillment.methods[0].destinations = [testAddress(country)];
+            u.fulfillment.methods[0].selected_destination_id = 'dest_1';
+            const c = await shopping.updateCheckout(s, ck.id, u);
+            ck = c.body;
+            const method = ck.fulfillment?.methods?.[0];
+            must(method?.selected_destination_id === 'dest_1' && method.destinations?.length === 1 && method.destinations[0].type === 'shipping_address', 'the selected destination must be echoed with type shipping_address');
+            must(method.groups?.[0]?.options?.length && method.groups[0].selected_option_id, 'a group with options and a selected option is expected');
+            must(ck.totals.some((t) => t.type === 'fulfillment'), 'a fulfillment total is expected');
+            must(ck.status === 'ready_for_complete', `expected ready_for_complete, got ${ck.status}: ${(ck.messages ?? []).map((m) => m.code).join(', ')}`);
+            return `${method.groups[0].options.map((o) => `${o.title} ${o.totals[0].amount}`).join(', ')}`;
+        });
+        await run('dev.ucp.shopping.fulfillment', 'an undeliverable country is refused', async () => {
+            const u = replay(ck);
+            u.fulfillment.methods[0].destinations = [testAddress('AQ')];
+            u.fulfillment.methods[0].selected_destination_id = 'dest_1';
+            const c = await shopping.updateCheckout(s, ck.id, u);
+            must(c.body.status === 'incomplete' && c.body.messages?.some((m) => m.code === 'address_undeliverable'), 'Antarctica must give address_undeliverable');
+            u.fulfillment.methods[0].destinations = [testAddress(country)];
+            ck = (await shopping.updateCheckout(s, ck.id, u)).body;
+            must(ck.status === 'ready_for_complete', 'the checkout must recover after a valid address');
+            return 'address_undeliverable, then recovered';
+        });
+    }
+    else {
+        const u = replay(ck);
+        u.buyer = TEST_BUYER;
+        ck = (await shopping.updateCheckout(s, ck.id, u)).body;
+    }
+    if (s.capabilities.has('dev.ucp.shopping.buyer_consent')) {
+        await run('dev.ucp.shopping.buyer_consent', 'consent is echoed with descriptions', async () => {
+            const u = replay(ck);
+            u.buyer = { ...TEST_BUYER, consent: { 'dev.ucp.consent.marketing': { granted: false, source: 'platform' } } };
+            const c = await shopping.updateCheckout(s, ck.id, u);
+            ck = c.body;
+            const given = ck.buyer?.consent?.['dev.ucp.consent.marketing'];
+            must(given && given.granted === false && given.source === 'platform' && given.description, 'consent must come back with granted, source and description');
+            return given.description;
+        });
+    }
+    await run('dev.ucp.shopping.checkout', 'totals identity and ready_for_complete', async () => {
+        must(ck.status === 'ready_for_complete', `status is ${ck.status}`);
+        must(ck.totals.filter((t) => t.type === 'subtotal').length === 1 && ck.totals.filter((t) => t.type === 'total').length === 1, 'exactly one subtotal and one total');
+        must(total(ck.totals) === sum(ck.totals), `sum of entries ${sum(ck.totals)} must equal total ${total(ck.totals)}`);
+        return `total ${total(ck.totals)} ${ck.currency}`;
+    });
+    await run('ai.commercelayer.sandbox', 'a declined token fails recoverably', async () => {
+        const c = await shopping.completeCheckout(s, ck.id, { payment: { instruments: [sandboxInstrument(true)] } });
+        must(c.body.status !== 'completed' && c.body.messages?.some((m) => m.code === 'payment_failed' && m.severity === 'recoverable'), 'expected payment_failed, recoverable');
+        return `payment_failed, status ${c.body.status}`;
+    });
+    await run('ai.commercelayer.sandbox', 'an unknown handler is refused', async () => {
+        const pi = { ...sandboxInstrument(), handler_id: 'nope' };
+        const c = await shopping.completeCheckout(s, ck.id, { payment: { instruments: [pi] } });
+        must(c.body.status !== 'completed' && c.body.messages?.some((m) => m.code === 'payment_failed'), 'expected payment_failed');
+        return 'payment_failed';
+    });
+    let completeCall = null;
+    let orderId = null;
+    const key = crypto.randomUUID();
+    const completeBody = { payment: { instruments: [sandboxInstrument()] }, signals: { 'dev.ucp.buyer_ip': '203.0.113.1', 'dev.ucp.user_agent': 'c11r' } };
+    await run('dev.ucp.shopping.checkout', 'complete with the sandbox token places the order', async () => {
+        completeCall = await shopping.completeCheckout(s, ck.id, completeBody, { idempotencyKey: key });
+        const done = completeCall.body;
+        must(done.status === 'completed', `expected completed, got ${done.status}: ${(done.messages ?? []).map((m) => m.code).join(', ')}`);
+        must(done.order?.id && /^https:\/\//.test(done.order.permalink_url ?? ''), 'order.id and order.permalink_url are required');
+        must(done.continue_url === undefined && done.expires_at === undefined, 'completed checkouts should omit continue_url and expires_at');
+        must(JSON.stringify(done.payment ?? {}).includes('"token"') === false, 'the credential token must not be echoed');
+        orderId = done.order.id;
+        return `order ${done.order.id} ${done.order.label ?? ''}`;
+    });
+    await run('signatures', 'the completion response is signed and verifies', async () => {
+        must(completeCall, 'no completion');
+        must(completeCall.digest === 'verified', `Content-Digest ${completeCall.digest ?? 'missing'}`);
+        must(completeCall.signature === 'verified', `Signature ${completeCall.signature ?? 'missing'}`);
+        return 'ES256 over @status, content-digest, content-type';
+    });
+    await run('transport', 'the same Idempotency-Key replays, a different body conflicts', async () => {
+        const again = await request(s, 'POST', `${s.endpoint}/checkout-sessions/${ck.id}/complete`, completeBody, { idempotencyKey: key });
+        must(again.status === completeCall.status && JSON.stringify(again.body) === JSON.stringify(completeCall.body), 'the replay must return the same response');
+        const other = await request(s, 'POST', `${s.endpoint}/checkout-sessions/${ck.id}/complete`, { ...completeBody, attribution: { x: '1' } }, { idempotencyKey: key });
+        must(other.status === 409, `expected 409, got ${other.status}`);
+        return 'replayed, then 409';
+    });
+    await run('dev.ucp.shopping.checkout', 'a completed checkout is immutable; a fresh one cancels', async () => {
+        const c = await shopping.cancelCheckout(s, ck.id);
+        must(c.body.status === 'completed' && c.body.messages?.some((m) => m.severity === 'unrecoverable'), 'cancel after completion must be refused as unrecoverable');
+        const fresh = await shopping.createCheckout(s, { line_items: [{ item: { id: v.id }, quantity: 1 }], context });
+        const canceled = await shopping.cancelCheckout(s, fresh.body.id);
+        must(canceled.body.status === 'canceled', 'a fresh checkout must cancel');
+        return 'ok';
+    });
+    if (cartId) {
+        await run('dev.ucp.shopping.cart', 'checkout from cart_id is idempotent', async () => {
+            const a = await shopping.createCheckout(s, { cart_id: cartId, buyer: TEST_BUYER });
+            must(a.body.line_items?.length === 1 && a.body.line_items[0].quantity === 2, 'the checkout must take the cart lines');
+            const b = await shopping.createCheckout(s, { cart_id: cartId });
+            must(b.body.id === a.body.id, 'a second create for the same cart must return the same checkout');
+            return `checkout ${a.body.id} from cart ${cartId}`;
+        });
+    }
+    // ---- order
+    if (orderId) {
+        const oid = orderId;
+        await run('dev.ucp.shopping.order', 'GET /orders/{id} returns the order entity', async () => {
+            const c = await shopping.getOrder(s, oid);
+            const o = c.body;
+            must(o.id === oid && o.checkout_id === ck.id && o.permalink_url && o.currency === ck.currency, 'id, checkout_id, permalink_url, currency');
+            must(o.line_items?.[0]?.quantity?.total !== undefined && o.line_items[0].quantity.fulfilled !== undefined && o.line_items[0].status === 'processing', 'order line items need quantity {total, fulfilled} and status');
+            must(o.fulfillment && Array.isArray(o.fulfillment.expectations ?? []) && Array.isArray(o.fulfillment.events ?? []), 'fulfillment with expectations and events');
+            must(total(o.totals) === total(ck.totals), 'order totals must match the checkout');
+            const miss = await request(s, 'GET', `${s.endpoint}/orders/no-such-order`);
+            must(miss.body?.ucp?.status === 'error' && miss.body.messages?.[0]?.code === 'not_found', 'unknown order must be not_found');
+            return `${o.label ?? o.id}, ${o.fulfillment.expectations?.length ?? 0} expectation(s)`;
+        });
+        await run('dev.ucp.shopping.order', 'orders are private: a bad token is challenged', async () => {
+            const c = await request(s, 'GET', `${s.endpoint}/orders/${oid}`, undefined, { bearer: 'not-a-token' });
+            must(c.status === 401 && /^Bearer realm=/.test(c.headers['www-authenticate'] ?? ''), `expected 401 with WWW-Authenticate: Bearer, got ${c.status}`);
+            must(c.body?.messages?.[0]?.code === 'identity_required', 'the body must carry identity_required');
+            return '401 identity_required';
+        });
+    }
+    // ---- identity linking
+    if (s.capabilities.has('dev.ucp.common.identity_linking')) {
+        await run('dev.ucp.common.identity_linking', 'OAuth metadata, PKCE and token exchange', async () => {
+            const meta = await send('GET', `${origin}/.well-known/oauth-authorization-server`, {});
+            must(meta.status === 200, `metadata answered ${meta.status}`);
+            const m = JSON.parse(meta.body);
+            for (const f of ['issuer', 'authorization_endpoint', 'token_endpoint', 'revocation_endpoint', 'jwks_uri', 'scopes_supported', 'code_challenge_methods_supported'])
+                must(m[f], `metadata misses ${f}`);
+            must(m.code_challenge_methods_supported.includes('S256') && m.authorization_response_iss_parameter_supported === true, 'S256 and iss support are required');
+            must(m.scopes_supported.includes('dev.ucp.shopping.order:read'), 'scopes_supported must list dev.ucp.shopping.order:read');
+            const verifier = crypto.randomBytes(32).toString('base64url');
+            const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+            const authz = new URL(m.authorization_endpoint);
+            authz.search = new URLSearchParams({ response_type: 'code', client_id: 'c11r-check', redirect_uri: 'https://commercelayer.ai/ucp/agent-cli/callback', scope: 'dev.ucp.shopping.order:read', state: 'xyz', code_challenge: challenge, code_challenge_method: 'S256' }).toString();
+            const a = await send('GET', authz.toString(), {});
+            must(a.status === 302 && a.headers.location, `authorize must redirect, got ${a.status}`);
+            const loc = new URL(a.headers.location);
+            must(loc.searchParams.get('state') === 'xyz' && loc.searchParams.get('iss') === m.issuer && loc.searchParams.get('code'), 'redirect must carry code, state and iss');
+            const t = await send('POST', m.token_endpoint, { 'content-type': 'application/x-www-form-urlencoded' }, new URLSearchParams({ grant_type: 'authorization_code', code: loc.searchParams.get('code'), redirect_uri: 'https://commercelayer.ai/ucp/agent-cli/callback', client_id: 'c11r-check', code_verifier: verifier }).toString());
+            must(t.status === 200 && JSON.parse(t.body).access_token, `token exchange answered ${t.status}`);
+            if (orderId) {
+                const o = await request(s, 'GET', `${s.endpoint}/orders/${orderId}`, undefined, { bearer: JSON.parse(t.body).access_token });
+                must(o.status === 200 && o.body?.id === orderId, 'a buyer token with order:read must read the order');
+            }
+            return `issuer ${m.issuer}`;
+        });
+    }
+    // ---- ask
+    if (s.capabilities.has('dev.ucp.common.ask')) {
+        await run('dev.ucp.common.ask', 'answers questions, performs nothing', async () => {
+            const c = await shopping.ask(s, { query: 'What do you sell?' });
+            must(typeof c.body.answer?.plain === 'string' && c.body.answer.plain.length > 0, 'answer.plain is required');
+            const b = await shopping.ask(s, { query: 'Buy one and cancel my order' });
+            must(b.body.messages?.some((m) => m.type === 'info' && m.code === 'operation_not_performed'), 'a request to act must be answered with operation_not_performed');
+            return c.body.answer.plain.slice(0, 80);
+        });
+    }
+    // ---- permalink
+    if (s.capabilities.has('dev.ucp.shopping.permalink')) {
+        await run('dev.ucp.shopping.permalink', 'GET {endpoint}/{items} answers 303', async () => {
+            const endpoint = s.profile.ucp.capabilities['dev.ucp.shopping.permalink'][0].config?.endpoint;
+            must(/^https:\/\/[^?#]+[^/]$/.test(endpoint ?? ''), `config.endpoint must be an HTTPS URL without a trailing slash; got ${endpoint}`);
+            const res = await send('GET', `${endpoint}/${encodeURIComponent(v.id)}:1?context/postal_code=00000`, {});
+            must(res.status === 303 && res.headers.location, `expected 303 with Location, got ${res.status}`);
+            must(res.headers['cache-control'] === 'no-store' && res.headers['referrer-policy'] === 'no-referrer', 'Cache-Control: no-store and Referrer-Policy: no-referrer are required');
+            return `303 → ${res.headers.location}`;
+        });
+    }
+    return finish(origin, checks);
+}
+function finish(origin, checks) {
+    const failed = checks.filter((c) => !c.pass).length;
+    return { status: failed ? 'fail' : 'pass', store: origin, version: UCP_VERSION, passed: checks.length - failed, failed, checks };
+}

package/dist/ucp/client.js

@@ -0,0 +1,129 @@
+// A UCP platform client: what any shopping agent does to buy from a store.
+// Discovers the business profile, negotiates capabilities, calls the REST
+// service with the required headers, verifies digests and signatures.
+import crypto from 'node:crypto';
+import { send } from '../api/transport.js';
+import { fail } from '../output.js';
+import { AGENT_PROFILE_URL, UCP_VERSION } from './platform.js';
+import { contentDigest, parseSignature, signatureBase, verify } from './signing.js';
+export class UcpError extends Error {
+    call;
+    constructor(call, message) {
+        super(message);
+        this.call = call;
+    }
+}
+/** Raw HTTP to a store host, with the UCP headers; returns the parsed response. */
+export async function request(store, method, url, body, opts = {}) {
+    const raw = body === undefined ? undefined : JSON.stringify(body);
+    const headers = { accept: 'application/json' };
+    const omit = new Set(opts.omit ?? []);
+    if (!omit.has('ucp-agent'))
+        headers['ucp-agent'] = `profile="${AGENT_PROFILE_URL}"`;
+    if (!omit.has('request-id'))
+        headers['request-id'] = crypto.randomUUID();
+    if ((method === 'POST' || method === 'PUT') && !omit.has('idempotency-key') && !/\/catalog\/|\/ask$/.test(url)) {
+        headers['idempotency-key'] = opts.idempotencyKey ?? crypto.randomUUID();
+    }
+    if (raw !== undefined)
+        headers['content-digest'] = contentDigest(raw);
+    if (opts.bearer)
+        headers.authorization = `Bearer ${opts.bearer}`;
+    const res = await send(method, url, headers, raw);
+    return inspect(store.keys, method, url, res);
+}
+function inspect(keys, method, url, res) {
+    let body = null;
+    try {
+        body = res.body ? JSON.parse(res.body) : null;
+    }
+    catch {
+        body = null;
+    }
+    const call = { method, url, status: res.status, headers: res.headers, body };
+    if (res.headers['content-digest'])
+        call.digest = res.headers['content-digest'] === contentDigest(res.body) ? 'verified' : 'mismatch';
+    const sig = parseSignature(res.headers['signature-input'], res.headers.signature);
+    if (sig) {
+        const key = keys.find((k) => k.kid === sig.params.keyid);
+        if (!key)
+            call.signature = 'unknown_key';
+        else {
+            const values = { '@status': String(res.status), 'content-digest': res.headers['content-digest'] ?? '', 'content-type': res.headers['content-type'] ?? '' };
+            call.signature = verify(signatureBase(values, sig.params), sig.signature, key) ? 'verified' : 'invalid';
+        }
+    }
+    return call;
+}
+/** Fetch /.well-known/ucp and work out what we can do with this store. */
+export async function discover(origin) {
+    const res = await send('GET', `${origin}/.well-known/ucp`, { accept: 'application/json' });
+    if (res.status !== 200)
+        fail('ucp_profile_unreachable', `${origin}/.well-known/ucp answered ${res.status}.`, 'The store does not speak UCP, or the sandbox expired. Run `c11r status`.');
+    let profile;
+    try {
+        profile = JSON.parse(res.body);
+    }
+    catch {
+        fail('ucp_profile_malformed', `${origin}/.well-known/ucp is not JSON.`, 'Report it at https://commercelayer.ai/support with the output of `c11r status`.');
+    }
+    const ucp = profile.ucp ?? {};
+    if (ucp.version !== UCP_VERSION) {
+        fail('ucp_version_unsupported', `The store speaks UCP ${ucp.version}; this CLI speaks ${UCP_VERSION}.`, 'Update the CLI: npx -y @commercelayer/agent-cli@latest.');
+    }
+    const rest = (name) => (ucp.services?.[name] ?? []).find((s) => s.transport === 'rest')?.endpoint ?? null;
+    const endpoint = rest('dev.ucp.shopping');
+    if (!endpoint)
+        fail('ucp_no_rest_service', 'The store profile has no REST dev.ucp.shopping service.', 'Report it at https://commercelayer.ai/support.');
+    const capabilities = new Set();
+    for (const [name, entries] of Object.entries(ucp.capabilities ?? {})) {
+        if (entries.some((e) => e.version === UCP_VERSION))
+            capabilities.add(name);
+    }
+    return { origin, profile, endpoint, commonEndpoint: rest('dev.ucp.common'), capabilities, keys: profile.keys ?? [] };
+}
+/** A call that must come back with a UCP resource; throws UcpError otherwise. */
+async function expectResource(call, what) {
+    const c = await call;
+    if (c.status >= 400)
+        throw new UcpError(c, `${what}: the store answered ${c.status}${c.body?.code ? ` ${c.body.code}` : ''}.`);
+    if (c.body?.ucp?.status === 'error')
+        throw new UcpError(c, `${what}: ${c.body.messages?.map((m) => `${m.code}: ${m.content}`).join('; ')}`);
+    return c;
+}
+export const shopping = {
+    search: (s, body) => expectResource(request(s, 'POST', `${s.endpoint}/catalog/search`, body), 'catalog search'),
+    lookup: (s, body) => expectResource(request(s, 'POST', `${s.endpoint}/catalog/lookup`, body), 'catalog lookup'),
+    product: (s, body) => expectResource(request(s, 'POST', `${s.endpoint}/catalog/product`, body), 'get product'),
+    createCart: (s, body, o) => expectResource(request(s, 'POST', `${s.endpoint}/carts`, body, o), 'create cart'),
+    getCart: (s, id) => expectResource(request(s, 'GET', `${s.endpoint}/carts/${id}`), 'get cart'),
+    updateCart: (s, id, body) => expectResource(request(s, 'PUT', `${s.endpoint}/carts/${id}`, body), 'update cart'),
+    cancelCart: (s, id) => expectResource(request(s, 'POST', `${s.endpoint}/carts/${id}/cancel`, {}), 'cancel cart'),
+    createCheckout: (s, body, o) => expectResource(request(s, 'POST', `${s.endpoint}/checkout-sessions`, body, o), 'create checkout'),
+    getCheckout: (s, id) => expectResource(request(s, 'GET', `${s.endpoint}/checkout-sessions/${id}`), 'get checkout'),
+    updateCheckout: (s, id, body) => expectResource(request(s, 'PUT', `${s.endpoint}/checkout-sessions/${id}`, body), 'update checkout'),
+    completeCheckout: (s, id, body, o) => expectResource(request(s, 'POST', `${s.endpoint}/checkout-sessions/${id}/complete`, body, o), 'complete checkout'),
+    cancelCheckout: (s, id) => expectResource(request(s, 'POST', `${s.endpoint}/checkout-sessions/${id}/cancel`, {}), 'cancel checkout'),
+    getOrder: (s, id, o) => expectResource(request(s, 'GET', `${s.endpoint}/orders/${id}`, undefined, o), 'get order'),
+    ask: (s, body) => expectResource(request(s, 'POST', `${s.commonEndpoint ?? s.endpoint}/ask`, body), 'ask'),
+};
+/** The update payload for a checkout: everything the platform may write, re-sent whole. */
+export function replay(checkout) {
+    const out = { line_items: checkout.line_items.map((l) => ({ id: l.id, item: { id: l.item.id }, quantity: l.quantity })) };
+    for (const k of ['buyer', 'context', 'signals', 'attribution', 'discounts'])
+        if (checkout[k] !== undefined)
+            out[k] = k === 'discounts' ? { codes: checkout.discounts.codes ?? [] } : checkout[k];
+    if (checkout.fulfillment?.methods) {
+        out.fulfillment = {
+            methods: checkout.fulfillment.methods.map((m) => ({
+                id: m.id,
+                type: m.type,
+                line_item_ids: m.line_item_ids,
+                destinations: m.destinations,
+                selected_destination_id: m.selected_destination_id ?? null,
+                groups: (m.groups ?? []).map((g) => ({ id: g.id, selected_option_id: g.selected_option_id ?? null })),
+            })),
+        };
+    }
+    return out;
+}