@commercelayer/agent-cli 0.8.1 → 1.0.0-dev.1

package/dist/ucp/check.js

@@ -1,362 +0,0 @@
-// 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';
-/** One nonsense word, no space or hyphen: the store's search splits a query into words, and "no" or "product" match real descriptions. */
-export const UNMATCHED_QUERY = 'qxzjvwkq';
-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: UNMATCHED_QUERY });
-        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 placed;
-    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;
-        placed = { id: done.order.id, label: done.order.label };
-        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, placed);
-}
-function finish(origin, checks, order) {
-    const failed = checks.filter((c) => !c.pass).length;
-    const report = { status: failed ? 'fail' : 'pass', store: origin, version: UCP_VERSION, passed: checks.length - failed, failed, checks };
-    if (order)
-        report.order = order;
-    return report;
-}

package/dist/ucp/client.js

@@ -1,129 +0,0 @@
-// 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.`, 'The store host answered badly. Try again; if it keeps happening, tell the human, 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.', 'The store host serves a profile this CLI cannot use. Tell the human, with the output of `c11r ucp profile`.');
-    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;
-}

package/dist/ucp/images.js

@@ -1,62 +0,0 @@
-// --images: each product's image_url saved as a file, for agents that can read images and
-// want to look at or describe a product. Files go under <tmpdir>/c11r/images/<store host>/,
-// named by product id and a hash of the URL, so a file already there is reused and a new
-// image gets a new file. A chat thumbnail needs only image_url, never this.
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { download } from '../api/transport.js';
-export const MAX_IMAGES = 24;
-const TIMEOUT_MS = 5000;
-const MAX_BYTES = 10 * 1024 * 1024;
-const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/avif': 'avif', 'image/svg+xml': 'svg' };
-/** The folder of a store's images: C11R_IMAGES_DIR (tests) or the OS temp dir. */
-export const imagesDir = (origin) => path.join(process.env.C11R_IMAGES_DIR ?? path.join(os.tmpdir(), 'c11r', 'images'), new URL(origin).host);
-const safe = (s) => s.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 80) || 'product';
-/** One product's image: the path of its file, or why there is none. */
-async function fetchImage(dir, p) {
-    const url = p.image_url;
-    if (typeof url !== 'string' || !url)
-        return { image_error: 'The product has no image_url.' };
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        return { image_error: `image_url ${url} is not a URL.` };
-    }
-    if (!['https:', 'http:'].includes(parsed.protocol))
-        return { image_error: `image_url ${url} is not an http(s) address.` };
-    const stem = `${safe(String(p.id ?? ''))}-${crypto.createHash('sha256').update(url).digest('hex').slice(0, 10)}`;
-    const kept = fs.existsSync(dir) ? fs.readdirSync(dir).find((f) => f.startsWith(`${stem}.`) && Object.values(EXT).includes(f.slice(stem.length + 1))) : undefined;
-    if (kept)
-        return { image_file: path.join(dir, kept) };
-    try {
-        const r = await download(url, TIMEOUT_MS);
-        if (r.status !== 200)
-            return { image_error: `The store answered ${r.status} for ${url}.` };
-        const ext = EXT[r.type.split(';')[0].trim().toLowerCase()];
-        if (!ext)
-            return { image_error: `${url} is not an image (content-type ${r.type || 'missing'}).` };
-        if (r.bytes.length > MAX_BYTES)
-            return { image_error: `${url} is over 10 MB.` };
-        fs.mkdirSync(dir, { recursive: true });
-        const file = path.join(dir, `${stem}.${ext}`);
-        // Written aside then renamed, so a parallel run never reads half a file.
-        const tmp = `${file}.${process.pid}.part`;
-        fs.writeFileSync(tmp, r.bytes);
-        fs.renameSync(tmp, file);
-        return { image_file: file };
-    }
-    catch (e) {
-        const err = e;
-        return { image_error: err.name === 'TimeoutError' ? `${url} took more than ${TIMEOUT_MS / 1000} s.` : `Could not download ${url}: ${err.message}` };
-    }
-}
-/** Products with image_file or image_error, the first MAX_IMAGES in parallel; how many were left out. */
-export async function withImages(origin, products) {
-    const dir = imagesDir(origin);
-    const got = await Promise.all(products.slice(0, MAX_IMAGES).map((p) => fetchImage(dir, p)));
-    return { products: products.map((p, i) => (i < MAX_IMAGES ? { ...p, ...got[i] } : p)), skipped: Math.max(0, products.length - MAX_IMAGES) };
-}