Initial Commit

openspec/specs/payment-provider-paypal/spec.md

@@ -0,0 +1,316 @@
+<!-- markdownlint-disable MD024 -->
+
+# 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 <base64Encode(clientId + ":" + clientSecret)>` 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-<encoded>"`
+
+**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 <cached-token>"`
+
+#### 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'"`
+
+<!-- markdownlint-enable MD024 -->