@notabene/javascript-sdk 2.13.0 → 2.14.0

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",
@@ -32,7 +32,7 @@
       "import": "./dist/esm/notabene.js",
       "require": "./dist/cjs/notabene.cjs"
     },
-    "./src/ivms/types": "./src/ivms/types.ts"
+    "./src/ivms/types": "./src/ivms/index.ts"
   },
   "browserslist": "> 0.5%, last 2 versions, not dead",
   "publishConfig": {
@@ -104,5 +104,9 @@
     "extends": [
       "@commitlint/config-conventional"
     ]
+  },
+  "dependencies": {
+    "@taprsvp/types": "^1.13.0",
+    "jose": "^6.1.0"
   }
 }

package/src/ivms/index.ts

@@ -0,0 +1,5 @@
+// Re-export all types from types.ts
+export * from './types';
+
+// Re-export all V2 types
+export * from './v2Types';

package/src/ivms/v2Types.ts

@@ -0,0 +1,35 @@
+import {
+  NaturalPerson,
+  NaturalPersonName,
+  NaturalPersonNameTypeCode,
+  Person,
+} from './types';
+
+export type OriginatorV2 = {
+  originatorPerson: PersonV2[];
+  customerIdentification?: string;
+};
+
+export type BeneficiaryV2 = {
+  beneficiaryPerson: PersonV2[];
+  customerIdentification?: string;
+};
+
+export type NaturalPersonNameIDV2 = {
+  primaryIdentifier?: string;
+  secondaryIdentifier?: string;
+  naturalPersonNameIdentifierType?: NaturalPersonNameTypeCode;
+};
+
+export type NaturalPersonNameV2 = Omit<NaturalPersonName, 'nameIdentifier'> & {
+  nameIdentifier?: NaturalPersonNameIDV2[];
+};
+
+export type NaturalPersonV2 = Omit<NaturalPerson, 'name'> & {
+  name: NaturalPersonNameV2;
+};
+
+export type PersonV2 = Omit<Person, 'naturalPerson'> & {
+  naturalPerson?: NaturalPersonV2;
+  accountNumber?: string[];
+};

package/src/notabene.ts

@@ -83,6 +83,18 @@ import { type MessageCallback } from './utils/MessageEventManager';
 import { decodeFragmentToObject, encodeObjectToFragment } from './utils/urls';
 // Must be exported for React Native SDK to use
 export { default as EmbeddedComponent } from './components/EmbeddedComponent';
+export {
+  componentResponseToIVMS101,
+  componentResponseToTxCreateRequest,
+  componentResponseToTxRequests,
+  componentResponseToV1TxCreateRequest,
+} from './responseTransformer';
+export type {
+  ResponseToTxRequestConfig,
+  TransactionCreateRequest,
+  TransactionCreateRequestV2,
+  TransactionIVMS101Request,
+} from './responseTransformer';
 export {
   ConnectionManager,
   getRefreshResult,

package/src/responseTransformer/README.md

@@ -0,0 +1,164 @@
+# Notabene TX Transformer
+
+A utility module to transform Notabene component responses into API request bodies for Version 1 and Version 2 APIs.
+
+## Usage
+
+### Version 2 API - Complete Workflow
+
+```typescript
+import { componentResponseToTxRequests, EXAMPLE_ORIGINATOR_V2 } from '$lib/notabene-tx-transformer';
+
+withdrawal.on('complete', async (result) => {
+	// Generate all request bodies in one call
+	const { createTx, appendPii, confirmRelationship } = componentResponseToTxRequests(
+		result.response,
+		delegateToken,
+		{ originator: EXAMPLE_ORIGINATOR_V2 }
+	);
+
+	// 1. Create transaction
+	const txResponse = await fetch(`/entity/${vaspDid}/tx`, {
+		method: 'POST',
+		body: JSON.stringify(createTx)
+	});
+
+	const txId = txResponse.transfer['@id'];
+
+	// 2. Append PII
+	await fetch(`/entity/${vaspDid}/tx/${txId}/append`, {
+		method: 'POST',
+		body: JSON.stringify(appendPii)
+	});
+
+	// 3. Confirm relationship (if proof exists)
+	if (confirmRelationship) {
+		await fetch(`/entity/${vaspDid}/relationship?to=...&from=...`, {
+			method: 'PATCH',
+			body: JSON.stringify(confirmRelationship)
+		});
+	}
+});
+```
+
+### Version 2 API - Individual Functions
+
+```typescript
+import {
+	componentResponseToTxCreateRequest,
+	componentResponseToIVMS101
+} from '$lib/notabene-tx-transformer';
+
+// Create transaction only
+const createBody = componentResponseToTxCreateRequest(response, delegateToken);
+
+// IVMS101 data only
+const ivms101Body = componentResponseToIVMS101(response, delegateToken, {
+	originator: EXAMPLE_ORIGINATOR_V2
+});
+```
+
+### Version 1 API (Legacy)
+
+```typescript
+import { componentResponseToV1TxCreateRequest } from '$lib/notabene-tx-transformer';
+
+withdrawal.on('complete', async (result) => {
+	const requestBody = componentResponseToV1TxCreateRequest(result.response);
+
+	// Send to your Version 1 API
+	await fetch(`${apiUrlV1}/entity/${did}/tx`, {
+		method: 'POST',
+		headers: {
+			'Content-Type': 'application/json',
+			Authorization: `Bearer ${token}`
+		},
+		body: JSON.stringify(requestBody)
+	});
+});
+```
+
+## API
+
+### `componentResponseToTxRequests(response, delegateToken, config?)`
+
+Transforms a Notabene component response into all V2 request bodies (createTx, appendPii, and optionally confirmRelationship).
+
+**Parameters:**
+
+- `response`: Response from the Notabene TX Create component
+- `delegateToken`: JWT delegate token for extracting the originator ID
+- `config`: Optional `ResponseToTxRequestConfig` object
+  - `config.originatorId`: Auto-extracted from delegateToken if not provided
+  - `config.beneficiaryId`: Auto-generated from destination if not provided
+  - `config.referenceId`: Optional reference ID for the transaction
+  - `config.originator`: Optional originator information in V2 format for PII append
+
+**Returns:** Object with `createTx`, `appendPii`, and optionally `confirmRelationship`
+
+### `componentResponseToTxCreateRequest(response, delegateToken, config?)`
+
+Transforms a Notabene component response to a V2 transaction create request.
+
+**Parameters:**
+
+- `response`: Response from the Notabene TX Create component
+- `delegateToken`: JWT delegate token for extracting the originator ID
+- `config`: Optional configuration object
+  - `config.originatorId`: Auto-extracted from delegateToken if not provided
+  - `config.beneficiaryId`: Auto-generated from destination if not provided
+  - `config.referenceId`: Optional reference ID for the transaction
+
+**Returns:** Transaction create request body
+
+### `componentResponseToIVMS101(response, delegateToken, config?)`
+
+Transforms a Notabene component response to IVMS101 format.
+
+**Parameters:**
+
+- `response`: Response from the Notabene TX Create component
+- `delegateToken`: JWT delegate token for extracting the originator ID
+- `config`: Optional `ResponseToTxRequestConfig` object
+  - `config.originatorId`: Auto-extracted from delegateToken if not provided
+  - `config.beneficiaryId`: Auto-generated from destination if not provided
+  - `config.referenceId`: Optional reference ID for the transaction
+  - `config.originator`: Optional originator information in V2 format
+
+**Returns:** IVMS101 formatted request body
+
+### `componentResponseToV1TxCreateRequest(response)`
+
+Transforms a Notabene component response to a V1 transaction create request.
+
+**Parameters:**
+
+- `response`: Response from the Notabene TX Create component
+
+**Returns:** V1 transaction create request body
+
+## Module Structure
+
+```
+notabene-tx-transformer/
+├── index.ts        # Main exports
+├── transformer.ts  # Main transformation function
+├── mappers.ts      # V1 and V2 mapping logic
+├── types.ts        # Types not available in SDK
+├── utils.ts        # Utility functions (getPartyId)
+└── README.md       # This file
+```
+
+## Configuration
+
+All V2 functions accept an optional `ResponseToTxRequestConfig` parameter with auto-enrichment:
+
+- **`originatorId`**: Auto-extracted from `delegateToken.sub` if not provided
+- **`beneficiaryId`**: Auto-generated as `did:key:${destination}` if not provided
+- **`referenceId`**: Optional transaction reference
+- **`originator`**: Optional originator information in V2 format (used in PII append requests)
+
+## Version Differences
+
+- **Version 1 (Legacy)**: Single-step transaction creation with embedded PII
+- **Version 2**: Multi-step workflow (create → append PII → confirm relationship)

package/src/responseTransformer/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Notabene TX Transformer
+ *
+ * A utility module to transform Notabene component responses into API request bodies.
+ */
+
+// Main export
+export {
+  componentResponseToIVMS101,
+  componentResponseToTxCreateRequest,
+  componentResponseToTxRequests,
+  componentResponseToV1TxCreateRequest,
+} from './transformer';
+
+// Type exports
+export {
+  type ResponseToTxRequestConfig,
+  type TransactionCreateRequest,
+  type TransactionCreateRequestV2, // rename to TransactCreateRequest?
+  type TransactionIVMS101Request,
+} from './types';

package/src/responseTransformer/mappers.ts

@@ -0,0 +1,293 @@
+import type {
+  Beneficiary,
+  NaturalPerson,
+  NaturalPersonName,
+  Originator,
+  Person,
+} from '@notabene/javascript-sdk/src/ivms/types';
+import type { Agent } from '@taprsvp/types';
+import type { IVMS101, V1Transaction, Withdrawal } from '../types';
+import type {
+  ResponseToTxRequestConfig,
+  TransactionCreateRequest,
+  TransactionCreateRequestV2,
+  TransactionIVMS101Request,
+} from './types';
+import { convertPersonToV2, getPartyId } from './utils';
+
+// Constants
+const DEFAULT_GEOGRAPHIC_ADDRESS = [
+  {
+    addressType: 'GEOG' as const,
+    addressLine: ['1234 Main Street'],
+    townName: 'Unknown',
+    country: 'US',
+  },
+];
+
+// Helper functions
+function parseName(fullName: string) {
+  const trimmedName = fullName.trim();
+  if (!trimmedName) {
+    return { primaryIdentifier: '', secondaryIdentifier: '' };
+  }
+
+  const parts = trimmedName.split(/\s+/);
+  const primaryIdentifier = parts[parts.length - 1];
+  const secondaryParts = parts.slice(0, -1);
+  const secondaryIdentifier =
+    secondaryParts.length > 0 ? secondaryParts.join(' ') : primaryIdentifier;
+
+  return { primaryIdentifier, secondaryIdentifier };
+}
+
+function copyIVMS(
+  type: 'originator' | 'beneficiary',
+  persons?: Person[],
+  accountNumber: string[] = ['1234567890'],
+): Originator | Beneficiary {
+  const updatedPersons = persons?.map((person) => {
+    const updatedPerson = { ...person };
+
+    if (updatedPerson.naturalPerson) {
+      updatedPerson.naturalPerson = {
+        ...updatedPerson.naturalPerson,
+        geographicAddress: DEFAULT_GEOGRAPHIC_ADDRESS,
+      };
+    }
+
+    if (updatedPerson.legalPerson) {
+      updatedPerson.legalPerson = {
+        ...updatedPerson.legalPerson,
+        geographicAddress: DEFAULT_GEOGRAPHIC_ADDRESS,
+      };
+    }
+
+    return updatedPerson;
+  });
+
+  return type === 'originator'
+    ? { originatorPersons: updatedPersons, accountNumber }
+    : { beneficiaryPersons: updatedPersons, accountNumber };
+}
+
+function hostIVMS(
+  type: 'originator' | 'beneficiary',
+  name = 'John Doe',
+): Originator | Beneficiary {
+  const { primaryIdentifier, secondaryIdentifier } = parseName(name);
+
+  const person: Person = {
+    naturalPerson: {
+      name: [
+        {
+          nameIdentifier: [
+            {
+              primaryIdentifier,
+              ...(secondaryIdentifier ? { secondaryIdentifier } : {}),
+              nameIdentifierType: 'LEGL',
+            },
+          ],
+        },
+      ] as any,
+      geographicAddress: DEFAULT_GEOGRAPHIC_ADDRESS,
+    },
+  };
+
+  return type === 'originator'
+    ? { originatorPersons: [person], accountNumber: ['1234567890'] }
+    : { beneficiaryPersons: [person], accountNumber: ['1234567890'] };
+}
+
+const wrapNameInArray = (naturalPerson: NaturalPerson): NaturalPerson => ({
+  ...naturalPerson,
+  // @ts-expect-error Preserving the original logic
+  name: naturalPerson.name
+    ? ([naturalPerson.name] as NaturalPersonName[])
+    : undefined,
+});
+
+const transformPerson = (person: Person): Person => ({
+  ...person,
+  naturalPerson: person.naturalPerson
+    ? wrapNameInArray(person.naturalPerson)
+    : undefined,
+});
+
+const transformIVMS101 = (
+  { beneficiary, originator }: IVMS101,
+  name?: string,
+  originatorEqualsBeneficiary?: boolean,
+  destination?: string,
+  operation?: 'withdrawal' | 'deposit',
+) => {
+  if (operation === 'withdrawal') {
+    const transformedBeneficiary = beneficiary && {
+      ...beneficiary,
+      ...(destination && { accountNumber: [destination] }),
+      beneficiaryPersons: beneficiary.beneficiaryPersons?.map(transformPerson),
+    };
+
+    if (
+      originatorEqualsBeneficiary &&
+      transformedBeneficiary?.beneficiaryPersons
+    ) {
+      const originator = copyIVMS(
+        'originator',
+        transformedBeneficiary?.beneficiaryPersons,
+      ) as Originator;
+
+      return {
+        beneficiary: {
+          accountNumber: originator.accountNumber,
+          beneficiaryPersons: originator.originatorPersons,
+        },
+        originator,
+      };
+    }
+
+    return {
+      beneficiary: transformedBeneficiary,
+      originator: hostIVMS('originator', name),
+    };
+  }
+
+  if (operation === 'deposit') {
+    const transformedOriginator = originator && {
+      ...(destination && { accountNumber: [destination] }),
+      originatorPersons: originator.originatorPersons?.map(transformPerson),
+    };
+
+    if (
+      originatorEqualsBeneficiary &&
+      transformedOriginator?.originatorPersons
+    ) {
+      const beneficiary = copyIVMS(
+        'beneficiary',
+        transformedOriginator?.originatorPersons,
+      ) as Beneficiary;
+
+      return {
+        originator: {
+          accountNumber: beneficiary.accountNumber,
+          originatorPersons: beneficiary.beneficiaryPersons,
+        },
+        beneficiary,
+      };
+    }
+
+    return {
+      originator: transformedOriginator,
+      beneficiary: hostIVMS('beneficiary', name),
+    };
+  }
+
+  throw new Error('Invalid operation type');
+};
+
+export function mapToV1CreateRequest(
+  withdrawal: Withdrawal,
+  payload: V1Transaction,
+  ivms101: IVMS101,
+): TransactionCreateRequest {
+  const { beneficiary, originator } = transformIVMS101(
+    ivms101,
+    withdrawal.customer?.name,
+    payload.originatorEqualsBeneficiary,
+    withdrawal.destination,
+    'withdrawal',
+  );
+
+  return {
+    transactionAsset: payload.transactionAsset,
+    transactionAmount: payload.transactionAmount,
+    beneficiaryDid: withdrawal.counterparty?.did,
+    originatorVASPdid: payload.originatorVASPdid,
+    ...(payload.beneficiaryVASPdid && !payload.beneficiaryProof
+      ? { beneficiaryVASPdid: payload.beneficiaryVASPdid }
+      : {}),
+    transactionBlockchainInfo: {
+      ...(originator?.accountNumber && { origin: originator.accountNumber[0] }),
+      ...(withdrawal.destination && { destination: withdrawal.destination }),
+    },
+    ...(payload.beneficiaryProof && {
+      beneficiaryProof: payload.beneficiaryProof,
+    }),
+    ...(beneficiary && { beneficiary }),
+    ...(originator && { originator }),
+    ...(payload.originatorEqualsBeneficiary && {
+      originatorEqualsBeneficiary: payload.originatorEqualsBeneficiary,
+    }),
+  };
+}
+
+export function mapToTransactCreateRequest(
+  withdrawal: Withdrawal,
+  payload: V1Transaction,
+  config: Omit<ResponseToTxRequestConfig, 'originator'> = {},
+): TransactionCreateRequestV2 {
+  const originatorId =
+    config?.originatorId || getPartyId('originator', withdrawal.customer);
+  const beneficiaryId =
+    config?.beneficiaryId || getPartyId('beneficiary', withdrawal.counterparty);
+  const referenceId =
+    config?.referenceId || Math.random().toString(36).substring(2, 15);
+  const agents: Agent[] = [];
+
+  if (payload.originatorVASPdid) {
+    agents.push({
+      '@id': payload.originatorVASPdid,
+      for: originatorId,
+      role: 'VASP',
+    });
+  }
+
+  if (payload.beneficiaryVASPdid) {
+    agents.push({
+      '@id': payload.beneficiaryVASPdid,
+      for: beneficiaryId,
+      role: 'VASP',
+    });
+  }
+
+  if (withdrawal.destination && withdrawal?.account?.did) {
+    agents.push({
+      '@id': withdrawal.account.did,
+      for: payload.beneficiaryVASPdid || beneficiaryId,
+      role: 'SettlementAddress',
+    });
+  }
+
+  return {
+    originator: { '@id': originatorId },
+    beneficiary: { '@id': beneficiaryId },
+    asset: withdrawal.asset,
+    amount: withdrawal.amountDecimal?.toString() || payload.transactionAmount,
+    agents,
+    ref: referenceId,
+  };
+}
+
+export function mapToAppendPiiRequest(
+  withdrawal: Withdrawal,
+  ivms101: IVMS101,
+  config: ResponseToTxRequestConfig = {},
+): TransactionIVMS101Request {
+  const beneficiaryId =
+    config.beneficiaryId || getPartyId('beneficiary', withdrawal.counterparty);
+
+  // Convert all beneficiary persons from V1 to V2 format
+  const beneficiaryPersons =
+    ivms101.beneficiary?.beneficiaryPersons?.map((person) =>
+      convertPersonToV2(person, beneficiaryId),
+    ) || [];
+
+  return {
+    ivms101: {
+      originator: config.originator,
+      beneficiary: {
+        beneficiaryPerson: beneficiaryPersons,
+      },
+    },
+  };
+}