@gopaycz/gopay-js-sdk 1.6.6 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,56 @@
+# [1.8.0](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/compare/1.7.1...1.8.0) (2026-07-08)
+
+
+### Bug Fixes
+
+* suppress js-yaml CVE-1121860 pending age-gate (audit) GPOMA-2398 ([2cc80b6](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/2cc80b69082d3b851b17cc52da8a7a76a8e7eb41))
+
+
+### Features
+
+* **ci:** introduce internal README and stop mirroring it to GitHub GPOMA-2398 ([11c0ff9](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/11c0ff99c1e56f867c37fd2c67b9e9328ac6ec08))
+
+## [1.7.1](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/compare/1.7.0...1.7.1) (2026-06-29)
+
+
+### Bug Fixes
+
+* add fancy npm badges GPOMA-2375 ([9a8f3a7](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/9a8f3a76661d069a5b23791759062e3b39a8b21a))
+
+# [1.7.0](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/compare/1.6.7...1.7.0) (2026-06-29)
+
+
+### Bug Fixes
+
+*  use api from production link GPOMA-2375 ([51e1574](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/51e157458f0f54a18a1460f4754df3c5103a560f))
+* **audit:** suppress git-raw-commits deprecation GPOMA-2375 ([35f2379](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/35f237916d8581427bb9b358ffa20e0c07e9fc82))
+* **browser-sdk:** guard attachPayment() against re-call while card form mounted D1 GPOMA-2375 ([41fa86d](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/41fa86d19957c6e1b0c94c491f2dfb8db438330e))
+* **cards,polling,wallets,http:** code bugs B1 B2 B3 B6 D3 GPOMA-2375 ([55228e3](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/55228e3c5e0de30fa0934fddb31ff53ef6f2b5a7))
+* **cards:** use cardFormSessionActive flag to close race in isCardFormMounted (D1) GPOMA-2375 ([b1d85c5](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/b1d85c5531b512c2d7160c693fe22c92e40d1cf9))
+* **polling:** forward abort signal to per-poll client.get() GPOMA-2375 ([5d36270](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/5d36270589fe92e6b690276e47dd474bf99d58e8))
+* update push instructions GPOMA-2375 ([160ce7e](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/160ce7e98c1143abe34e081153cc5bec7c418027))
+
+
+### Features
+
+* **api:** wire AbortSignal through public payment methods (D4) GPOMA-2375 ([a23bd08](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/a23bd08e6b99fa89901a7813f581adfdfae91a2d))
+* **errors,polling:** attach chargeState to CHARGE_FAILED error for catch callers D2 GPOMA-2375 ([26f1f38](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/26f1f38470c47b008684de17eb742f0c820ba1a3))
+* **http:** add AbortSignal to RequestOptions and thread into all fetch calls D4 GPOMA-2375 ([81c2721](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/81c27211fabefc5de47b7211aad9b73403bc5755))
+* **payments:** add awaitPaymentStatus() polling helper for QR and bank-transfer flows M1 GPOMA-2375 ([10b447a](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/10b447a8202607afc9b737aa44f4ae7ed8a1fce3))
+* **scopes:** export GoPayScopes constants and combineScopes helper M2 GPOMA-2375 ([74b94f8](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/74b94f84e2c815789c4842d088e7ddc43eba8e64))
+
+## [1.6.7](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/compare/1.6.6...1.6.7) (2026-06-24)
+
+
+### Bug Fixes
+
+* clarify theming link GPOMA-2364 ([dca521f](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/dca521f92fce78714d5ae5ee0ae2052f75f160f4))
+* rename env filename GPOMA-2364 ([5eed047](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/5eed047b701a3350370c6da2467bdcb2bbacf356))
+* rename remaining GP_GW_JS_SDK_* refs and make BASE_URL optional in e2e config GPOMA-2364 ([4e4774b](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/4e4774b1a8e4f5948f8674e3805568ba9aa4b445))
+* run tests on local node GPOMA-2364 ([a54e7fa](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/a54e7facda750dcc423fdca0ae7142b93cc9344d))
+* update env example GPOMA-2364 ([fe2a3ea](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/fe2a3eaa86ab5ef2c77ed3e2016f3069b5d5ff2e))
+* update README env var names to GOPAY_PAYMENTS_V4_ prefix GPOMA-2364 ([cb3a07a](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/commits/cb3a07a056a10fd3d90f0d20fa147e7ddfb4a34f))
+
 ## [1.6.6](https://bitbucket.org/gp-gopay/gp-gw-js-sdk/compare/1.6.5...1.6.6) (2026-06-17)
 
 

package/README.md

@@ -1,6 +1,11 @@
 # @gopaycz/gopay-js-sdk
 
-GoPay JavaScript SDK for server-side use (Node.js) — wraps the GoPay Payments API v4.0.
+[![npm](https://img.shields.io/npm/v/@gopaycz/gopay-js-sdk)](https://www.npmjs.com/package/@gopaycz/gopay-js-sdk)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gp-gopay_gp-gw-js-sdk&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gp-gopay_gp-gw-js-sdk)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=gp-gopay_gp-gw-js-sdk&metric=coverage)](https://sonarcloud.io/summary/new_code?id=gp-gopay_gp-gw-js-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+GoPay JavaScript SDK for server-side use (Node.js) — wraps the new [GoPay Payments API v4](https://api-docs.gopay.com/).
 
 > **Building a browser integration?** Use [`@gopaycz/gopay-js-sdk-browser`](../browser-sdk/README.md) — it handles in-browser card encryption, direct-charge flows, and exposes an IIFE bundle for CDN use.
 
@@ -50,14 +55,15 @@ const payment = await sdk.createPayment('YOUR_GOID', {
 Once the customer completes the payment flow and returns to your site, charge the payment using the instrument they provided:
 
 ```ts
-// Card token (obtained via sdk.mountCardForm() — returns an object, use .token)
+// Card token: obtained via the browser SDK card form (see @gopaycz/gopay-js-sdk-browser)
+// and forwarded to your server after tokenization via sdk.tokenizeEncryptedCard()
 const charge = await sdk.chargePayment(payment.id, {
   payment_instrument: {
     payment_instrument: 'PAYMENT_CARD',
     input: {
       input_type: 'CARD_TOKEN',
       card_token: cardToken.token,
-      challenge_preferrence: 'AUTO',
+      challenge_preference: 'AUTO',
     },
   },
 });
@@ -82,7 +88,7 @@ The SDK uses OAuth2. **Client credentials (`client_id` / `client_secret`) must n
 Your backend holds the credentials. Call `authenticate()` once on startup — the SDK stores the token and refreshes it transparently before expiry:
 
 ```ts
-import { createGoPaySDK } from '@gopaycz/gopay-js-sdk';
+import { createGoPaySDK, GoPayScopes } from '@gopaycz/gopay-js-sdk';
 
 const sdk = createGoPaySDK({ environment: 'production' });
 
@@ -90,13 +96,27 @@ await sdk.authenticate({
   grant_type: 'client_credentials',
   client_id: process.env.GOPAY_CLIENT_ID,
   client_secret: process.env.GOPAY_CLIENT_SECRET,
-  scope: 'payment:write payment:read',
+  scope: GoPayScopes.PAYMENT_WRITE + ' ' + GoPayScopes.PAYMENT_READ,
+  // or: scope: combineScopes(GoPayScopes.PAYMENT_WRITE, GoPayScopes.PAYMENT_READ)
+  // or just a plain string: scope: 'payment:write payment:read'
 });
 
 // All subsequent calls attach the Bearer token automatically.
 const payment = await sdk.createPayment(goid, params);
 ```
 
+### Scopes reference
+
+| Scope | Constant | Used by |
+|---|---|---|
+| `payment:write` | `GoPayScopes.PAYMENT_WRITE` | `createPayment`, `chargePayment`, `refundPayment`, recurrences, payment links |
+| `payment:read` | `GoPayScopes.PAYMENT_READ` | `getPaymentStatus`, `getChargeState`, `listRefunds`, `getRefund`, recurrence status |
+| `card:write` | `GoPayScopes.CARD_WRITE` | `getBrowserKeys()` — allows the browser SDK to present the card form |
+| `card:read` | `GoPayScopes.CARD_READ` | `getCardDetails`, `deleteCard` |
+| `payment:charge` | `GoPayScopes.PAYMENT_CHARGE` | Browser SDK only (`attachPayment` / `payment_credentials` grant) |
+
+For `getBrowserKeys()` to work, include `card:write` in your server-side `authenticate()` call. `shareableKey` must also be set in the SDK config (see [Browser keys](#browser-keys) below). Include `payment:write` (and any other scopes) as needed for the rest of your integration.
+
 ---
 
 ## Configuration
@@ -153,6 +173,28 @@ The one exception is `startApplePaySession`: it returns `void` instead of a Prom
 | `isAuthenticated()` | Returns `true` if a token is currently stored. Does not check expiry — expired tokens are refreshed transparently on the next API call. |
 | `logout()` | Clear all stored tokens and credentials. All subsequent API calls will throw until the SDK is re-authenticated. |
 
+#### Browser keys
+
+`getBrowserKeys()` returns `{ shareable_key, client_id }` — pass both to the browser SDK via your own API endpoint.
+
+**Prerequisites:**
+- The `shareableKey` option must be set when creating the SDK:
+  ```ts
+  const sdk = createGoPaySDK({
+    environment: 'production',
+    shareableKey: process.env.GOPAY_SHAREABLE_KEY, // issued in GoPay admin alongside client_id
+  });
+  ```
+- The token scope must include `card:write` (obtain `shareableKey` from the GoPay admin portal):
+  ```ts
+  await sdk.authenticate({
+    ...,
+    scope: 'payment:write payment:read card:write',
+  });
+  ```
+
+Throws `AUTH_CREDENTIALS_MISSING` if either prerequisite is missing.
+
 ### Payments
 
 | Method | Description |
@@ -313,127 +355,72 @@ document.body.appendChild(img);
 
 ### Cards
 
+> **SDK boundary:** card data encryption and the card form UI live in the **browser SDK** ([`@gopaycz/gopay-js-sdk-browser`](../browser-sdk/README.md)), not here. The browser encrypts the card inside a GoPay-hosted iframe and returns an `encryptedPayload`; your server calls `tokenizeEncryptedCard` to convert it to a card token, then charges the payment. Raw card data never touches your server or this SDK.
+
 | Method | Description |
 |---|---|
-| `mountCardForm(container, options?)` | Fetches the GoPay-hosted iframe URL from `GET /encryption/card-form-url`, mounts it into `container`, and returns `Promise<CardFormController>`. The controller exposes a `result` promise (resolves to the card token on submit), `setTheme()`, `setLocale()`, `submit()`, and `isValid` for runtime control. Handles iframe creation, internal communication, and `POST /cards/tokens` internally. Requires the `card:write` scope. |
-| `getCardDetails(cardId)` | Retrieve details of a stored permanent card token (`GET /cards/tokens/{cardId}`). Returns masked PAN, expiry, scheme, fingerprint, and the reusable token. Requires the `card:read` scope. |
-| `deleteCard(cardId)` | Delete a stored permanent card token (`DELETE /cards/tokens/{cardId}`). Returns `void`. |
-
-#### `mountCardForm` options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `theme` | `CardFormTheme` | `DEFAULT_CARD_FORM_THEME` | Visual theme (colors, font sizes, spacing, button styles). All fields are optional — the iframe applies built-in defaults for any omitted field. |
-| `locale` | `string` | `navigator.language` | BCP 47 language tag for form labels and placeholders. The region subtag is ignored (`'cs-CZ'` → `'cs'`). Unknown locales fall back to English. Supported: `bg` `cs` `de` `en` `es` `et` `fr` `hr` `hu` `it` `lt` `lv` `nl` `pl` `pt` `ro` `ru` `sk` `sl` `uk`. |
-| `submitMode` | `'internal' \| 'external'` | `'internal'` | `'internal'` — the iframe renders its own submit button. `'external'` — the iframe hides the button; the parent controls submission via `cardForm.submit()` and receives validity changes via `onValidityChange`. |
-| `permanent` | `boolean` | `false` | When `true`, a permanent (reusable) card token is created that can be charged again for future payments. When `false` (default), a single-use token is created. |
-| `onValidityChange` | `(isValid: boolean) => void` | — | Called whenever the overall form validity changes in external submit mode. Use this to enable/disable your external submit button. |
-
-> **Send theme and locale at init time.** Both options are applied before the form is first painted, avoiding a flash of unstyled content. Use `cardForm.setTheme()` and `cardForm.setLocale()` on the returned controller if you need to update them after mounting.
-
-`CardFormTheme` is fully typed — hover in your editor to see every available field. Notable fields:
+| `tokenizeEncryptedCard(encryptedPayload)` | Convert the encrypted payload returned by the browser SDK into a card token (`POST /cards/tokens`). Requires `card:write` scope. Returns `{ token, card_id? }`. |
+| `getCardDetails(cardId)` | Retrieve details of a stored permanent card token (`GET /cards/tokens/{cardId}`). Returns masked PAN, expiry, scheme, fingerprint, and the reusable token. Requires `card:read` scope. |
+| `deleteCard(cardId)` | Delete a stored permanent card token (`DELETE /cards/tokens/{cardId}`). Returns `void`. Requires `card:read` scope. |
 
-| Field | Type | Default | Description |
-|---|---|---|---|
-| `fontFamily` | `string` | `system-ui, sans-serif` | CSS font-family stack applied to all form text (labels, inputs, errors, submit button). Use system font stacks — e.g. `"Inter, system-ui, sans-serif"` — to match your page without loading external fonts. |
+### Flow A — server-side card charge
 
-> **Color format restriction.** All color fields in `CardFormTheme` must use one of the following CSS formats: `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `hsla(...)`, or `transparent`. Values that do not match are silently replaced with `unset` (browser default). Named colors (e.g. `red`) and other CSS values are not accepted.
-
-Theme presets are exported from the package:
+The browser encrypts the card; your server tokenizes and charges. This is the recommended flow when your server handles the charge (e.g. to save the token for future use).
 
 ```ts
-import {
-  GoPaySDK,
-  DEFAULT_CARD_FORM_THEME,
-  DARK_CARD_FORM_THEME,
-} from '@gopaycz/gopay-js-sdk';
-
-// Default theme, locale from navigator.language (options can be omitted entirely)
-const cardForm = await sdk.mountCardForm(container);
-const cardToken = await cardForm.result;
-
-// Dark theme with Czech locale
-const cardForm = await sdk.mountCardForm(container, {
-  theme: DARK_CARD_FORM_THEME,
-  locale: 'cs',
-});
-const cardToken = await cardForm.result;
-
-// Custom theme — override individual fields, keep the rest as defaults
-const cardForm = await sdk.mountCardForm(container, {
-  theme: { ...DEFAULT_CARD_FORM_THEME, submitBackgroundColor: '#your-brand-color' },
-});
-
-// Update theme or locale at runtime (e.g. user toggles dark mode or language)
-darkModeToggle.addEventListener('change', () => cardForm.setTheme(DARK_CARD_FORM_THEME));
-langSelect.addEventListener('change', e => cardForm.setLocale(e.target.value));
+// ── Browser (using @gopaycz/gopay-js-sdk-browser) ──────────────────────────
+import { createGoPayBrowserSDK, collectBrowserData } from '@gopaycz/gopay-js-sdk-browser';
 
-const cardToken = await cardForm.result;
-```
-
-#### External submit button
-
-Use `submitMode: 'external'` when you want the submit button to live outside the iframe — for example to match your own checkout UI. The iframe hides its built-in button, reports validity changes via `onValidityChange`, and waits for `cardForm.submit()` to trigger encryption.
+const browserSdk = createGoPayBrowserSDK({ environment: 'production', shareableKey, clientId });
+const controller = await browserSdk.mountCardForm(container, { flow: 'return-payload' });
+const { encryptedPayload } = await controller.result;
 
-```ts
-const payBtn = document.getElementById('pay-btn');
+// Collect browser data for 3DS — must be done in the browser
+const browserData = collectBrowserData();
 
-const cardForm = await sdk.mountCardForm(container, {
-  submitMode: 'external',
-  onValidityChange(isValid) {
-    // Enable/disable your own submit button based on form validity.
-    payBtn.disabled = !isValid;
-  },
+// Forward both to your server endpoint
+await fetch('/api/charge', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ paymentId, encryptedPayload, browserData }),
 });
 
-payBtn.addEventListener('click', () => {
-  cardForm.submit(); // triggers encryption inside the iframe
-});
-
-// Await the result exactly the same as in internal submit.
-const cardToken = await cardForm.result;
-```
-
-`cardForm.isValid` is also available as a synchronous getter in case you need to read the current validity state imperatively (e.g. inside a click handler before calling `submit()`).
-
-> Calling `submit()` in internal submit mode throws a `GoPaySDKError`. Calling it after the form completes or is unmounted is a no-op.
-
-### Card Pay
+// ── Server (using @gopaycz/gopay-js-sdk) ───────────────────────────────────
+import { createGoPaySDK } from '@gopaycz/gopay-js-sdk';
 
-Card number encryption must never run in publicly reachable JavaScript — doing so would expose the raw PAN to any script on the merchant's page. The SDK uses a GoPay-hosted iframe for this step so that raw card data never touches merchant code.
+const sdk = createGoPaySDK({ environment: 'production' });
+await sdk.authenticate({ ..., scope: 'payment:write payment:read card:write' });
 
-```ts
-// 1. Create a payment session first (server-side).
-const payment = await sdk.createPayment(goid, params);
+// Handler for POST /api/charge
+const { encryptedPayload, paymentId, browserData } = req.body;
 
-// 2. Mount the iframe — the SDK fetches the hosted form URL from the API,
-//    mounts the iframe, then awaits the user submitting the card form,
-//    and calls POST /cards/tokens automatically.
-const container = document.getElementById('card-form-container');
-const cardForm = await sdk.mountCardForm(container);
-const cardToken = await cardForm.result;
+// 1. Convert encrypted payload to a card token
+const cardToken = await sdk.tokenizeEncryptedCard(encryptedPayload);
 
-// 3. Charge the payment with the resulting card token.
-const charge = await sdk.chargePayment(payment.id, {
+// 2. Charge the payment — always forward browserData from the browser for 3DS
+const charge = await sdk.chargePayment(paymentId, {
   payment_instrument: {
     payment_instrument: 'PAYMENT_CARD',
     input: {
       input_type: 'CARD_TOKEN',
       card_token: cardToken.token,
-      challenge_preferrence: 'AUTO',
+      challenge_preference: 'AUTO',
+      browser_data: browserData, // required for 3DS — do not omit
     },
   },
 });
 
 if (charge.action?.redirect_url) {
-  // 3DS authentication required — redirect the customer.
-  window.location.href = charge.action.redirect_url;
+  // 3DS authentication required — redirect the customer
+  res.json({ redirectUrl: charge.action.redirect_url });
 }
 ```
 
+> **`browser_data` is required for 3DS.** The server SDK does not auto-collect it (only the browser SDK can). Always forward it from the browser via `collectBrowserData()`. Without it, 3DS context is absent and approval rates degrade.
+
 ### Saved cards
 
-When `mountCardForm` is called with `permanent: true`, the resulting `cardToken.token` is a permanent token tied to a card ID (`cardToken.card_id`). You can retrieve or delete it later:
+To save a card for future payments, pass `permanent: true` to `mountCardForm` in the browser SDK. The resulting `cardToken.card_id` can be stored and used to charge again without re-entering card details:
 
 ```ts
 // Retrieve details of a stored card (masked PAN, expiry, scheme, etc.)
@@ -452,8 +439,6 @@ const charge = await sdk.chargePayment(payment.id, {
 await sdk.deleteCard(card.card_id);
 ```
 
-`GET /encryption/public-key` and the JWE construction it enables are **intentionally not part of this SDK's API surface**.
-
 ---
 
 ### Recurrences
@@ -600,6 +585,23 @@ try {
 | `status` | `number` | HTTP status code (e.g. `401`, `422`). |
 | `body` | `unknown` | Parsed JSON response body, or raw text if JSON parsing failed. |
 
+A 422 error from `chargePayment` with an invalid amount looks like:
+
+```json
+{
+  "date_time": "2024-03-15T14:22:00.000+0100",
+  "error_code": 400,
+  "error_name": "PAYMENT_VALIDATION_ERROR",
+  "message": [
+    {
+      "field": "amount",
+      "message": "INVALID",
+      "description": "Value 0 is out of allowed range [1, 99999999]"
+    }
+  ]
+}
+```
+
 ### Centralised error handling with `onError`
 
 Pass an `onError` callback to the SDK config to intercept every error in one place — useful for logging or alerting — without replacing per-call `catch` blocks: