@finteqhub/sdk-js 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,13 +1,32 @@
 # Changelog
 
-Notable changes to `@finteqhub/sdk-js`. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Notable changes to the SDK. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 0.17.0
+
+### Breaking changes
+
+- The SDK class is now exported as `Processing`; the previous class name is no longer exported.
+- The constructor takes a single options object instead of positional arguments. The object is validated like the positional arguments were; passing positional arguments throws `TypeError: sdk-js: constructor expects an options object`. Unknown keys are rejected too (`TypeError: sdk-js: unknown option "issecure"`), so a misspelled option, or a `merchantId` left over from 0.15.0, fails loudly instead of silently falling back to the default. The new `ProcessingOptions` type is exported.
+
+Migration:
+
+```
+// 0.16.0: positional arguments
+(apiUrl, fingerprintVisitorId, sessionId, isSecure, retryOptions)
+
+// 0.17.0: an options object
+new Processing({ apiUrl, fingerprintVisitorId, sessionId, isSecure, retryOptions });
+```
+
+`isSecure` and `retryOptions` stay optional, with the same defaults (`false` and `{}`).
 
 ## 0.16.0
 
 ### Breaking changes
 
 - The SDK no longer sends the `x-merchant-id` header (previously on every request) or the `x-project-id` header (previously on `submit-form` and `operations` requests, taken from the session response). This release requires a backend that no longer expects these headers; against older backends `submit-form` and `sessions` requests are rejected with 400.
-- The `merchantId` constructor argument was removed together with the header. The constructor is now `new FinteqHubProcessing(apiUrl, fingerprintVisitorId, sessionId, isSecure?, retryOptions?)` — every argument after `fingerprintVisitorId` shifts one position to the left. Callers must drop the third argument; a call site that still passes it fails argument validation (`isSecure` receives the session id, which is not a boolean, and the constructor throws a `TypeError`).
+- The `merchantId` constructor argument was removed together with the header. The constructor arguments are now `(apiUrl, fingerprintVisitorId, sessionId, isSecure?, retryOptions?)` — every argument after `fingerprintVisitorId` shifts one position to the left. Callers must drop the third argument; a call site that still passes it fails argument validation (`isSecure` receives the session id, which is not a boolean, and the constructor throws a `TypeError`).
 
 ### Changed
 
@@ -41,7 +60,7 @@ No code changes: the SDK behaves exactly as in 0.13.0 (only the version reported
 
 ### Breaking changes
 
-- The SDK identification header sent with every request was renamed from `X-Finteqhub-SDK` to `x-pgw-sdk`, now spelled in lower case to match the other headers the SDK sends. Header names are case-insensitive, so only the name itself changed; the value format (`sdk-js/<version>`) is unchanged.
+- The SDK identification header sent with every request was renamed to `x-pgw-sdk`, spelled in lower case to match the other headers the SDK sends. Backends that read the header by its previous name must switch to `x-pgw-sdk`; the value format (`sdk-js/<version>`) is unchanged.
 
 ## 0.12.0
 

package/README.md

@@ -1,16 +1,28 @@
 # processing-sdk
 
-Use `new FinteqHubProcessing(apiUrl: string, fingerprintVisitorId: string, sessionId: string, isSecure?: boolean, retryOptions?: RetryOptions)` to create an instance of the FinteqHubProcessing object. The FinteqHubProcessing object is your entrypoint to FinteqHub processing SDK.
+Use `new Processing(options: ProcessingOptions)` to create an instance of the Processing object. The Processing object is your entrypoint to the processing SDK.
 
 ```
-const processing = new FinteqHubProcessing('api-url', 'fingerprint-visitor-id', 'session-id');
+interface ProcessingOptions {
+  apiUrl: string;
+  fingerprintVisitorId: string;
+  sessionId: string;
+  isSecure?: boolean; // default false
+  retryOptions?: RetryOptions; // default {}
+}
+
+const processing = new Processing({
+  apiUrl: 'api-url',
+  fingerprintVisitorId: 'fingerprint-visitor-id',
+  sessionId: 'session-id',
+});
 ```
 
-The constructor validates its arguments and throws a `TypeError` when `apiUrl`, `fingerprintVisitorId` or `sessionId` is missing, empty or not a string, when `isSecure` is not a boolean, or when `retryOptions` is malformed (see [Retries and error diagnostics](#retries-and-error-diagnostics)).
+The constructor validates its options and throws a `TypeError` when they are not an object, when they contain an unknown key (for example a misspelled `issecure`), when `apiUrl`, `fingerprintVisitorId` or `sessionId` is missing, empty or not a string, when `isSecure` is not a boolean, or when `retryOptions` is malformed (see [Retries and error diagnostics](#retries-and-error-diagnostics)).
 
 ## Retries and error diagnostics
 
-Failed HTTP requests are retried automatically with exponential backoff (`100ms → 200ms → 500ms → 1000ms → 2000ms`; every retry after the fifth waits 2000ms). Retries can be configured via the optional `retryOptions` constructor argument (the fifth one, after `isSecure`):
+Failed HTTP requests are retried automatically with exponential backoff (`100ms → 200ms → 500ms → 1000ms → 2000ms`; every retry after the fifth waits 2000ms). Retries can be configured via the optional `retryOptions` constructor option:
 
 ```
 interface RetryOptions {
@@ -18,16 +30,22 @@ interface RetryOptions {
   retryStatusCode?: (statusCode: number) => boolean; // default: statusCode < 200 || statusCode === 408 || statusCode >= 500
 }
 
-const processing = new FinteqHubProcessing('api-url', 'fingerprint-visitor-id', 'session-id', false, {
-  retryCount: 3,
+const processing = new Processing({
+  apiUrl: 'api-url',
+  fingerprintVisitorId: 'fingerprint-visitor-id',
+  sessionId: 'session-id',
+  retryOptions: { retryCount: 3 },
 });
 ```
 
 To disable retries entirely, pass `retryCount: 0` — every request is then sent exactly once, as in 0.11.0. Error diagnostics (`RequestError`, the `console.error` dump) are still collected:
 
 ```
-const processing = new FinteqHubProcessing('api-url', 'fingerprint-visitor-id', 'session-id', false, {
-  retryCount: 0,
+const processing = new Processing({
+  apiUrl: 'api-url',
+  fingerprintVisitorId: 'fingerprint-visitor-id',
+  sessionId: 'session-id',
+  retryOptions: { retryCount: 0 },
 });
 ```
 
@@ -59,7 +77,7 @@ Every request the SDK makes carries an extra header:
 x-pgw-sdk: sdk-js/<version>
 ```
 
-The value contains the SDK name and version (kept in sync with `package.json` by a test) — for example `sdk-js/0.11.0`. FinteqHub uses this header to identify traffic coming from the official SDK integration — for example to notify affected merchants when a security fix is released. It does not affect authentication or request routing.
+The value contains the SDK name and version (kept in sync with `package.json` by a test) — for example `sdk-js/0.11.0`. The backend uses this header to identify traffic coming from the official SDK integration — for example to notify affected merchants when a security fix is released. It does not affect authentication or request routing.
 
 The header is added automatically to every request and cannot be disabled.
 
@@ -94,13 +112,13 @@ processing
 The minimal flow is to construct the instance and call `submitForm` — no other request is needed before it. Use it when your own UI already knows what to collect from the customer (for example, the payment method and its credential fields are fixed on your side):
 
 ```
-import { FinteqHubProcessing } from "@finteqhub/sdk-js";
+import { Processing } from "@finteqhub/sdk-js";
 import FingerprintJS from "@fingerprintjs/fingerprintjs";
 
 const fp = await FingerprintJS.load();
 const result = await fp.get();
 
-const processing = new FinteqHubProcessing(apiUrl, result.visitorId, sessionId);
+const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });
 
 const data = {/** collect data from form **/}
 
@@ -115,7 +133,7 @@ processing
 Call `getSession` first when the form itself is built from the session: available payment methods, their credential fields, the operation amount and currency. `submitForm` does not use the result — it only drives your UI:
 
 ```
-const processing = new FinteqHubProcessing(apiUrl, result.visitorId, sessionId);
+const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });
 
 const session = await processing.getSession();
 

package/dist/src/processing.d.ts

@@ -3,6 +3,13 @@ export interface RetryOptions {
     retryCount?: number;
     retryStatusCode?: (statusCode: number) => boolean;
 }
+export interface ProcessingOptions {
+    apiUrl: string;
+    fingerprintVisitorId: string;
+    sessionId: string;
+    isSecure?: boolean;
+    retryOptions?: RetryOptions;
+}
 export declare type RequestAttempt = {
     durationMs: number;
     status?: number;
@@ -44,14 +51,14 @@ export declare class RequestError extends Error {
     diagnostics: RequestDiagnostics;
     constructor(message: string, diagnostics: RequestDiagnostics);
 }
-export declare class FinteqHubProcessing {
+export declare class Processing {
     private apiUrl;
     private fingerprintVisitorId;
     private sessionId;
     private projectId;
     private isSecure;
     private retryOptions;
-    constructor(apiUrl: string, fingerprintVisitorId: string, sessionId: string, isSecure?: boolean, retryOptions?: RetryOptions);
+    constructor(options: ProcessingOptions);
     getSession(): Promise<SessionResponse>;
     submitForm(data: SubmitData): Promise<ProcessOperationRedirectResponse>;
     private processOperation;

package/dist/src/processing.js

@@ -24,9 +24,10 @@ const sanitizeBody = (body) => body.slice(0, MAX_BODY_SNIPPET_LENGTH).replace(/\
 // 400 is deliberately not retried: the backend returns it for deterministic validation
 // failures and for duplicate-submit rejections — retrying either only delays the error
 const defaultRetryStatusCode = (statusCode) => statusCode < 200 || statusCode === 408 || statusCode >= 500;
-export class FinteqHubProcessing {
-    constructor(apiUrl, fingerprintVisitorId, sessionId, isSecure = false, retryOptions = {}) {
-        validateArguments({ apiUrl, fingerprintVisitorId, sessionId, isSecure, retryOptions });
+export class Processing {
+    constructor(options) {
+        validateArguments(options);
+        const { apiUrl, fingerprintVisitorId, sessionId, isSecure = false, retryOptions = {} } = options;
         this.apiUrl = apiUrl;
         this.fingerprintVisitorId = fingerprintVisitorId;
         this.sessionId = sessionId;

package/dist/src/utils.d.ts

@@ -1,4 +1,4 @@
-import type { RetryOptions } from "./processing";
+import type { ProcessingOptions } from "./processing";
 export declare const DeviceType: {
     Unknown: string;
     Computer: string;
@@ -10,14 +10,7 @@ export declare const DeviceType: {
 };
 export declare function uuid(): string;
 export declare function getDeviceType(): string;
-declare type ConstructorArguments = {
-    apiUrl: string;
-    fingerprintVisitorId: string;
-    sessionId: string;
-    isSecure: boolean;
-    retryOptions: RetryOptions;
-};
-export declare function validateArguments(args: ConstructorArguments): void;
+export declare function validateArguments(options: ProcessingOptions): void;
 /** Returns native browser hints, falling back to low entropy values if needed. */
 export declare function getClientHints(): Promise<{
     architecture?: string;
@@ -79,4 +72,3 @@ export declare function getDeviceData(): Promise<{
         };
     };
 }>;
-export {};

package/dist/src/utils.js

@@ -50,16 +50,27 @@ export function getDeviceType() {
     return DeviceType.Unknown;
 }
 const REQUIRED_STRINGS = ["apiUrl", "fingerprintVisitorId", "sessionId"];
-export function validateArguments(args) {
+const KNOWN_OPTIONS = [...REQUIRED_STRINGS, "isSecure", "retryOptions"];
+export function validateArguments(options) {
+    // catches callers still using the positional signature from 0.16.0 and earlier
+    if (typeof options !== "object" || options === null) {
+        throw new TypeError("sdk-js: constructor expects an options object");
+    }
+    // a misspelled key (e.g. `issecure`) would otherwise silently fall back to the default
+    for (const key of Object.keys(options)) {
+        if (!KNOWN_OPTIONS.includes(key)) {
+            throw new TypeError(`sdk-js: unknown option "${key}"`);
+        }
+    }
     for (const key of REQUIRED_STRINGS) {
-        if (typeof args[key] !== "string" || args[key] === "") {
+        if (typeof options[key] !== "string" || options[key] === "") {
             throw new TypeError(`sdk-js: ${key} must be a non-empty string`);
         }
     }
-    if (typeof args.isSecure !== "boolean") {
+    const { isSecure = false, retryOptions = {} } = options;
+    if (typeof isSecure !== "boolean") {
         throw new TypeError("sdk-js: isSecure must be a boolean");
     }
-    const { retryOptions } = args;
     if (typeof retryOptions !== "object" || retryOptions === null) {
         throw new TypeError("sdk-js: retryOptions must be an object");
     }

package/dist/src/version.d.ts

@@ -1,3 +1,3 @@
 export declare const SDK_HEADER_NAME = "x-pgw-sdk";
-export declare const SDK_VERSION = "0.16.0";
+export declare const SDK_VERSION = "0.17.0";
 export declare const SDK_HEADER_VALUE: string;

package/dist/src/version.js

@@ -1,3 +1,3 @@
 export const SDK_HEADER_NAME = "x-pgw-sdk";
-export const SDK_VERSION = "0.16.0";
+export const SDK_VERSION = "0.17.0";
 export const SDK_HEADER_VALUE = `sdk-js/${SDK_VERSION}`;

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@finteqhub/sdk-js",
-  "version": "0.16.0",
-  "description": "SDK for interacting with FinteqHub processing API",
+  "version": "0.17.0",
+  "description": "SDK for interacting with the processing API",
   "main": "./dist/index.js",
   "typings": "./dist/index.d.ts",
   "files": [
     "dist/*",
     "CHANGELOG.md"
   ],
-  "author": "FinteqHub",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/finteqhub/sdk-js.git"