@commercetools/checkout-payments-processor-sdk 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @commercetools/checkout-payments-processor-sdk
+
+## 0.0.2
+
+### Patch Changes
+
+- af90f7f: Sample change for all the packages
+- Updated dependencies [af90f7f]
+  - @commercetools/checkout-payments-lib@0.0.2
+
+## 0.0.1
+
+### Patch Changes
+
+- Initialising repository

package/README.md

@@ -0,0 +1,42 @@
+# @commercetools/checkout-payments-processor-sdk
+
+The Processor Module acts as the middleware between commercetools and the payment service provider, handling transaction processing and payment updates. It handles key operations such as payment authorization, capture, refund, and cancellation directly with the payment service provider while ensuring transactions are processed and saved accurately in commercetools composable commerce.
+
+## Key Responsibilities
+* Receives payment requests from the enabler.
+* Communicates with the PSP for authorization, capture, refund, and cancellation.
+* Updates commercetools payment objects based on PSP responses.
+* Ensures secure and idempotent transaction handling.
+
+## Prerequisites
+
+commercetools Checkout has support for two component integration types (payment components and drop-in components)
+
+The payment connector requires:
+
+* A commercetools Composable Commerce API Client with permissions for:
+  * `manage_payments`
+  * `manage_orders`
+  * `view_sessions`
+  * `view_api_clients`
+  * `manage_checkout_payment_intents`
+  * `introspect_oauth_tokens`
+
+* Additional API credentials  capable of managing connnector-related operations. This includes tasks like:
+  * Installing the connector
+  * Deploying and updating the connector
+  * Performing connector-related maintenance operations
+
+For more details on setting up and managing connectors, refer to the commercetools Connector Deployment Documentation.
+
+# Access & Authentication
+The integration uses several authentication methods to ensure secure communication between different components. These include:
+
+## Session Authentication
+The integration will use session-based authentication for frontend-to-backend communication. The session information is passed via the X-Session-Id header, which is validated by the Processor to ensure the request is trusted and associated with the correct session.
+
+## JWT Validation
+JSON Web Tokens (JWT) are used to validate operations performed within the commercetools Merchant Center. The Processor supports JWT validation to authenticate and authorize requests for internal operations.
+
+## OAuth Authentication
+OAuth 2.0 is used for server-to-server communication to manage secure operations such as capture, cancel, and refund of payments. The OAuth credentials are validated via the introspect_oauth_tokens scope to ensure that the Processor has the necessary permissions for these operations.

package/biome.json

@@ -0,0 +1,38 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "space",
+		"indentWidth": 2
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"style": {
+				"useImportType": "error"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@commercetools/checkout-payments-processor-sdk",
+  "version": "0.0.6",
+  "description": "Checkout payments SDK for processor",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "commercetools",
+  "license": "ISC",
+  "devDependencies": {
+    "@biomejs/biome": "2.2.5",
+    "@tsconfig/node24": "24.0.1",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/lodash": "4.17.20",
+    "@types/node": "24.7.0",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "msw": "2.11.3",
+    "tsc-alias": "1.8.16",
+    "tsx": "4.20.6",
+    "typedoc": "0.28.13",
+    "typescript": "5.9.3",
+    "vite-tsconfig-paths": "5.1.4",
+    "vitest": "3.2.4"
+  },
+  "dependencies": {
+    "@commercetools-backend/loggers": "24.7.2",
+    "@commercetools/platform-sdk": "8.18.0",
+    "@commercetools/ts-client": "4.3.0",
+    "jsonwebtoken": "^9.0.2",
+    "jwks-rsa": "3.2.0",
+    "lodash": "4.17.23",
+    "logform": "2.7.0",
+    "@commercetools/checkout-payments-core": "0.0.6"
+  },
+  "scripts": {
+    "build": "rm -rf ./dist && tsc -p tsconfig.prod.json && tsc-alias",
+    "clean": "rm -rf ./dist ./coverage ./node_modules",
+    "format": "biome check --write ./src",
+    "lint": "biome check ./src",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "doc": "typedoc --options typedoc.json"
+  }
+}

package/src/api/context/request-context.helper.test.ts

@@ -0,0 +1,98 @@
+import { SessionAuthentication } from '@security';
+import type { SessionPrincipal } from '@security-types';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+  getAllowedPaymentMethodsFromContext,
+  getCartIdFromContext,
+  getCheckoutTransactionItemIdFromContext,
+  getCtSessionIdFromContext,
+  getGiftCardPlannedAmountFromContext,
+  getMerchantReturnUrlFromContext,
+  getProcessorUrlFromContext,
+} from '@/api/context/request-context.helper.js';
+import { RequestContextProvider } from '@/api/context/request-context.provider.js';
+
+describe('context', () => {
+  const sessionId = 'random-session-id';
+  const principal: SessionPrincipal = {
+    cartId: 'sample-cart-id',
+    allowedPaymentMethods: [],
+    processorUrl: 'http://127.0.0.1',
+    paymentInterface: 'sample-payment-interface',
+    checkoutTransactionItemId: 'sample-transaction-item-id',
+    merchantReturnUrl: 'https://merchant.return.url',
+    giftCardPlannedAmount: {
+      centAmount: 10,
+      currencyCode: 'EUR',
+    },
+  };
+
+  const authn: SessionAuthentication = new SessionAuthentication(
+    sessionId,
+    principal,
+  );
+
+  const contextProvider = new RequestContextProvider({
+    getContextFn: () => ({
+      correlationId: 'correlation-id',
+      requestId: 'request-id',
+      authentication: authn,
+    }),
+    updateContextFn: () => {},
+  });
+
+  beforeEach(() => {
+    // jest.setTimeout(10000);
+    vi.resetAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('getGiftCardPlannedAmountFromContext', async () => {
+    const result = getGiftCardPlannedAmountFromContext(
+      contextProvider.getContextData(),
+    );
+    expect(result).toStrictEqual({
+      centAmount: 10,
+      currencyCode: 'EUR',
+    });
+  });
+
+  test('getCtSessionIdFromContext', async () => {
+    const result = getCtSessionIdFromContext(contextProvider.getContextData());
+    expect(result).toStrictEqual(sessionId);
+  });
+
+  test('getAllowedPaymentMethodsFromContext', async () => {
+    const result = getAllowedPaymentMethodsFromContext(
+      contextProvider.getContextData(),
+    );
+    expect(result).toHaveLength(0);
+  });
+
+  test('getCartIdFromContext', async () => {
+    const result = getCartIdFromContext(contextProvider.getContextData());
+    expect(result).toStrictEqual('sample-cart-id');
+  });
+
+  test('getMerchantReturnUrlFromContext', async () => {
+    const result = getMerchantReturnUrlFromContext(
+      contextProvider.getContextData(),
+    );
+    expect(result).toStrictEqual('https://merchant.return.url');
+  });
+
+  test('getProcessorUrlFromContext', async () => {
+    const result = getProcessorUrlFromContext(contextProvider.getContextData());
+    expect(result).toStrictEqual('http://127.0.0.1');
+  });
+
+  test('getCheckoutTransactionItemIdFromContext', async () => {
+    const result = getCheckoutTransactionItemIdFromContext(
+      contextProvider.getContextData(),
+    );
+    expect(result).toStrictEqual('sample-transaction-item-id');
+  });
+});

package/src/api/context/request-context.helper.ts

@@ -0,0 +1,89 @@
+import type { RequestContextData } from '@api-types';
+import type { Money } from '@commercetools/platform-sdk';
+import { SessionAuthentication } from '@security';
+
+export function getGiftCardPlannedAmountFromContext(
+  context: RequestContextData,
+): Money | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().giftCardPlannedAmount;
+  }
+}
+
+export function getCtSessionIdFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getCredentials();
+  }
+}
+
+export function getCartIdFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().cartId;
+  }
+}
+
+export function getAllowedPaymentMethodsFromContext(
+  context: RequestContextData,
+): string[] | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().allowedPaymentMethods;
+  }
+}
+
+/**
+ * @deprecated use getCheckoutTransactionItemIdFromContext instead
+ * @param context
+ * @returns
+ */
+export function getPaymentInterfaceFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().paymentInterface;
+  }
+}
+
+export function getCheckoutTransactionItemIdFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().checkoutTransactionItemId;
+  }
+}
+
+export function getProcessorUrlFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().processorUrl;
+  }
+}
+
+export function getMerchantReturnUrlFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().merchantReturnUrl;
+  }
+}
+
+export function getFutureOrderNumberFromContext(
+  context: RequestContextData,
+): string | undefined {
+  const authentication = context.authentication;
+  if (authentication && authentication instanceof SessionAuthentication) {
+    return authentication?.getPrincipal().futureOrderNumber;
+  }
+}

package/src/api/context/request-context.provider.ts

@@ -0,0 +1,27 @@
+import type { ContextProvider, RequestContextData } from '@api-types';
+
+/**
+ * ContextProvider is a class that provides a way to access and update the context data.
+ */
+export class RequestContextProvider
+  implements ContextProvider<RequestContextData>
+{
+  private getContextFn: () => RequestContextData;
+  private updateContextFn: (ctx: Partial<RequestContextData>) => void;
+
+  constructor(opts: {
+    getContextFn: () => RequestContextData;
+    updateContextFn: (ctx: Partial<RequestContextData>) => void;
+  }) {
+    this.getContextFn = opts.getContextFn;
+    this.updateContextFn = opts.updateContextFn;
+  }
+
+  getContextData(): RequestContextData {
+    return this.getContextFn();
+  }
+
+  updateContextData(ctx: Partial<RequestContextData>) {
+    this.updateContextFn(ctx);
+  }
+}

package/src/api/context/types/request-context.type.ts

@@ -0,0 +1,18 @@
+import type { Authentication } from '@security-types';
+
+/**
+ * Context provider interface
+ */
+export interface ContextProvider<T> {
+  getContextData(): T;
+  updateContextData(ctx: Partial<T>): void;
+}
+
+/**
+ * Request context data
+ */
+export type RequestContextData = {
+  correlationId: string;
+  requestId: string;
+  authentication?: Authentication;
+};