@qelos/sdk 4.1.1 → 4.2.1

package/src/index.ts

@@ -16,6 +16,7 @@ const noExtraHeadersUrls = new Set([
   '/api/signin',
   '/api/signup',
   '/api/auth/callback',
+  '/api/auth/mcp/token',
 ])
 
 export type {
@@ -23,6 +24,13 @@ export type {
   SocialAuthCallbackPayload,
   SocialProvider,
   SocialLoginOptions,
+  McpAuthorizeOptions,
+  McpCallbackInput,
+  McpCallbackParams,
+  McpTokenExchangeOptions,
+  McpTokenExchangeResult,
+  DecodedMcpOAuthStatePayload,
+  McpPagePathOptions,
 } from './authentication';
 
 export type { BlueprintEntitiesRegistry } from './blueprints';
@@ -31,8 +39,20 @@ export {
   parseSocialCallbackRefreshToken,
   getSocialAuthSetCookieParts,
   applySocialAuthCookiesToServerResponse,
+  parseMcpCallbackParams,
 } from './authentication';
 
+export {
+  buildMcpAuthorizePath,
+  buildMcpAuthorizePathFromQuery,
+  buildMcpLoginRedirectUrl,
+  buildMcpConsentPageUrl,
+  resolveMcpLoginRedirect,
+  appendMcpAccessDeniedRedirect,
+  decodeMcpOAuthStatePayload,
+  buildMcpTokenExchangeBody,
+} from './mcp-auth';
+
 export default class QelosSDK extends BaseSDK {
   #customHeaders = {}
 

package/src/mcp-auth.ts

@@ -0,0 +1,293 @@
+import type { IUser } from './authentication';
+
+export interface McpAuthorizeOptions {
+  redirectUri: string;
+  state?: string;
+  codeChallenge?: string;
+  codeChallengeMethod?: string;
+  clientId?: string;
+}
+
+export interface McpTokenExchangeOptions {
+  code: string;
+  redirectUri: string;
+  codeVerifier: string;
+}
+
+export interface McpTokenExchangeResult {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+  user: IUser;
+}
+
+/** Callback URL or query bag from an MCP OAuth redirect. */
+export type McpCallbackInput =
+  | string
+  | URL
+  | URLSearchParams
+  | Record<string, string | string[] | undefined>;
+
+export interface McpCallbackParams {
+  code?: string;
+  state?: string;
+  error?: string;
+  errorDescription?: string;
+}
+
+/** Decoded MCP OAuth state JWT payload (display only — not verified). */
+export interface DecodedMcpOAuthStatePayload {
+  redirectUri?: string;
+  state?: string;
+  codeChallenge?: string;
+  codeChallengeMethod?: string;
+  tenant?: string;
+  clientId?: string;
+}
+
+export interface McpPagePathOptions {
+  loginPath?: string;
+  consentPath?: string;
+}
+
+function readQueryValue(
+  input: Record<string, string | string[] | undefined>,
+  key: string,
+): string | undefined {
+  const raw = input[key];
+  if (Array.isArray(raw)) {
+    return raw[0] && typeof raw[0] === 'string' ? raw[0] : undefined;
+  }
+  return typeof raw === 'string' ? raw : undefined;
+}
+
+function searchParamsFromString(input: string): URLSearchParams | undefined {
+  try {
+    const url = new URL(input);
+    if (url.search) {
+      return url.searchParams;
+    }
+    if (url.hash.length > 1) {
+      return new URLSearchParams(url.hash.slice(1));
+    }
+    return url.searchParams;
+  } catch {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const queryPart = trimmed.startsWith('?')
+      ? trimmed.slice(1)
+      : trimmed.startsWith('#')
+        ? trimmed.slice(1)
+        : trimmed.includes('=')
+          ? trimmed
+          : undefined;
+    return queryPart ? new URLSearchParams(queryPart) : undefined;
+  }
+}
+
+function searchParamsFromInput(input: McpCallbackInput): URLSearchParams | undefined {
+  if (input instanceof URLSearchParams) {
+    return input;
+  }
+  if (input instanceof URL) {
+    if (input.search.length > 1) {
+      return input.searchParams;
+    }
+    if (input.hash.length > 1) {
+      return new URLSearchParams(input.hash.slice(1));
+    }
+    return input.searchParams;
+  }
+  if (typeof input === 'string') {
+    return searchParamsFromString(input);
+  }
+
+  const params = new URLSearchParams();
+  const code = readQueryValue(input, 'code');
+  const state = readQueryValue(input, 'state');
+  const error = readQueryValue(input, 'error');
+  const errorDescription = readQueryValue(input, 'error_description');
+  if (code) params.set('code', code);
+  if (state) params.set('state', state);
+  if (error) params.set('error', error);
+  if (errorDescription) params.set('error_description', errorDescription);
+  return params.toString() ? params : undefined;
+}
+
+/**
+ * Parse authorization callback parameters from an MCP OAuth redirect.
+ * Accepts a full URL, {@link URL}, `URLSearchParams`, a query/fragment string,
+ * or a query object such as `req.query` from Next.js or Express.
+ */
+export function parseMcpCallbackParams(input: McpCallbackInput): McpCallbackParams {
+  const params = searchParamsFromInput(input);
+  if (!params) {
+    return {};
+  }
+
+  const result: McpCallbackParams = {};
+  const code = params.get('code');
+  const state = params.get('state');
+  const error = params.get('error');
+  const errorDescription = params.get('error_description');
+  if (code) result.code = code;
+  if (state) result.state = state;
+  if (error) result.error = error;
+  if (errorDescription) result.errorDescription = errorDescription;
+  return result;
+}
+
+/** Relative authorize path with query string for {@link QlAuthentication.getMcpAuthorizeUrl}. */
+export function buildMcpAuthorizePath(options: McpAuthorizeOptions): string {
+  const search = new URLSearchParams({ redirect_uri: options.redirectUri });
+  if (options.state) search.set('state', options.state);
+  if (options.codeChallenge) search.set('code_challenge', options.codeChallenge);
+  if (options.codeChallengeMethod) search.set('code_challenge_method', options.codeChallengeMethod);
+  if (options.clientId) search.set('client_id', options.clientId);
+  return `/api/auth/mcp/authorize?${search.toString()}`;
+}
+
+/**
+ * Build `/api/auth/mcp/authorize?…` from OAuth authorize query params
+ * (e.g. when `/mcp/authorize` receives a direct client redirect).
+ */
+export function buildMcpAuthorizePathFromQuery(
+  query: Record<string, string | string[] | undefined>,
+): string | null {
+  const redirectUri = readQueryValue(query, 'redirect_uri');
+  if (!redirectUri) {
+    return null;
+  }
+
+  const options: McpAuthorizeOptions = { redirectUri };
+  const state = readQueryValue(query, 'state');
+  const codeChallenge = readQueryValue(query, 'code_challenge');
+  const codeChallengeMethod = readQueryValue(query, 'code_challenge_method');
+  const clientId = readQueryValue(query, 'client_id');
+  if (state) options.state = state;
+  if (codeChallenge) options.codeChallenge = codeChallenge;
+  if (codeChallengeMethod) options.codeChallengeMethod = codeChallengeMethod;
+  if (clientId) options.clientId = clientId;
+  return buildMcpAuthorizePath(options);
+}
+
+/** Login redirect used by Qelos after an unauthenticated MCP authorize request. */
+export function buildMcpLoginRedirectUrl(
+  authorizePath: string,
+  options?: Pick<McpPagePathOptions, 'loginPath'>,
+): string {
+  const loginPath = options?.loginPath ?? '/login';
+  return `${loginPath}?redirect=${encodeURIComponent(authorizePath)}`;
+}
+
+/** Consent page URL issued after the user signs in during MCP OAuth. */
+export function buildMcpConsentPageUrl(
+  mcpState: string,
+  options?: Pick<McpPagePathOptions, 'consentPath'>,
+): string {
+  const consentPath = options?.consentPath ?? '/mcp/authorize';
+  return `${consentPath}?mcp_state=${encodeURIComponent(mcpState)}`;
+}
+
+/**
+ * Resolve the post-login redirect target from login-page query params.
+ * Matches the resume logic used by the Qelos admin login flow.
+ */
+export function resolveMcpLoginRedirect(
+  query: Record<string, string | string[] | undefined>,
+  options?: McpPagePathOptions,
+): string | null {
+  const redirect = readQueryValue(query, 'redirect');
+  if (redirect) {
+    return redirect;
+  }
+
+  const mcpState = readQueryValue(query, 'mcp_state');
+  if (mcpState) {
+    return buildMcpConsentPageUrl(mcpState, options);
+  }
+
+  return buildMcpAuthorizePathFromQuery(query);
+}
+
+/** Redirect URI with `error=access_denied` for MCP consent denial. */
+export function appendMcpAccessDeniedRedirect(
+  redirectUri: string,
+  oauthState?: string | null,
+): string {
+  try {
+    const url = new URL(redirectUri);
+    url.searchParams.set('error', 'access_denied');
+    if (oauthState) {
+      url.searchParams.set('state', oauthState);
+    }
+    return url.toString();
+  } catch {
+    const separator = redirectUri.includes('?') ? '&' : '?';
+    let result = `${redirectUri}${separator}error=access_denied`;
+    if (oauthState) {
+      result += `&state=${encodeURIComponent(oauthState)}`;
+    }
+    return result;
+  }
+}
+
+/**
+ * Decode the signed `mcp_state` JWT payload for display on a consent page.
+ * Does not verify the signature — use only for UI labels, not authorization.
+ */
+export function decodeMcpOAuthStatePayload(mcpState: string): DecodedMcpOAuthStatePayload | null {
+  if (!mcpState) {
+    return null;
+  }
+
+  try {
+    const parts = mcpState.split('.');
+    if (parts.length !== 3 || !parts[1]) {
+      return null;
+    }
+
+    const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const json =
+      typeof globalThis.atob === 'function'
+        ? globalThis.atob(base64)
+        : Buffer.from(base64, 'base64').toString('utf8');
+    const decoded = JSON.parse(json) as {
+      ru?: string;
+      s?: string;
+      cc?: string;
+      ccm?: string;
+      t?: string;
+      cid?: string;
+    };
+
+    const payload: DecodedMcpOAuthStatePayload = {};
+    if (decoded.ru) payload.redirectUri = decoded.ru;
+    if (decoded.s) payload.state = decoded.s;
+    if (decoded.cc) payload.codeChallenge = decoded.cc;
+    if (decoded.ccm) payload.codeChallengeMethod = decoded.ccm;
+    if (decoded.t) payload.tenant = decoded.t;
+    if (decoded.cid) payload.clientId = decoded.cid;
+    return payload.redirectUri ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface McpOAuthTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+export function buildMcpTokenExchangeBody(options: McpTokenExchangeOptions): URLSearchParams {
+  return new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: options.code,
+    redirect_uri: options.redirectUri,
+    code_verifier: options.codeVerifier,
+  });
+}

package/src/payments.ts

@@ -1,6 +1,6 @@
 import { QelosSDKOptions } from './types';
 import BaseSDK from './base-sdk';
-import { IPlan, ISubscription, IInvoice, ICoupon, BillingCycle } from '@qelos/global-types';
+import { IPlan, ISubscription, IInvoice, ICoupon, BillingCycle, CheckoutCustomer } from '@qelos/global-types';
 
 export interface CheckoutRequest {
   /** Required when not providing `subscriptionId`. Must be a non-dynamic plan. */
@@ -10,6 +10,17 @@ export interface CheckoutRequest {
   couponCode?: string;
   successUrl?: string;
   cancelUrl?: string;
+  /**
+   * Real-world identity of the billable entity. Passed through to the payment
+   * provider (e.g. Sumit) so it can create a properly-named customer record
+   * instead of falling back to the raw billable entity ID.
+   */
+  customer?: CheckoutCustomer;
+  /**
+   * When true, cancels any existing active or trialing subscription for the
+   * authenticated billable entity before starting checkout (e.g. plan change).
+   */
+  reset?: boolean;
   /**
    * Pre-created subscription ID. Required for dynamic plans — the admin must set
    * `dynamicAmount` on the subscription before this checkout call will succeed.

package/test/mcp-auth.test.ts

@@ -0,0 +1,255 @@
+import * as assert from 'node:assert/strict';
+import { createHash, randomBytes } from 'node:crypto';
+import { test } from 'node:test';
+import {
+  appendMcpAccessDeniedRedirect,
+  buildMcpAuthorizePath,
+  buildMcpAuthorizePathFromQuery,
+  buildMcpConsentPageUrl,
+  buildMcpLoginRedirectUrl,
+  buildMcpTokenExchangeBody,
+  decodeMcpOAuthStatePayload,
+  parseMcpCallbackParams,
+  resolveMcpLoginRedirect,
+} from '../src/mcp-auth';
+
+function pkceChallenge(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+test('buildMcpAuthorizePath', async (t) => {
+  await t.test('builds authorize path with required redirect_uri', () => {
+    const path = buildMcpAuthorizePath({
+      redirectUri: 'cursor://anysphere.cursor-mcp/oauth/callback',
+    });
+    assert.match(path, /^\/api\/auth\/mcp\/authorize\?/);
+    const parsed = new URL(`https://gateway.example.com${path}`);
+    assert.equal(
+      parsed.searchParams.get('redirect_uri'),
+      'cursor://anysphere.cursor-mcp/oauth/callback',
+    );
+  });
+
+  await t.test('includes optional PKCE and client params', () => {
+    const path = buildMcpAuthorizePath({
+      redirectUri: 'https://claude.ai/api/mcp/auth_callback',
+      state: 'csrf-9',
+      codeChallenge: 'abc123',
+      codeChallengeMethod: 'S256',
+      clientId: 'claude',
+    });
+    const parsed = new URL(`https://gateway.example.com${path}`);
+    assert.equal(parsed.searchParams.get('state'), 'csrf-9');
+    assert.equal(parsed.searchParams.get('code_challenge'), 'abc123');
+    assert.equal(parsed.searchParams.get('code_challenge_method'), 'S256');
+    assert.equal(parsed.searchParams.get('client_id'), 'claude');
+  });
+});
+
+test('getMcpAuthorizeUrl', async (t) => {
+  const { default: QelosSDK } = await import('../src/index');
+
+  await t.test('returns absolute authorize URL', () => {
+    const sdk = new QelosSDK({ appUrl: 'https://gateway.example.com' });
+    const url = sdk.authentication.getMcpAuthorizeUrl({
+      redirectUri: 'https://claude.ai/api/mcp/auth_callback',
+      state: 's1',
+    });
+    const parsed = new URL(url);
+    assert.equal(parsed.origin, 'https://gateway.example.com');
+    assert.equal(parsed.pathname, '/api/auth/mcp/authorize');
+    assert.equal(parsed.searchParams.get('redirect_uri'), 'https://claude.ai/api/mcp/auth_callback');
+    assert.equal(parsed.searchParams.get('state'), 's1');
+  });
+});
+
+test('parseMcpCallbackParams', async (t) => {
+  await t.test('parses code and state from full URL', () => {
+    assert.deepEqual(
+      parseMcpCallbackParams('https://claude.ai/api/mcp/auth_callback?code=abc&state=xyz'),
+      { code: 'abc', state: 'xyz' },
+    );
+  });
+
+  await t.test('parses error params from callback URL', () => {
+    assert.deepEqual(
+      parseMcpCallbackParams('cursor://cb?error=access_denied&state=xyz'),
+      { error: 'access_denied', state: 'xyz' },
+    );
+  });
+
+  await t.test('parses URL / URLSearchParams / query objects', () => {
+    assert.deepEqual(
+      parseMcpCallbackParams(new URL('http://_/cb?code=u&state=v')),
+      { code: 'u', state: 'v' },
+    );
+    assert.deepEqual(
+      parseMcpCallbackParams(new URLSearchParams('code=w&state=x')),
+      { code: 'w', state: 'x' },
+    );
+    assert.deepEqual(parseMcpCallbackParams({ code: 'y', state: 'z' }), { code: 'y', state: 'z' });
+    assert.deepEqual(parseMcpCallbackParams({ error: ['denied'] }), { error: 'denied' });
+  });
+
+  await t.test('parses fragment delivery params', () => {
+    assert.deepEqual(
+      parseMcpCallbackParams('https://app.example/cb#code=frag-code&state=frag-state'),
+      { code: 'frag-code', state: 'frag-state' },
+    );
+  });
+
+  await t.test('returns empty object when params missing', () => {
+    assert.deepEqual(parseMcpCallbackParams('/no-query'), {});
+    assert.deepEqual(parseMcpCallbackParams({}), {});
+  });
+});
+
+test('exchangeMcpAuthorizationCode', async (t) => {
+  const { default: QelosSDK } = await import('../src/index');
+
+  await t.test('posts PKCE token exchange and returns tokens with user', async () => {
+    const codeVerifier = randomBytes(32).toString('base64url');
+    const redirectUri = 'https://claude.ai/api/mcp/auth_callback';
+    const calls: { url: string; init?: RequestInit }[] = [];
+
+    const sdk = new QelosSDK({
+      appUrl: 'https://gateway.example.com',
+      fetch: async (url, init) => {
+        calls.push({ url: String(url), init });
+        if (String(url).endsWith('/api/auth/mcp/token')) {
+          const body = init?.body ? String(init.body) : '';
+          const params = new URLSearchParams(body);
+          assert.equal(params.get('grant_type'), 'authorization_code');
+          assert.equal(params.get('code'), 'auth-code-1');
+          assert.equal(params.get('redirect_uri'), redirectUri);
+          assert.equal(params.get('code_verifier'), codeVerifier);
+          return new Response(
+            JSON.stringify({
+              access_token: 'at-1',
+              refresh_token: 'rt-1',
+              token_type: 'Bearer',
+              expires_in: 18000,
+            }),
+            { status: 200, headers: { 'content-type': 'application/json' } },
+          );
+        }
+        if (String(url).endsWith('/api/me')) {
+          return new Response(
+            JSON.stringify({ _id: 'u1', username: 'jane', email: 'jane@example.com' }),
+            { status: 200, headers: { 'content-type': 'application/json' } },
+          );
+        }
+        return new Response('not found', { status: 404 });
+      },
+    });
+
+    const result = await sdk.authentication.exchangeMcpAuthorizationCode({
+      code: 'auth-code-1',
+      redirectUri,
+      codeVerifier,
+    });
+
+    assert.equal(result.accessToken, 'at-1');
+    assert.equal(result.refreshToken, 'rt-1');
+    assert.equal(result.expiresIn, 18000);
+    assert.equal(result.user._id, 'u1');
+    assert.equal(calls.length, 2);
+    assert.match(calls[0]!.url, /\/api\/auth\/mcp\/token$/);
+    assert.match(calls[1]!.url, /\/api\/me$/);
+    assert.equal(
+      (calls[0]!.init?.headers as Record<string, string>)['content-type'],
+      'application/x-www-form-urlencoded',
+    );
+  });
+
+  await t.test('buildMcpTokenExchangeBody matches authorize PKCE pair', () => {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = pkceChallenge(verifier);
+    const path = buildMcpAuthorizePath({
+      redirectUri: 'cursor://anysphere.cursor-mcp/oauth/callback',
+      codeChallenge: challenge,
+      codeChallengeMethod: 'S256',
+    });
+    const authorizeParams = new URL(`https://gateway.example.com${path}`).searchParams;
+    assert.equal(authorizeParams.get('code_challenge'), challenge);
+    assert.equal(authorizeParams.get('code_challenge_method'), 'S256');
+
+    const body = buildMcpTokenExchangeBody({
+      code: 'c1',
+      redirectUri: 'cursor://anysphere.cursor-mcp/oauth/callback',
+      codeVerifier: verifier,
+    });
+    assert.equal(body.get('code_verifier'), verifier);
+  });
+});
+
+test('mcp authorize page helpers', async (t) => {
+  await t.test('buildMcpLoginRedirectUrl encodes authorize path', () => {
+    const authorizePath = '/api/auth/mcp/authorize?redirect_uri=https%3A%2F%2Fclaude.ai';
+    assert.equal(
+      buildMcpLoginRedirectUrl(authorizePath),
+      `/login?redirect=${encodeURIComponent(authorizePath)}`,
+    );
+  });
+
+  await t.test('buildMcpConsentPageUrl encodes mcp_state', () => {
+    assert.equal(
+      buildMcpConsentPageUrl('signed.jwt.state'),
+      `/mcp/authorize?mcp_state=${encodeURIComponent('signed.jwt.state')}`,
+    );
+  });
+
+  await t.test('buildMcpAuthorizePathFromQuery mirrors authorize params', () => {
+    const path = buildMcpAuthorizePathFromQuery({
+      redirect_uri: 'cursor://anysphere.cursor-mcp/oauth/callback',
+      state: 's1',
+      code_challenge: 'cc',
+      code_challenge_method: 'S256',
+      client_id: 'cursor',
+    });
+    assert.ok(path);
+    const parsed = new URL(`https://gateway.example.com${path}`);
+    assert.equal(parsed.searchParams.get('redirect_uri'), 'cursor://anysphere.cursor-mcp/oauth/callback');
+    assert.equal(parsed.searchParams.get('state'), 's1');
+    assert.equal(parsed.searchParams.get('code_challenge'), 'cc');
+    assert.equal(parsed.searchParams.get('code_challenge_method'), 'S256');
+    assert.equal(parsed.searchParams.get('client_id'), 'cursor');
+  });
+
+  await t.test('resolveMcpLoginRedirect prefers redirect, then mcp_state, then authorize query', () => {
+    assert.equal(
+      resolveMcpLoginRedirect({ redirect: '/api/auth/mcp/authorize?redirect_uri=x' }),
+      '/api/auth/mcp/authorize?redirect_uri=x',
+    );
+    assert.equal(
+      resolveMcpLoginRedirect({ mcp_state: 'jwt' }),
+      `/mcp/authorize?mcp_state=${encodeURIComponent('jwt')}`,
+    );
+    assert.equal(
+      resolveMcpLoginRedirect({ redirect_uri: 'https://claude.ai/cb' }),
+      '/api/auth/mcp/authorize?redirect_uri=https%3A%2F%2Fclaude.ai%2Fcb',
+    );
+    assert.equal(resolveMcpLoginRedirect({}), null);
+  });
+
+  await t.test('appendMcpAccessDeniedRedirect adds error and state', () => {
+    assert.equal(
+      appendMcpAccessDeniedRedirect('cursor://cb?foo=1', 'oauth-state'),
+      'cursor://cb?foo=1&error=access_denied&state=oauth-state',
+    );
+  });
+
+  await t.test('decodeMcpOAuthStatePayload decodes JWT payload without verification', () => {
+    const payload = { ru: 'cursor://cb', s: 'oauth-state', t: 'tenant-1', cid: 'cursor' };
+    const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const token = `header.${encoded}.signature`;
+
+    assert.deepEqual(decodeMcpOAuthStatePayload(token), {
+      redirectUri: 'cursor://cb',
+      state: 'oauth-state',
+      tenant: 'tenant-1',
+      clientId: 'cursor',
+    });
+    assert.equal(decodeMcpOAuthStatePayload('not-a-jwt'), null);
+  });
+});

package/test/payments.test.ts

@@ -0,0 +1,65 @@
+import * as assert from 'node:assert/strict';
+import { test } from 'node:test';
+import QlPayments from '../src/payments';
+import { QelosSDKOptions } from '../src/types';
+
+function jsonResponse(body: unknown) {
+  const res = new Response(JSON.stringify(body));
+  res.headers.set('Content-Type', 'application/json');
+  return res;
+}
+
+test('QlPayments', async (t) => {
+  await t.test('checkout serializes the customer object into the POST body', async () => {
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        init = requestInit;
+        return jsonResponse({ subscriptionId: 'sub-1', checkoutUrl: 'https://sumit.example/checkout' });
+      },
+    };
+    const payments = new QlPayments(options);
+    await payments.checkout({
+      planId: 'plan-1',
+      billingCycle: 'monthly',
+      successUrl: 'https://app.example/success',
+      cancelUrl: 'https://app.example/cancel',
+      customer: {
+        name: 'Jane Doe',
+        nameForInvoice: 'Acme Inc.',
+        email: 'jane@acme.example',
+        phone: '+1-555-0100',
+        address: '1 Main St',
+        city: 'Springfield',
+      },
+    });
+
+    assert.equal(init?.method, 'post');
+    const body = JSON.parse(init?.body as string);
+    assert.deepEqual(body.customer, {
+      name: 'Jane Doe',
+      nameForInvoice: 'Acme Inc.',
+      email: 'jane@acme.example',
+      phone: '+1-555-0100',
+      address: '1 Main St',
+      city: 'Springfield',
+    });
+  });
+
+  await t.test('checkout omits customer when not provided', async () => {
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        init = requestInit;
+        return jsonResponse({ subscriptionId: 'sub-1' });
+      },
+    };
+    const payments = new QlPayments(options);
+    await payments.checkout({ planId: 'plan-1', billingCycle: 'monthly' });
+
+    const body = JSON.parse(init?.body as string);
+    assert.equal('customer' in body, false);
+  });
+});