@artos-commerce/ucp-client 0.1.1 → 0.2.0

package/README.md

@@ -1,16 +1,17 @@
 # @artos-commerce/ucp-client
 
-**Path B Direct UCP client for Artos.** A typed UCP transport, AP2 mandate
-signing, and checkout orchestration so you can build your own commerce-grade UCP
-client against `api.artos.sh` — without hand-rolling the JSON-RPC envelope, the
-canonical-JSON signing bytes, the AP2 mandates, or the payment-rail rules.
+**Build-track Direct UCP client for Artos.** A typed UCP transport, AP2 mandate
+signing, checkout orchestration, buyer-account tools, and buyer OAuth so you can
+build your own commerce-grade UCP client against `api.artos.sh` — without
+hand-rolling the JSON-RPC envelope, the canonical-JSON signing bytes, the AP2
+mandates, or the payment-rail rules.
 
 This is the reusable core extracted from the hosted Artos MCP bridge. If you just
-want an MCP endpoint for AI agents, point them at the hosted bridge
-(`https://agent.artos.sh/mcp`, **Path A**) and skip this package. Reach for
-`@artos-commerce/ucp-client` when you are building your **own** client/integration
-(**Path B**) and want the hard parts — signing, verification, and rail selection
-— done correctly for you.
+want an MCP endpoint for AI agents, point them at the hosted **Connect** bridge
+(`https://agent.artos.sh/mcp`) and skip this package. Reach for
+`@artos-commerce/ucp-client` when you are building your **own**
+client/integration (the **Build** track) and want the hard parts — signing,
+verification, and rail selection — done correctly for you.
 
 ## What it does for you
 
@@ -25,6 +26,12 @@ want an MCP endpoint for AI agents, point them at the hosted bridge
 - **Checkout orchestration** (`createCheckoutHandlers`): a single
   `confirmPurchase` re-prices, verifies, mints the mandate, routes to the
   `$0` / card / crypto rail, and returns a structured `CheckoutOutcome`.
+- **Buyer-account tools** (`createAccountHandlers`): typed wrappers over the
+  buyer's account MCP (`get_buyer_context`, `list_my_orders`, wallet balances,
+  coupons, …) — all buyer-bound.
+- **Buyer OAuth** (`OAuthClient` + `createPkce`): discover the Authorization
+  Server, build the PKCE authorize URL, and exchange/refresh tokens so a
+  Build-track agent can run buyer sign-in itself.
 
 ## Install
 
@@ -118,6 +125,46 @@ switch (outcome.status) {
 throw `UcpClientError`; an expired buyer bearer throws `UcpAuthError` carrying
 the `WWW-Authenticate` challenge.
 
+### Buyer sign-in (OAuth) and account tools
+
+A Build-track agent can run the buyer-OAuth dance itself instead of relying on
+the hosted Connect bridge:
+
+```ts
+import { OAuthClient, createPkce } from '@artos-commerce/ucp-client';
+
+const oauth = new OAuthClient({ artosBaseUrl: 'https://api.artos.sh' });
+const pkce = createPkce();
+
+// 1. Send the buyer here to sign in + consent (offline_access by default).
+const { url, state } = await oauth.authorizeUrl({
+  clientId: 'https://you.example/well-known/oauth-client.json',
+  redirectUri: 'https://you.example/oauth/callback',
+  codeChallenge: pkce.challenge,
+});
+
+// 2. On the redirect (verify `state`), exchange the code for tokens.
+const tokens = await oauth.exchangeCode({
+  code,
+  codeVerifier: pkce.verifier,
+  clientId: 'https://you.example/well-known/oauth-client.json',
+  redirectUri: 'https://you.example/oauth/callback',
+});
+
+// 3. Later, silently renew with the rotating refresh token.
+const fresh = await oauth.refresh({ refreshToken: tokens.refreshToken! });
+```
+
+With `tokens.accessToken` as the `buyerToken`, the account tools are typed:
+
+```ts
+import { createAccountHandlers } from '@artos-commerce/ucp-client';
+
+const account = createAccountHandlers({ client }); // client carries buyerToken
+const me = await account.getBuyerContext();
+const orders = await account.listOrders({ limit: 10 });
+```
+
 ## The two-credential auth model
 
 The Artos API's identity guard prefers `X-API-Key` over a bearer. `UcpClient`
@@ -139,12 +186,14 @@ Never send both for a buyer-bound call.
 - `Ap2Signer` — `mintCheckoutMandate`, `mintPaymentMandate`.
 - `canonicalJson`, `verifyDetachedJws`, `verifyMerchantAuthorization`.
 - `createCheckoutHandlers` — read tools + `confirmPurchase`.
+- `createAccountHandlers` — typed buyer-account tools (buyer-bound).
+- `OAuthClient`, `createPkce`, `DEFAULT_BUYER_SCOPE` — buyer OAuth (PKCE).
 - `SuiSigner`, `resolveCryptoDeps` (crypto rail; need `@mysten/sui`).
 - Helpers: `toMinorUnits`, `normalizeSearchFilters`, `resolveRail`,
   `grandTotal`, `currencyOf`, `asAllowanceId`, `isUcpError`, `messageOf`.
 
 Subpath entries are also published: `@artos-commerce/ucp-client/ucp`,
-`/ap2`, `/checkout`, `/sui`, `/crypto`.
+`/ap2`, `/checkout`, `/account`, `/oauth`, `/sui`, `/crypto`.
 
 ## Security notes
 

package/dist/account/handlers.d.ts

@@ -0,0 +1,43 @@
+import type { AccountToolSpec, UcpClient } from '../ucp/client.js';
+/** Dependencies the account handlers operate over (injectable for tests). */
+export interface AccountDeps {
+    client: UcpClient;
+}
+/**
+ * Typed convenience wrappers over the buyer-account MCP tools (`POST
+ * /account/mcp`). Every call is **buyer-bound**: the {@link UcpClient} must carry
+ * a buyer OAuth bearer (`buyerToken`) or the API answers 401 (relayed as a
+ * {@link import('../ucp/client.js').UcpAuthError}). The buyer is always resolved
+ * server-side from the bearer — never passed in args. Each method returns the
+ * tool's `structuredContent` payload (a plain JSON resource, possibly a UCP
+ * business-error envelope inspectable via `isUcpError`).
+ *
+ * Mirrors {@link import('../checkout/handlers.js').createCheckoutHandlers}: pure
+ * handlers over an injected client, so a host unit-tests them with a fake.
+ */
+export declare function createAccountHandlers(deps: AccountDeps): {
+    /** Lists the buyer-account tools the API advertises (`tools/list`). */
+    listTools(): Promise<AccountToolSpec[]>;
+    /** The buyer's profile + session context. */
+    getBuyerContext(): Promise<Record<string, unknown>>;
+    /** The buyer's saved shipping/billing addresses. */
+    listAddresses(): Promise<Record<string, unknown>>;
+    /** The buyer's orders across all stores. */
+    listOrders(args?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** A single order by id. */
+    getOrder(id: string): Promise<Record<string, unknown>>;
+    /** The buyer's returns. */
+    listReturns(): Promise<Record<string, unknown>>;
+    /** The buyer's on-chain wallet balances. */
+    getWalletBalances(): Promise<Record<string, unknown>>;
+    /** The buyer's available coupons. */
+    listCoupons(): Promise<Record<string, unknown>>;
+    /** The buyer's gift cards. */
+    listGifts(): Promise<Record<string, unknown>>;
+    /** Claims a gift by code. */
+    claimGift(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Escape hatch: call any account tool by name (future-proof). */
+    call(name: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
+};
+/** The handler object returned by {@link createAccountHandlers}. */
+export type AccountHandlers = ReturnType<typeof createAccountHandlers>;

package/dist/account/handlers.js

@@ -0,0 +1,62 @@
+/**
+ * Typed convenience wrappers over the buyer-account MCP tools (`POST
+ * /account/mcp`). Every call is **buyer-bound**: the {@link UcpClient} must carry
+ * a buyer OAuth bearer (`buyerToken`) or the API answers 401 (relayed as a
+ * {@link import('../ucp/client.js').UcpAuthError}). The buyer is always resolved
+ * server-side from the bearer — never passed in args. Each method returns the
+ * tool's `structuredContent` payload (a plain JSON resource, possibly a UCP
+ * business-error envelope inspectable via `isUcpError`).
+ *
+ * Mirrors {@link import('../checkout/handlers.js').createCheckoutHandlers}: pure
+ * handlers over an injected client, so a host unit-tests them with a fake.
+ */
+export function createAccountHandlers(deps) {
+    const { client } = deps;
+    return {
+        /** Lists the buyer-account tools the API advertises (`tools/list`). */
+        listTools() {
+            return client.listAccountTools();
+        },
+        /** The buyer's profile + session context. */
+        getBuyerContext() {
+            return client.callAccountTool('get_buyer_context', {});
+        },
+        /** The buyer's saved shipping/billing addresses. */
+        listAddresses() {
+            return client.callAccountTool('list_my_addresses', {});
+        },
+        /** The buyer's orders across all stores. */
+        listOrders(args = {}) {
+            return client.callAccountTool('list_my_orders', args);
+        },
+        /** A single order by id. */
+        getOrder(id) {
+            return client.callAccountTool('get_my_order', { id });
+        },
+        /** The buyer's returns. */
+        listReturns() {
+            return client.callAccountTool('list_my_returns', {});
+        },
+        /** The buyer's on-chain wallet balances. */
+        getWalletBalances() {
+            return client.callAccountTool('get_wallet_balances', {});
+        },
+        /** The buyer's available coupons. */
+        listCoupons() {
+            return client.callAccountTool('list_my_coupons', {});
+        },
+        /** The buyer's gift cards. */
+        listGifts() {
+            return client.callAccountTool('list_my_gifts', {});
+        },
+        /** Claims a gift by code. */
+        claimGift(args) {
+            return client.callAccountTool('claim_gift', args);
+        },
+        /** Escape hatch: call any account tool by name (future-proof). */
+        call(name, args = {}) {
+            return client.callAccountTool(name, args);
+        },
+    };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/account/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/account/handlers.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAiB;IACrD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAExB,OAAO;QACL,uEAAuE;QACvE,SAAS;YACP,OAAO,MAAM,CAAC,gBAAgB,EAAE,CAAC;QACnC,CAAC;QAED,6CAA6C;QAC7C,eAAe;YACb,OAAO,MAAM,CAAC,eAAe,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;QACzD,CAAC;QAED,oDAAoD;QACpD,aAAa;YACX,OAAO,MAAM,CAAC,eAAe,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;QACzD,CAAC;QAED,4CAA4C;QAC5C,UAAU,CACR,OAAgC,EAAE;YAElC,OAAO,MAAM,CAAC,eAAe,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACxD,CAAC;QAED,4BAA4B;QAC5B,QAAQ,CAAC,EAAU;YACjB,OAAO,MAAM,CAAC,eAAe,CAAC,cAAc,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,2BAA2B;QAC3B,WAAW;YACT,OAAO,MAAM,CAAC,eAAe,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,4CAA4C;QAC5C,iBAAiB;YACf,OAAO,MAAM,CAAC,eAAe,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;QAC3D,CAAC;QAED,qCAAqC;QACrC,WAAW;YACT,OAAO,MAAM,CAAC,eAAe,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,8BAA8B;QAC9B,SAAS;YACP,OAAO,MAAM,CAAC,eAAe,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,6BAA6B;QAC7B,SAAS,CAAC,IAA6B;YACrC,OAAO,MAAM,CAAC,eAAe,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACpD,CAAC;QAED,kEAAkE;QAClE,IAAI,CACF,IAAY,EACZ,OAAgC,EAAE;YAElC,OAAO,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ap2/canonical-json.d.ts

@@ -1,7 +1,7 @@
 /**
  * Sorted-key canonical JSON serialization, byte-for-byte identical to the
  * artos-api implementation (`src/modules/ucp/crypto/canonical-json.ts`) and the
- * copies in artos-mcp-bridge / artos-my / artos-storefront. Used to recompute
+ * copies in artos-agent / artos-my / artos-storefront. Used to recompute
  * the bytes a store's `merchant_authorization` (and an AP2 mandate) is signed
  * over, so a signature verifies across every repo.
  *

package/dist/ap2/canonical-json.js

@@ -1,7 +1,7 @@
 /**
  * Sorted-key canonical JSON serialization, byte-for-byte identical to the
  * artos-api implementation (`src/modules/ucp/crypto/canonical-json.ts`) and the
- * copies in artos-mcp-bridge / artos-my / artos-storefront. Used to recompute
+ * copies in artos-agent / artos-my / artos-storefront. Used to recompute
  * the bytes a store's `merchant_authorization` (and an AP2 mandate) is signed
  * over, so a signature verifies across every repo.
  *

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export { UCP_VERSION, normalizeBaseUrl, assertEcP256PrivateJwk, parseSuiNetwork,
 export { UcpClient, UcpClientError, UcpAuthError, messageOf, isUcpError, type UcpResponse, type UcpClientOptions, type UcpAuthMode, type StoreToolOptions, type AccountToolSpec, type ToolAnnotations, } from './ucp/client.js';
 export { canonicalJson, verifyDetachedJws, verifyMerchantAuthorization, Ap2Signer, type CheckoutMandateClaims, type PaymentMandateClaims, } from './ap2/index.js';
 export { createCheckoutHandlers, toMinorUnits, normalizeSearchFilters, availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, type CheckoutHandlers, type CheckoutDeps, type CheckoutLineItem, type ConfirmPurchaseInput, type CheckoutErrorCode, type CheckoutOutcome, type SearchFilters, type ResolvedRail, } from './checkout/index.js';
+export { createAccountHandlers, type AccountHandlers, type AccountDeps, } from './account/handlers.js';
+export { OAuthClient, OAuthClientError, createPkce, DEFAULT_BUYER_SCOPE, type AuthorizationServerMetadata, type OAuthTokens, type Pkce, type OAuthClientConfig, type OAuthClientOptions, } from './oauth/client.js';
 export { resolveCryptoDeps, type CryptoDeps } from './crypto/deps.js';
 export { SuiSigner, SuiSignerError } from './sui/signer.js';

package/dist/index.js

@@ -6,6 +6,10 @@ export { UcpClient, UcpClientError, UcpAuthError, messageOf, isUcpError, } from
 export { canonicalJson, verifyDetachedJws, verifyMerchantAuthorization, Ap2Signer, } from './ap2/index.js';
 // Checkout orchestration
 export { createCheckoutHandlers, toMinorUnits, normalizeSearchFilters, availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, } from './checkout/index.js';
+// Buyer-account tools
+export { createAccountHandlers, } from './account/handlers.js';
+// Buyer OAuth (PKCE authorize + token exchange/refresh)
+export { OAuthClient, OAuthClientError, createPkce, DEFAULT_BUYER_SCOPE, } from './oauth/client.js';
 // Crypto rail (requires the optional `@mysten/sui` peer dependency)
 export { resolveCryptoDeps } from './crypto/deps.js';
 export { SuiSigner, SuiSignerError } from './sui/signer.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,GAMhB,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EACL,SAAS,EACT,cAAc,EACd,YAAY,EACZ,SAAS,EACT,UAAU,GAOX,MAAM,iBAAiB,CAAC;AAEzB,MAAM;AACN,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,2BAA2B,EAC3B,SAAS,GAGV,MAAM,gBAAgB,CAAC;AAExB,yBAAyB;AACzB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GASd,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AACpE,OAAO,EAAE,iBAAiB,EAAmB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,GAMhB,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EACL,SAAS,EACT,cAAc,EACd,YAAY,EACZ,SAAS,EACT,UAAU,GAOX,MAAM,iBAAiB,CAAC;AAEzB,MAAM;AACN,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,2BAA2B,EAC3B,SAAS,GAGV,MAAM,gBAAgB,CAAC;AAExB,yBAAyB;AACzB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GASd,MAAM,qBAAqB,CAAC;AAE7B,sBAAsB;AACtB,OAAO,EACL,qBAAqB,GAGtB,MAAM,uBAAuB,CAAC;AAE/B,wDAAwD;AACxD,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,mBAAmB,GAMpB,MAAM,mBAAmB,CAAC;AAE3B,oEAAoE;AACpE,OAAO,EAAE,iBAAiB,EAAmB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/oauth/client.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The buyer-auth scopes a Build-track agent should request: `purchase:complete`
+ * to place orders, and `offline_access` so the API mints a rotating refresh
+ * token (without it the buyer must re-consent every time the access token
+ * expires).
+ */
+export declare const DEFAULT_BUYER_SCOPE = "purchase:complete offline_access";
+/** RFC 8414 Authorization Server metadata (the fields this client uses). */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    scopes_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    [k: string]: unknown;
+}
+/** A normalized OAuth token response. */
+export interface OAuthTokens {
+    accessToken: string;
+    tokenType: string;
+    /** Access-token lifetime in seconds. */
+    expiresIn: number;
+    /** Present only when `offline_access` was granted. */
+    refreshToken?: string;
+    scope?: string;
+}
+/** A PKCE (RFC 7636) verifier/challenge pair (S256). */
+export interface Pkce {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+/** Raised for OAuth discovery / token errors (carries the RFC 6749 `error`). */
+export declare class OAuthClientError extends Error {
+    readonly error: string;
+    constructor(error: string, description?: string);
+}
+type FetchLike = typeof fetch;
+/**
+ * Generates a PKCE pair: a high-entropy `verifier` and its S256 `challenge`. Send
+ * the challenge on the authorize request; keep the verifier to redeem the code.
+ */
+export declare function createPkce(): Pkce;
+export interface OAuthClientConfig {
+    /** Artos API base URL / OAuth issuer origin, e.g. `https://api.artos.sh`. */
+    artosBaseUrl: string;
+}
+export interface OAuthClientOptions {
+    fetch?: FetchLike;
+}
+/**
+ * Drives the Artos buyer-OAuth flow (RFC 6749/7636/8414) for a **Build-track**
+ * agent that runs sign-in itself (instead of relying on the hosted Connect
+ * bridge / Claude). It discovers the Authorization Server metadata, builds the
+ * PKCE authorize URL, and exchanges/refreshes tokens against the token endpoint.
+ * AS metadata is fetched once and cached for the client's lifetime.
+ */
+export declare class OAuthClient {
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    private cached?;
+    constructor(cfg: OAuthClientConfig, options?: OAuthClientOptions);
+    /** Fetches RFC 8414 AS metadata (`/.well-known/oauth-authorization-server`). */
+    discover(): Promise<AuthorizationServerMetadata>;
+    /** Cached AS metadata (discovered on first use). */
+    metadata(): Promise<AuthorizationServerMetadata>;
+    /**
+     * Builds the PKCE authorize URL the buyer opens to sign in + consent. Returns
+     * the URL and the `state` (verify it on the redirect to prevent CSRF). Pair
+     * with a {@link createPkce} `challenge`; keep the matching `verifier`.
+     */
+    authorizeUrl(params: {
+        clientId: string;
+        redirectUri: string;
+        codeChallenge: string;
+        scope?: string;
+        state?: string;
+    }): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /** Redeems an authorization code (+ PKCE verifier) for tokens. */
+    exchangeCode(params: {
+        code: string;
+        codeVerifier: string;
+        clientId: string;
+        redirectUri: string;
+    }): Promise<OAuthTokens>;
+    /** Exchanges a refresh token for a fresh access token (rotates the refresh). */
+    refresh(params: {
+        refreshToken: string;
+        clientId?: string;
+    }): Promise<OAuthTokens>;
+    private tokenRequest;
+}
+export {};

package/dist/oauth/client.js

@@ -0,0 +1,123 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { normalizeBaseUrl } from '../config.js';
+/**
+ * The buyer-auth scopes a Build-track agent should request: `purchase:complete`
+ * to place orders, and `offline_access` so the API mints a rotating refresh
+ * token (without it the buyer must re-consent every time the access token
+ * expires).
+ */
+export const DEFAULT_BUYER_SCOPE = 'purchase:complete offline_access';
+/** Raised for OAuth discovery / token errors (carries the RFC 6749 `error`). */
+export class OAuthClientError extends Error {
+    error;
+    constructor(error, description) {
+        super(description ?? error);
+        this.error = error;
+        this.name = 'OAuthClientError';
+    }
+}
+function base64url(buf) {
+    return buf.toString('base64url');
+}
+/**
+ * Generates a PKCE pair: a high-entropy `verifier` and its S256 `challenge`. Send
+ * the challenge on the authorize request; keep the verifier to redeem the code.
+ */
+export function createPkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge, method: 'S256' };
+}
+/**
+ * Drives the Artos buyer-OAuth flow (RFC 6749/7636/8414) for a **Build-track**
+ * agent that runs sign-in itself (instead of relying on the hosted Connect
+ * bridge / Claude). It discovers the Authorization Server metadata, builds the
+ * PKCE authorize URL, and exchanges/refreshes tokens against the token endpoint.
+ * AS metadata is fetched once and cached for the client's lifetime.
+ */
+export class OAuthClient {
+    fetchImpl;
+    baseUrl;
+    cached;
+    constructor(cfg, options = {}) {
+        this.baseUrl = normalizeBaseUrl(cfg.artosBaseUrl);
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /** Fetches RFC 8414 AS metadata (`/.well-known/oauth-authorization-server`). */
+    async discover() {
+        const res = await this.fetchImpl(`${this.baseUrl}/.well-known/oauth-authorization-server`, { headers: { Accept: 'application/json' } });
+        if (!res.ok) {
+            throw new OAuthClientError('discovery_failed', `Authorization Server metadata fetch failed (${res.status}).`);
+        }
+        const meta = (await res.json());
+        if (!meta.authorization_endpoint || !meta.token_endpoint) {
+            throw new OAuthClientError('discovery_failed', 'Authorization Server metadata is missing authorize/token endpoints.');
+        }
+        return meta;
+    }
+    /** Cached AS metadata (discovered on first use). */
+    async metadata() {
+        return (this.cached ??= await this.discover());
+    }
+    /**
+     * Builds the PKCE authorize URL the buyer opens to sign in + consent. Returns
+     * the URL and the `state` (verify it on the redirect to prevent CSRF). Pair
+     * with a {@link createPkce} `challenge`; keep the matching `verifier`.
+     */
+    async authorizeUrl(params) {
+        const meta = await this.metadata();
+        const state = params.state ?? randomUUID();
+        const url = new URL(meta.authorization_endpoint);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', params.clientId);
+        url.searchParams.set('redirect_uri', params.redirectUri);
+        url.searchParams.set('code_challenge', params.codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('scope', params.scope ?? DEFAULT_BUYER_SCOPE);
+        url.searchParams.set('state', state);
+        return { url: url.toString(), state };
+    }
+    /** Redeems an authorization code (+ PKCE verifier) for tokens. */
+    async exchangeCode(params) {
+        return this.tokenRequest({
+            grant_type: 'authorization_code',
+            code: params.code,
+            code_verifier: params.codeVerifier,
+            client_id: params.clientId,
+            redirect_uri: params.redirectUri,
+        });
+    }
+    /** Exchanges a refresh token for a fresh access token (rotates the refresh). */
+    async refresh(params) {
+        const body = {
+            grant_type: 'refresh_token',
+            refresh_token: params.refreshToken,
+        };
+        if (params.clientId)
+            body.client_id = params.clientId;
+        return this.tokenRequest(body);
+    }
+    async tokenRequest(body) {
+        const meta = await this.metadata();
+        const res = await this.fetchImpl(meta.token_endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body: new URLSearchParams(body).toString(),
+        });
+        const json = (await res.json());
+        if (!res.ok || !json.access_token) {
+            throw new OAuthClientError(json.error ?? 'token_error', json.error_description ?? `Token request failed (${res.status}).`);
+        }
+        return {
+            accessToken: json.access_token,
+            tokenType: json.token_type ?? 'Bearer',
+            expiresIn: json.expires_in ?? 0,
+            refreshToken: json.refresh_token,
+            scope: json.scope,
+        };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/oauth/client.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@artos-commerce/ucp-client",
-  "version": "0.1.1",
-  "description": "Path B Direct UCP client for Artos: typed UCP transport, AP2 mandate signing, and checkout orchestration so you can build your own commerce-grade UCP client without hand-rolling the envelope, signing, and credential rules.",
+  "version": "0.2.0",
+  "description": "Build-track Direct UCP client for Artos: typed UCP transport, AP2 mandate signing, checkout orchestration, buyer-account tools, and buyer OAuth so you can build your own commerce-grade UCP client without hand-rolling the envelope, signing, and credential rules.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -17,6 +17,8 @@
     "./ucp": "./dist/ucp/client.js",
     "./ap2": "./dist/ap2/index.js",
     "./checkout": "./dist/checkout/index.js",
+    "./account": "./dist/account/handlers.js",
+    "./oauth": "./dist/oauth/client.js",
     "./sui": "./dist/sui/signer.js",
     "./crypto": "./dist/crypto/deps.js"
   },