@stripe/link-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stripe, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# `@stripe/link-sdk`
+
+Node.js SDK for agents that use Link. It provides typed resources for Link APIs
+and accepts an access token from your application.
+
+The SDK does not perform login, persist credentials, or own refresh tokens.
+Authentication state and user-facing authorization flows belong to the CLI or
+application embedding the SDK.
+
+## Install
+
+```bash
+npm install @stripe/link-sdk
+```
+
+The package is ESM-only and requires Node.js 20 or newer.
+
+## Quick start
+
+Pass an access token when creating the client:
+
+```ts
+import Link from '@stripe/link-sdk';
+
+const link = new Link({ accessToken: process.env.LINK_ACCESS_TOKEN! });
+
+const paymentMethods = await link.paymentMethods.list();
+```
+
+Use a fixed token for a short-lived job or when the caller replaces the entire
+client as credentials change.
+
+## Credentials
+
+Exactly one credential option is required.
+
+### Dynamic access tokens
+
+When your application manages expiring credentials, provide `getAccessToken`.
+The SDK calls it for each request. After a 401 response, the SDK calls it once
+with `forceRefresh: true` and retries the request with the returned token.
+
+```ts
+const link = new Link({
+  getAccessToken: async ({ forceRefresh } = {}) =>
+    credentialManager.getLinkAccessToken({ forceRefresh }),
+});
+```
+
+The credential manager should coalesce concurrent refreshes if several
+requests can receive a 401 at the same time. A client configured with a fixed
+`accessToken` does not retry a 401 because it cannot obtain a different token.
+
+## User-approved purchase flow
+
+Amounts are expressed in the currency's minor unit, such as cents for USD.
+`context` must be at least 100 characters and should tell the user what the
+agent is buying and why.
+
+```ts
+const methods = await link.paymentMethods.list();
+const paymentMethod = methods.find((method) => method.is_default) ?? methods[0];
+
+if (!paymentMethod) {
+  throw new Error('The user needs to add a Link payment method.');
+}
+
+const spendRequest = await link.spendRequests.create({
+  payment_details: paymentMethod.id,
+  credential_type: 'card',
+  amount: 2599,
+  currency: 'usd',
+  merchant_name: 'Acme',
+  merchant_url: 'https://acme.example',
+  context:
+    'The user asked the agent to buy the selected item from Acme for $25.99, including the displayed shipping cost.',
+});
+
+const approval = await link.spendRequests.requestApproval(spendRequest.id);
+await sendToUser(`Approve this purchase: ${approval.approval_url}`);
+await saveRunState({ spendRequestId: spendRequest.id });
+```
+
+Retrieve the request in a later agent run:
+
+```ts
+const result = await link.spendRequests.retrieve(state.spendRequestId);
+
+if (!result) {
+  throw new Error('Spend request not found.');
+}
+
+switch (result.status) {
+  case 'approved':
+    // Use the returned credential without placing it in logs or chat.
+    break;
+  case 'created':
+    return { status: 'approval_not_requested' };
+  case 'pending_approval':
+    return { status: 'waiting_for_user_approval' };
+  case 'requires_action': {
+    const action = result.status_details?.requires_action?.next_action;
+    return action?.resolution === 'auto_resume'
+      ? { status: 'retry_later' }
+      : action;
+  }
+  case 'denied':
+  case 'expired':
+  case 'succeeded':
+  case 'failed':
+  case 'canceled':
+    return { status: result.status };
+}
+```
+
+Only a `requires_action` result whose `resolution` is `auto_resume` should be
+polled automatically. For any other resolution, surface the action to the user
+and follow its instructions. Keep returned card or shared-payment-token
+credentials out of model context, logs, and user-visible messages.
+
+## Configuration
+
+```ts
+const link = new Link({
+  accessToken,
+  fetch,
+  defaultHeaders: { 'X-Agent-Version': 'acme-agent/1.0' },
+  verbose: true,
+  logger: { debug: (message) => diagnostics.debug(message) },
+  apiBaseUrl: 'https://api.link.com',
+  spendRequestBaseUrl: 'https://api.link.com',
+});
+```
+
+Verbose logging includes request methods, URLs, and response status codes. It
+does not include authorization headers or request and response bodies.
+
+## Errors
+
+The SDK throws typed errors:
+
+- `LinkConfigurationError` for invalid or missing client configuration
+- `LinkTransportError` when a request cannot reach Link
+- `LinkApiError` for non-success API responses
+- `LinkResponseError` when a successful response has an invalid shape
+
+`LinkApiError` includes `status`, `code`, and structured `details` fields for
+programmatic handling.
+
+```ts
+import { LinkApiError } from '@stripe/link-sdk';
+
+try {
+  await link.spendRequests.retrieve('spend_request_id');
+} catch (error) {
+  if (error instanceof LinkApiError) {
+    diagnostics.error({
+      status: error.status,
+      code: error.code,
+      details: error.details,
+    });
+  }
+  throw error;
+}
+```
+
+## Client resources
+
+- `spendRequests` — create, approve, retrieve, update, cancel, and list
+- `paymentMethods` — list Link payment methods
+- `shippingAddresses` — list shipping addresses
+- `userInfo` — retrieve Link user information
+- `transactions` — list transactions
+- `sources` — list connected sources
+- `balances` — list balances
+- `webBotAuth` — sign URLs for Web Bot Auth
+- `reports` — report agent outcomes

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface LineItem {
+    name: string;
+    url?: string;
+    image_url?: string;
+    description?: string;
+    sku?: string;
+    totals?: Total[];
+    quantity?: number;
+    unit_amount?: number;
+    product_url?: string;
+}
+interface Total {
+    type: string;
+    display_text: string;
+    amount: number;
+}
+interface BillingAddress {
+    name: string;
+    line1: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postal_code?: string;
+    country: string;
+}
+interface Card {
+    id: string;
+    brand: string;
+    exp_month: number;
+    exp_year: number;
+    number: string;
+    cvc?: string;
+    billing_address?: BillingAddress;
+    valid_until?: string;
+}
+/** Known statuses, while remaining forward-compatible with new API values. */
+type SpendRequestStatus = 'created' | 'pending_approval' | 'expired' | 'approved' | 'denied' | 'succeeded' | 'failed' | 'canceled' | 'requires_action' | (string & Record<never, never>);
+type NextActionType = 'ssn_verification' | 'identity_verification' | 'contact_support' | 'select_payment_method' | 'add_payment_method' | 'update_payment_method' | 're_authorize' | 'three_d_secure' | 'three_d_secure_retry';
+type NextActionResolution = 'auto_resume' | 'create_new_spend_request' | 'create_new_spend_request_after_completion';
+interface NextAction {
+    type: NextActionType;
+    resolution: NextActionResolution;
+    display_message: string;
+    action_url: string | null;
+    expires_at?: number | null;
+}
+interface SpendRequestStatusDetails {
+    requires_action?: {
+        failure_code?: string;
+        next_action: NextAction;
+    };
+}
+type CredentialType = 'shared_payment_token' | 'card';
+interface ApprovalDetail {
+    approved_at: number;
+    approval_method: 'click' | 'programmatic' | 'voice';
+    app_name: string;
+    external_user_id: string;
+    ip_address?: string;
+    user_agent?: string;
+    device_type?: 'mobile' | 'web';
+    agent_log_id?: string;
+    external_user_name?: string;
+    external_session_id?: string;
+    authentication_method?: 'biometric_face' | 'biometric_fingerprint' | 'passkey';
+}
+interface SharedPaymentToken {
+    id: string;
+    billing_address?: BillingAddress;
+    valid_until?: string;
+}
+interface RefundDetails {
+    amount: number;
+    currency: string;
+    state: string;
+    created: number;
+}
+interface PaymentStatusDetails {
+    outcome: 'success' | 'failure';
+    code?: string | null;
+    decline_code?: string | null;
+    amount: number;
+    currency: string;
+    created?: number | null;
+    refund_details?: RefundDetails | null;
+}
+interface SpendRequest {
+    id: string;
+    merchant_name?: string;
+    merchant_url?: string;
+    context?: string;
+    amount?: number;
+    currency?: string;
+    line_items?: LineItem[];
+    totals?: Total[];
+    payment_method?: string;
+    payment_details?: string;
+    credential_type?: CredentialType;
+    network_id?: string;
+    card_brand?: string;
+    card_last4?: string;
+    status: SpendRequestStatus;
+    approval_url?: string;
+    card?: Card;
+    shared_payment_token?: SharedPaymentToken | null;
+    link_pay_token?: string;
+    payment_status_details?: PaymentStatusDetails | null;
+    status_details?: SpendRequestStatusDetails | null;
+    link_transaction_id?: string;
+    activity_url?: string;
+    metadata?: Record<string, string>;
+    expires_at?: number;
+    created_at: string;
+    updated_at: string;
+}
+interface RequestApprovalResponse {
+    id: string;
+    approval_url: string;
+}
+interface CardDetails {
+    brand: string;
+    last4: string;
+    exp_month: number;
+    exp_year: number;
+}
+interface BankAccountDetails {
+    last4: string;
+    bank_name?: string;
+}
+interface UserInfo {
+    email?: string | null;
+    name?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    phone?: string | null;
+}
+interface ProductCapability {
+    eligible: boolean;
+    ineligibility_reasons: string[];
+}
+interface PaymentMethod {
+    id: string;
+    type: string;
+    is_default: boolean;
+    nickname?: string;
+    card_details?: CardDetails;
+    bank_account_details?: BankAccountDetails;
+    capabilities?: Record<string, ProductCapability>;
+}
+interface ShippingAddress {
+    name: string | null;
+    line_1: string | null;
+    line_2: string | null;
+    locality: string | null;
+    dependent_locality: string | null;
+    administrative_area: string | null;
+    postal_code: string | null;
+    sorting_code: string | null;
+    country_code: string | null;
+}
+interface ShippingAddressRecord {
+    id: string;
+    is_default: boolean;
+    nickname: string | null;
+    address: ShippingAddress | null;
+}
+type TransactionOrigin = 'link' | 'external_connection';
+interface Transaction {
+    id: string;
+    source_id: string | null;
+    amount: number;
+    currency: string;
+    created_date: string;
+    description: string;
+    origin: TransactionOrigin;
+    category: string | null;
+    status: string;
+}
+interface TransactionsPage {
+    data: Transaction[];
+    has_more?: boolean;
+    [key: string]: unknown;
+}
+interface Source {
+    id?: string | null;
+    name?: string | null;
+    type?: string | null;
+    capabilities?: Record<string, unknown> | null;
+    external_connection?: Record<string, unknown> | null;
+    granted_actions?: string[] | null;
+    bank_account?: Record<string, unknown> | null;
+    card?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+interface SourcesPage {
+    data: Source[];
+    has_more?: boolean;
+    [key: string]: unknown;
+}
+interface CashBalance {
+    available: Record<string, number>;
+}
+interface CreditBalance {
+    used: Record<string, number>;
+}
+interface Balance {
+    source_id: string;
+    type: 'cash' | 'credit';
+    cash?: CashBalance | null;
+    credit?: CreditBalance | null;
+    current: number;
+    currency: string;
+    as_of: string;
+    [key: string]: unknown;
+}
+interface BalancesPage {
+    data: Balance[];
+    has_more?: boolean;
+    [key: string]: unknown;
+}
+interface WebBotAuthBlock {
+    signature: string;
+    signature_input: string;
+    signature_agent: string;
+    authority: string;
+    expires_at: string;
+}
+
+interface GetAccessTokenOptions {
+    forceRefresh?: boolean;
+}
+type AccessTokenProvider = (options?: GetAccessTokenOptions) => Promise<string> | string;
+interface CreateSpendRequestParams {
+    payment_details?: string;
+    credential_type?: CredentialType;
+    network_id?: string;
+    execution_method?: 'link_pay_token';
+    merchant_account_id?: string;
+    amount?: number;
+    currency?: string;
+    merchant_name?: string;
+    merchant_url?: string;
+    context: string;
+    line_items?: LineItem[];
+    totals?: Total[];
+    request_approval?: boolean;
+    test?: boolean;
+    approval_details?: ApprovalDetail;
+    metadata?: Record<string, string>;
+}
+interface UpdateSpendRequestParams {
+    payment_details?: string;
+    amount?: number;
+    merchant_url?: string;
+    profile_id?: string;
+    merchant_id?: string;
+    currency?: string;
+    line_items?: LineItem[];
+    totals?: Total[];
+}
+interface ISpendRequestResource {
+    list(opts?: {
+        includeHistory?: boolean;
+    }): Promise<SpendRequest[]>;
+    create(params: CreateSpendRequestParams): Promise<SpendRequest>;
+    update(id: string, params: UpdateSpendRequestParams): Promise<SpendRequest>;
+    requestApproval(id: string): Promise<RequestApprovalResponse>;
+    cancel(id: string): Promise<SpendRequest>;
+    retrieve(id: string, opts?: {
+        include?: string[];
+    }): Promise<SpendRequest | null>;
+}
+interface IPaymentMethodsResource {
+    list(): Promise<PaymentMethod[]>;
+}
+interface IShippingAddressResource {
+    list(): Promise<ShippingAddressRecord[]>;
+}
+interface IUserInfoResource {
+    retrieve(): Promise<UserInfo>;
+}
+interface IWebBotAuthResource {
+    signUrl(url: string): Promise<WebBotAuthBlock>;
+}
+interface ListTransactionsParams {
+    limit?: number;
+    starting_after?: string;
+    ending_before?: string;
+    start_date?: string;
+    end_date?: string;
+    category?: string;
+    origin?: TransactionOrigin;
+    sources?: string[];
+}
+interface ITransactionsResource {
+    list(params?: ListTransactionsParams): Promise<TransactionsPage>;
+}
+interface ListSourcesParams {
+    limit?: number;
+    starting_after?: string;
+    ending_before?: string;
+}
+interface ISourcesResource {
+    list(params?: ListSourcesParams): Promise<SourcesPage>;
+}
+interface ListBalancesParams {
+    sources?: string[];
+    limit?: number;
+    starting_after?: string;
+    ending_before?: string;
+}
+interface IBalancesResource {
+    list(params?: ListBalancesParams): Promise<BalancesPage>;
+}
+declare const REPORT_OUTCOMES: readonly ["success", "blocked", "abandoned"];
+type ReportOutcome = (typeof REPORT_OUTCOMES)[number];
+declare const REPORT_TAGS: readonly ["stripe_checkout", "captcha", "anti_bot_script", "cdn_block", "waf_block", "dns_block", "rate_limited", "login_required", "3ds_challenge", "page_inaccessible", "timeout", "site_error", "payment_declined", "other"];
+type ReportTag = (typeof REPORT_TAGS)[number];
+interface CreateReportParams {
+    domain: string;
+    outcome: ReportOutcome;
+    spend_request_id: string;
+    tags?: ReportTag[];
+    step?: string;
+    freeform_context?: string;
+}
+interface ReportRecord {
+    object: string;
+    created_at: string;
+    domain: string;
+    outcome: string;
+    spend_request_id: string;
+    status: string;
+}
+interface IReportResource {
+    create(params: CreateReportParams): Promise<ReportRecord>;
+}
+
+interface LinkSdkLogger {
+    debug(message: string): void;
+}
+interface LinkClientOptions {
+    verbose?: boolean;
+    defaultHeaders?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    apiBaseUrl?: string;
+    spendRequestBaseUrl?: string;
+    logger?: LinkSdkLogger;
+}
+type LinkOptions = LinkClientOptions & ({
+    accessToken: string;
+    getAccessToken?: never;
+} | {
+    accessToken?: never;
+    getAccessToken: AccessTokenProvider;
+});
+
+declare class Link {
+    readonly spendRequests: ISpendRequestResource;
+    readonly paymentMethods: IPaymentMethodsResource;
+    readonly shippingAddresses: IShippingAddressResource;
+    readonly userInfo: IUserInfoResource;
+    readonly transactions: ITransactionsResource;
+    readonly sources: ISourcesResource;
+    readonly balances: IBalancesResource;
+    readonly webBotAuth: IWebBotAuthResource;
+    readonly reports: IReportResource;
+    constructor(options: LinkOptions);
+}
+
+declare class LinkSdkError extends Error {
+    readonly code: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+declare class LinkResponseError extends LinkSdkError {
+    readonly status: number;
+    constructor(operation: string, status: number, options?: {
+        cause?: unknown;
+    });
+}
+declare class LinkConfigurationError extends LinkSdkError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class LinkTransportError extends LinkSdkError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class LinkApiError extends LinkSdkError {
+    readonly status: number;
+    readonly rawBody: string | undefined;
+    readonly details?: unknown;
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        rawBody?: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+
+declare function getDuplicateSpendRequest(error: unknown): SpendRequest | null;
+
+export { type AccessTokenProvider, type ApprovalDetail, type Balance, type BalancesPage, type BankAccountDetails, type BillingAddress, type Card, type CardDetails, type CashBalance, type CreateReportParams, type CreateSpendRequestParams, type CredentialType, type CreditBalance, type GetAccessTokenOptions, type IBalancesResource, type IPaymentMethodsResource, type IReportResource, type IShippingAddressResource, type ISourcesResource, type ISpendRequestResource, type ITransactionsResource, type IUserInfoResource, type IWebBotAuthResource, type JsonPrimitive, type JsonValue, type LineItem, Link, LinkApiError, LinkConfigurationError, type LinkOptions, LinkResponseError, LinkSdkError, type LinkSdkLogger, LinkTransportError, type ListBalancesParams, type ListSourcesParams, type ListTransactionsParams, type NextAction, type NextActionResolution, type NextActionType, type PaymentMethod, type PaymentStatusDetails, type ProductCapability, REPORT_OUTCOMES, REPORT_TAGS, type RefundDetails, type ReportOutcome, type ReportRecord, type ReportTag, type RequestApprovalResponse, type SharedPaymentToken, type ShippingAddress, type ShippingAddressRecord, type Source, type SourcesPage, type SpendRequest, type SpendRequestStatus, type SpendRequestStatusDetails, type Total, type Transaction, type TransactionOrigin, type TransactionsPage, type UpdateSpendRequestParams, type UserInfo, type WebBotAuthBlock, Link as default, getDuplicateSpendRequest };