# Capability Spec: payment-provider-paypal **Package**: `@suaveplan/payment-provider-paypal` **Status**: SHIPPED > Every requirement below carries a `**Verified by:**` line. > > History: originally folded by `2026-05-17-add-payment-provider-paypal` > as the PayPal sibling adapter on the slim > `@suaveplan/payment-providers` core. ## Requirements ### Requirement: PayPalProvider implements PaymentProvider The package SHALL export a class `PayPalProvider` that implements the `PaymentProvider` structural interface from `@suaveplan/payment` with a literal-typed `name: "paypal"` property and the six lifecycle methods (`createIntent`, `confirmIntent`, `captureIntent`, `cancelIntent`, `refund`, `getIntent`). Every method MUST be `async` and MUST return a `PaymentIntent` or `Refund` shape from `@suaveplan/payment`. #### Scenario: name discriminant - **WHEN** a caller constructs `new PayPalProvider({ clientId: "id", clientSecret: "secret" })` - **THEN** `provider.name` equals the string `"paypal"` (literal type) #### Scenario: PaymentProvider conformance - **WHEN** a caller assigns a `PayPalProvider` instance to a variable of type `PaymentProvider` from `@suaveplan/payment` - **THEN** the assignment type-checks without casts, and all six methods are callable with their declared signatures **Verified by:** `src/paypal/paypal.test.ts::"has literal name 'paypal'"` AND `src/paypal/paypal.test.ts::"satisfies the PaymentProvider structural contract"` --- ### Requirement: OAuth2 client-credentials token cache The package SHALL acquire and cache an OAuth2 bearer token by posting `grant_type=client_credentials` to `/v1/oauth2/token` with an `Authorization: Basic ` header and a `Content-Type: application/x-www-form-urlencoded` header. The cached token MUST be reused for every subsequent call until `now() >= expiresAt`, where `expiresAt = tokenAcquiredAt + (expires_in * 1000) - 60_000` (60 s clock-skew buffer). A subsequent call after expiry MUST refresh the token transparently. #### Scenario: first call acquires a token, subsequent calls reuse it - **WHEN** the caller invokes any method twice in quick succession with an injected `FetchLike` recorder - **THEN** the recorder observes exactly one `/v1/oauth2/token` POST and two Orders-v2 calls (one per invocation) #### Scenario: token refresh after expiry - **WHEN** the caller invokes a method, advances the injected `NowFn` past `expiresAt`, and invokes a second method - **THEN** the recorder observes two `/v1/oauth2/token` POSTs and two Orders-v2 calls #### Scenario: OAuth header uses the injected base64 encoder - **WHEN** a caller injects a custom `base64Encode` that prepends `"X-"` - **THEN** the Basic header for the token call equals `"Basic X-"` **Verified by:** `src/paypal/paypal-token.test.ts::"reuses a cached OAuth token across method calls"` AND `src/paypal/paypal-token.test.ts::"refreshes the token after the cached expiry passes"` AND `src/paypal/paypal-token.test.ts::"derives the Basic header via the injected base64 encoder"` --- ### Requirement: Token-fetch failure raises OAUTH_TOKEN_FAILURE When the `/v1/oauth2/token` POST fails (network error, non-2xx response, or malformed JSON), the package SHALL raise `PaymentProviderError(PAYMENT_PROVIDER.OAUTH_TOKEN_FAILURE)` with `provider: "paypal"`, the token URL on the `url` discriminant, and the underlying failure attached as `cause`. The error SHALL be raised before any subsequent Orders-v2 HTTP call is attempted. #### Scenario: non-2xx token response - **WHEN** the injected `FetchLike` returns a 401 from the token endpoint - **THEN** the caller observes a `PaymentProviderError` with `code === "PAYMENT_PROVIDER.OAUTH_TOKEN_FAILURE"`, `provider === "paypal"`, `cause` set to the underlying `PaymentProviderError(HTTP_ERROR)`, and the recorder shows zero Orders-v2 calls #### Scenario: network-level token failure - **WHEN** the injected `FetchLike` throws a transport error on the token endpoint - **THEN** the same `OAUTH_TOKEN_FAILURE` is raised with the transport error on `cause` **Verified by:** `src/paypal/paypal-token.test.ts::"raises OAUTH_TOKEN_FAILURE when the token endpoint returns a non-2xx"` AND `src/paypal/paypal-token.test.ts::"raises OAUTH_TOKEN_FAILURE when the token endpoint throws"` --- ### Requirement: PayPalConfig constructor surface The package SHALL export a `PayPalConfig` interface extending the slim core's `OAuthConfig`. It MUST add a single optional `sandbox?: boolean` field. When `sandbox` is `true` and `baseUrl` is not supplied, the provider MUST use `https://api-m.sandbox.paypal.com` as the default base URL; otherwise (when `baseUrl` is unset and `sandbox` is not `true`), it MUST default to `https://api-m.paypal.com`. An explicit `baseUrl` always wins over the `sandbox` flag. #### Scenario: sandbox flag selects the sandbox endpoint - **WHEN** a caller constructs `new PayPalProvider({ clientId, clientSecret, sandbox: true })` and the recorder observes any call - **THEN** the recorder sees URLs prefixed with `https://api-m.sandbox.paypal.com` #### Scenario: explicit baseUrl overrides sandbox - **WHEN** a caller passes both `sandbox: true` and `baseUrl: "https://override/v2"` - **THEN** the recorder sees URLs prefixed with `https://override` **Verified by:** `src/paypal/paypal-token.test.ts::"defaults to the sandbox endpoint when sandbox flag is true"` AND `src/paypal/paypal-token.test.ts::"explicit baseUrl overrides the sandbox flag"` --- ### Requirement: createIntent maps CreatePaymentIntentInput to PayPal orders `createIntent` SHALL POST `/v2/checkout/orders` with the cached bearer token, a body of `{ intent, purchase_units: [{ amount: { currency_code, value }, description? }] }`, and — when the caller supplies `idempotencyKey` — a `PayPal-Request-Id` header equal to that key. The `intent` MUST be `"AUTHORIZE"` when `captureMethod === "manual"` and `"CAPTURE"` otherwise. The body's `value` MUST be the MoneyLike `bigint` amount converted to a major-unit decimal string with exactly two minor-unit digits (e.g. `5000n` → `"50.00"`). #### Scenario: manual capture creates an AUTHORIZE order - **WHEN** a caller invokes `createIntent({ amount: { amount: 5000n, currency: "USD" }, captureMethod: "manual", idempotencyKey: "idem-1" })` - **THEN** the recorder sees a POST to `…/v2/checkout/orders` with a body whose `intent === "AUTHORIZE"`, `purchase_units[0].amount.value === "50.00"`, and headers include `"PayPal-Request-Id": "idem-1"` AND `"Authorization": "Bearer "` #### Scenario: automatic capture creates a CAPTURE order - **WHEN** a caller invokes `createIntent({ amount: { amount: 1000n, currency: "EUR" }, captureMethod: "automatic" })` - **THEN** the recorder sees a body whose `intent === "CAPTURE"`, `purchase_units[0].amount.value === "10.00"`, and the request carries no `PayPal-Request-Id` header **Verified by:** `src/paypal/paypal.test.ts::"createIntent with manual captureMethod posts an AUTHORIZE order"` AND `src/paypal/paypal.test.ts::"createIntent with automatic captureMethod posts a CAPTURE order without an idempotency header"` --- ### Requirement: confirmIntent posts authorize and captureIntent posts capture `confirmIntent` SHALL POST `/v2/checkout/orders/{intentId}/authorize` with the cached bearer token and return the mapped `PaymentIntent`. `captureIntent` SHALL POST `/v2/checkout/orders/{intentId}/capture` with the cached bearer token and return the mapped `PaymentIntent` whose `capturedAmount.amount` is the sum of every `purchase_units[].payments.captures[].amount.value` parsed as a `bigint` minor-unit value. #### Scenario: confirmIntent maps APPROVED to authorized - **WHEN** PayPal returns an order with `status: "APPROVED"` - **THEN** the returned `PaymentIntent.status === "authorized"` #### Scenario: captureIntent sums every capture - **WHEN** PayPal returns an order with two captures of `"25.00"` USD each - **THEN** the returned `PaymentIntent.capturedAmount.amount === 5000n` **Verified by:** `src/paypal/paypal.test.ts::"confirmIntent posts authorize and maps APPROVED to authorized"` AND `src/paypal/paypal.test.ts::"captureIntent sums every purchase_unit capture into capturedAmount"` --- ### Requirement: cancelIntent voids the order and returns a canceled intent `cancelIntent` SHALL POST `/v2/checkout/orders/{intentId}/void` with the cached bearer token and return a synthesised `PaymentIntent` carrying the same `id`, `status: "canceled"`, zero `amount` / `capturedAmount` / `refundedAmount` (USD currency), and `createdAt` / `updatedAt` equal to `new Date(now()).toISOString()`. The injected `NowFn` MUST be the sole source of these timestamps so tests can pin them. #### Scenario: cancelIntent issues a void and returns canceled intent - **WHEN** a caller invokes `cancelIntent("ORDER_x")` with an injected `now` returning `1_700_000_000_000` - **THEN** the recorder sees a POST to `…/v2/checkout/orders/ORDER_x/void`, the returned intent has `id === "ORDER_x"`, `status === "canceled"`, and `createdAt === updatedAt === new Date(1_700_000_000_000).toISOString()` **Verified by:** `src/paypal/paypal.test.ts::"cancelIntent voids the order and returns a canceled intent with injected-now timestamps"` --- ### Requirement: refund posts to /payments/captures/{id}/refund `refund` SHALL POST `/v2/payments/captures/{paymentIntentId}/refund` with the cached bearer token. When the caller supplies `amount`, the body MUST include `{ amount: { currency_code, value } }` with the same decimal-string marshalling rule as `createIntent`. When the caller supplies `idempotencyKey`, the request MUST carry a `PayPal-Request-Id` header. When the caller supplies neither, the request body MUST be an empty object and no idempotency header is sent. The returned `Refund` MUST carry the PayPal refund `id`, the caller's `paymentIntentId`, the parsed amount, and the mapped `RefundStatus`. #### Scenario: full-amount refund with idempotency key - **WHEN** a caller invokes `refund({ paymentIntentId: "CAP_x", amount: { amount: 2000n, currency: "USD" }, idempotencyKey: "rfn-1" })` - **THEN** the recorder sees a POST whose body is `{ amount: { currency_code: "USD", value: "20.00" } }` and headers include `"PayPal-Request-Id": "rfn-1"` #### Scenario: bare refund with no amount or idempotency - **WHEN** a caller invokes `refund({ paymentIntentId: "CAP_x" })` - **THEN** the recorder sees a POST with an empty-object body and no `PayPal-Request-Id` header **Verified by:** `src/paypal/paypal.test.ts::"refund with explicit amount and idempotency posts amount body and PayPal-Request-Id header"` AND `src/paypal/paypal.test.ts::"refund without amount or idempotency posts an empty body and no idempotency header"` --- ### Requirement: getIntent fetches an order `getIntent` SHALL GET `/v2/checkout/orders/{intentId}` with the cached bearer token and return the mapped `PaymentIntent`. #### Scenario: getIntent fetches and maps an order - **WHEN** a caller invokes `getIntent("ORDER_y")` and PayPal returns a `COMPLETED` order with no captures - **THEN** the returned `PaymentIntent` has `id === "ORDER_y"`, `status === "captured"`, and `capturedAmount.amount === 0n` **Verified by:** `src/paypal/paypal.test.ts::"getIntent fetches the order and maps PayPal status to PaymentStatus"` --- ### Requirement: PayPal status mapping is exhaustive The package SHALL map PayPal order statuses to genesis `PaymentStatus` exactly as follows: `CREATED` → `created`, `SAVED` → `created`, `APPROVED` → `authorized`, `VOIDED` → `canceled`, `COMPLETED` → `captured`, `PAYER_ACTION_REQUIRED` → `pending`. Any other PayPal status — including the empty string and unknown strings — MUST map to `failed`. The refund-status mapping is: `COMPLETED` → `succeeded`, `PENDING` → `pending`, every other value → `failed`. #### Scenario: every documented PayPal status maps correctly - **WHEN** the caller invokes `getIntent` and PayPal returns each of the six documented statuses in turn - **THEN** the returned `PaymentIntent.status` equals the mapped value above; an undocumented status returns `failed` #### Scenario: refund-status mapping - **WHEN** the caller invokes `refund({ paymentIntentId: "x" })` and PayPal returns each of `COMPLETED`, `PENDING`, and an unknown status - **THEN** the returned `Refund.status` equals `succeeded`, `pending`, and `failed` respectively **Verified by:** `src/paypal/paypal.test.ts::"maps every documented PayPal order status to PaymentStatus"` AND `src/paypal/paypal.test.ts::"maps every documented PayPal refund status to RefundStatus"` --- ### Requirement: Universal-tier purity — no Node, browser, or React deps The package SHALL run unchanged on Node, Bun, browsers, and Web Workers. Source files MUST NOT import from `node:*`, `bun:*`, `react`, the DOM globals (`window`, `document`, `localStorage`, …), or any other runtime-specific surface. The base-64 encoder used for the OAuth Basic header MUST go through the injected `Base64EncodeFn` (defaulting to `globalThis.btoa`) so a runtime without `btoa` can supply its own encoder without forking the package. #### Scenario: dependency graph has only universal-tier siblings - **WHEN** the dep-graph test reads the package's `package.json` and the source-import graph - **THEN** the only `@suaveplan/*` deps are `payment`, `payment-providers`, and `error`; the only external dep is `tslib`; no `node:` / `bun:` / `react` / DOM-global imports appear in `src/` **Verified by:** `tests/dep-graph.test.ts::"declares only universal-tier dependencies"` AND `tests/dep-graph.test.ts::"source imports only @suaveplan/* siblings, tslib, and node-free intrinsics"` --- ### Requirement: Errors raised only as PaymentProviderError The package SHALL never raise a bare `Error` or any non-`PaymentProviderError` class from `@suaveplan/error`. Every failure path — token failure, HTTP non-2xx, JSON parse failure, transport error — surfaces as a `PaymentProviderError` from the slim core's factories (`oauthTokenFailure`, `httpError`, `timeoutError`, `parseError`), with `provider === "paypal"`. #### Scenario: every failure path narrows to PaymentProviderError - **WHEN** any of the four documented failure paths fires - **THEN** the thrown value is an `instanceof PaymentProviderError` from `@suaveplan/payment-providers` and the `provider` discriminant equals `"paypal"` **Verified by:** `src/paypal/paypal.test.ts::"every failure path narrows to PaymentProviderError with provider 'paypal'"`