@notabene/javascript-sdk 2.14.1 → 2.14.2-next.2

package/src/responseTransformer/mappers.ts

@@ -7,18 +7,26 @@ import type {
 } from '@notabene/javascript-sdk/src/ivms/types';
 import type { Agent } from '@taprsvp/types';
 import {
+  Deposit,
   PersonType,
   type IVMS101,
   type V1Transaction,
   type Withdrawal,
 } from '../types';
 import type {
-  ResponseToTxRequestConfig,
+  ResponseToIVMS101RequestConfig,
+  ResponseToTxCreateRequestConfig,
   TransactionCreateRequest,
   TransactionCreateRequestV2,
   TransactionIVMS101Request,
 } from './types';
-import { convertPersonToV2, getPartyId } from './utils';
+import {
+  convertPersonToV2,
+  getCaip10ChainPrefix,
+  getPartyId,
+  isDeposit,
+  isWithdrawal,
+} from './utils';
 
 // Constants
 const DEFAULT_GEOGRAPHIC_ADDRESS = [
@@ -227,16 +235,28 @@ export function mapToV1CreateRequest(
 }
 
 export function mapToTransactCreateRequest(
-  withdrawal: Withdrawal,
+  transaction: Withdrawal | Deposit,
   payload: V1Transaction,
-  config: Omit<ResponseToTxRequestConfig, 'originator'> = {},
+  config: ResponseToTxCreateRequestConfig = {},
 ): TransactionCreateRequestV2 {
+  // For withdrawals: customer sends to counterparty
+  // For deposits: counterparty sends to customer
+  const isWithdrawalTx = isWithdrawal(transaction);
+  const originatorParty = isWithdrawalTx
+    ? transaction.customer
+    : transaction.counterparty;
+  const beneficiaryParty = isWithdrawalTx
+    ? transaction.counterparty
+    : transaction.customer;
+
   const originatorId =
-    config?.originatorId || getPartyId('originator', withdrawal.customer);
+    config?.originatorId || getPartyId('originator', originatorParty);
   const beneficiaryId =
-    config?.beneficiaryId || getPartyId('beneficiary', withdrawal.counterparty);
+    config?.beneficiaryId || getPartyId('beneficiary', beneficiaryParty);
   const referenceId =
-    config?.referenceId || Math.random().toString(36).substring(2, 15);
+    config?.referenceId ||
+    payload.transactionId ||
+    Math.random().toString(36).substring(2, 15);
   const agents: Agent[] = [];
 
   if (payload.originatorVASPdid) {
@@ -255,47 +275,89 @@ export function mapToTransactCreateRequest(
     });
   }
 
-  if (withdrawal.destination && withdrawal?.account?.did) {
+  if (isWithdrawal(transaction) && transaction?.account?.did) {
     agents.push({
-      '@id': withdrawal.account.did,
+      '@id': transaction.account.did,
       for: payload.beneficiaryVASPdid || beneficiaryId,
       role: 'SettlementAddress',
     });
   }
 
+  if (isDeposit(transaction) && transaction?.account) {
+    if (transaction.account.did) {
+      agents.push({
+        '@id': transaction.account.did,
+        for: payload.originatorVASPdid || originatorId,
+        role: 'SourceAddress',
+      });
+    }
+
+    if (config.settlementAddress && transaction.account.caip10) {
+      const chainPrefix = getCaip10ChainPrefix(transaction.account.caip10);
+      agents.push({
+        '@id': `did:pkh:${chainPrefix}:${config.settlementAddress}`,
+        for: payload.beneficiaryVASPdid || beneficiaryId,
+        role: 'SettlementAddress',
+      });
+    }
+  }
+
   return {
     originator: { '@id': originatorId },
     beneficiary: { '@id': beneficiaryId },
-    asset: withdrawal.asset,
-    amount: withdrawal.amountDecimal?.toString() || payload.transactionAmount,
+    asset: transaction.asset,
+    amount: transaction.amountDecimal?.toString() || payload.transactionAmount,
     agents,
     ref: referenceId,
   };
 }
 
 export function mapToAppendPiiRequest(
-  withdrawal: Withdrawal,
+  transaction: Withdrawal | Deposit,
   ivms101: IVMS101,
-  config: ResponseToTxRequestConfig = {},
+  config: ResponseToIVMS101RequestConfig = {},
 ): TransactionIVMS101Request {
-  const beneficiaryId =
-    config.beneficiaryId || getPartyId('beneficiary', withdrawal.counterparty);
-
-  const beneficiaryPersons =
-    // If counterparty type is SELF, reuse originator data for beneficiary
-    withdrawal.counterparty?.type === PersonType.SELF && config.originator
-      ? config.originator.originatorPerson
-      : // Convert all beneficiary persons from V1 to V2 format
-        ivms101.beneficiary?.beneficiaryPersons?.map((person) =>
-          convertPersonToV2(person, beneficiaryId),
+  if (isWithdrawal(transaction)) {
+    const beneficiaryId =
+      config.beneficiaryId ||
+      getPartyId('beneficiary', transaction.counterparty);
+
+    const beneficiaryPersons =
+      // If counterparty type is SELF, reuse originator data for beneficiary
+      transaction.counterparty?.type === PersonType.SELF && config.originator
+        ? config.originator.originatorPerson
+        : // Convert all beneficiary persons from V1 to V2 format
+          ivms101.beneficiary?.beneficiaryPersons?.map((person) =>
+            convertPersonToV2(person, beneficiaryId),
+          ) || [];
+
+    return {
+      ivms101: {
+        originator: config.originator,
+        beneficiary: {
+          beneficiaryPerson: beneficiaryPersons,
+        },
+      },
+    };
+  }
+
+  const originatorId =
+    config.originatorId || getPartyId('originator', transaction.counterparty);
+
+  const originatorPersons =
+    transaction.counterparty?.type === PersonType.SELF && config.beneficiary
+      ? config.beneficiary.beneficiaryPerson
+      : // Convert all originator persons from V1 to V2 format
+        ivms101.originator?.originatorPersons?.map((person) =>
+          convertPersonToV2(person, originatorId),
         ) || [];
 
   return {
     ivms101: {
-      originator: config.originator,
-      beneficiary: {
-        beneficiaryPerson: beneficiaryPersons,
+      originator: {
+        originatorPerson: originatorPersons,
       },
+      beneficiary: config.beneficiary,
     },
   };
 }

package/src/responseTransformer/transformer.ts

@@ -1,5 +1,7 @@
 import { decodeJwt } from 'jose';
 import {
+  Deposit,
+  DID,
   PersonType,
   type OwnershipProof,
   type TransactionResponse,
@@ -12,42 +14,65 @@ import {
 } from './mappers';
 import type {
   DelegateToken,
+  ResponseToIVMS101RequestConfig,
+  ResponseToTxCreateRequestConfig,
   ResponseToTxRequestConfig,
   TransactionCreateRequest,
   TransactionCreateRequestV2,
   TransactionIVMS101Request,
 } from './types';
+import { isDeposit, isWithdrawal } from './utils';
 
 /**
- * Fills in missing config values by extracting them from the delegate token and withdrawal data
+ * Fills in missing config values by extracting them from the delegate token and transaction data
  * @internal
  */
-function enrichConfig(
+export function enrichConfig(
   config: ResponseToTxRequestConfig,
   delegateToken: string,
-  withdrawal: Withdrawal,
+  transaction: Withdrawal | Deposit,
 ): ResponseToTxRequestConfig {
   const enrichedConfig = { ...config };
 
-  // Extract originatorId from delegate token if not provided
-  if (!enrichedConfig.originatorId) {
-    try {
-      const tokenPayload = decodeJwt<DelegateToken>(delegateToken);
-      if (tokenPayload?.sub) {
-        enrichedConfig.originatorId = tokenPayload.sub;
+  // Extract customer ID from delegate token
+  // For withdrawals: customer is originator, for deposits: customer is beneficiary
+  let customerIdFromToken: DID | undefined;
+  try {
+    const tokenPayload = decodeJwt<DelegateToken>(delegateToken);
+    customerIdFromToken = tokenPayload?.sub;
+  } catch {
+    // If decoding fails, customerIdFromToken remains undefined
+  }
+
+  if (isWithdrawal(transaction)) {
+    // Withdrawal: customer sends to counterparty
+    if (!enrichedConfig.originatorId && customerIdFromToken) {
+      enrichedConfig.originatorId = customerIdFromToken;
+    }
+
+    if (!enrichedConfig.beneficiaryId) {
+      if (transaction.counterparty?.type === PersonType.SELF) {
+        enrichedConfig.beneficiaryId = enrichedConfig.originatorId;
+      } else if (transaction.destination) {
+        // Generate beneficiaryId from destination if not provided.
+        // TODO: Replace with proper DID key identifier creation
+        enrichedConfig.beneficiaryId = `did:key:${transaction.destination}`;
       }
-    } catch {
-      // If decoding fails, originatorId remains undefined
     }
-  }
+  } else if (isDeposit(transaction)) {
+    // Deposit: counterparty sends to customer
+    if (!enrichedConfig.beneficiaryId && customerIdFromToken) {
+      enrichedConfig.beneficiaryId = customerIdFromToken;
+    }
 
-  if (!enrichedConfig.beneficiaryId) {
-    if (withdrawal.counterparty?.type === PersonType.SELF) {
-      enrichedConfig.beneficiaryId = enrichedConfig.originatorId;
-    } else if (withdrawal.destination) {
-      // Generate beneficiaryId from destination if not provided.
-      // TODO: Replace with proper DID key identifier creation
-      enrichedConfig.beneficiaryId = `did:key:${withdrawal.destination}`;
+    if (!enrichedConfig.originatorId) {
+      if (transaction.counterparty?.type === PersonType.SELF) {
+        enrichedConfig.originatorId = enrichedConfig.beneficiaryId;
+      } else if (transaction.source) {
+        // Generate originatorId from source if not provided.
+        // TODO: Replace with proper DID key identifier creation
+        enrichedConfig.originatorId = `did:key:${transaction.source}`;
+      }
     }
   }
 
@@ -115,51 +140,51 @@ export function componentResponseToV1TxCreateRequest(
  * which is useful for V2 workflows where you need to create a transaction first,
  * then append IVMS101 data to it, and finally confirm the relationship.
  *
+ * ## IVMS101 Config by Transaction Type
+ *
+ * The `originator` and `beneficiary` config options provide the customer's PII data.
+ * Which one to use depends on the transaction type:
+ *
+ * - **Withdrawals**: Pass `originator` - the customer is sending funds (customer = originator)
+ * - **Deposits**: Pass `beneficiary` - the customer is receiving funds (customer = beneficiary)
+ *
+ * For self-transfers, the provided data is automatically reused for both parties.
+ *
  * @param response - The response from the Notabene Embedded Component
- * @param delegateToken - The JWT delegate token for extracting the originator ID
+ * @param delegateToken - The JWT delegate token for extracting the customer ID
  * @param config - Optional configuration for IDs and reference
- * @param config.originatorId - Optional originator ID (auto-extracted from delegateToken if not provided)
- * @param config.beneficiaryId - Optional beneficiary ID (auto-generated if not provided)
+ * @param config.originatorId - Optional originator ID (auto-extracted from delegateToken for withdrawals)
+ * @param config.beneficiaryId - Optional beneficiary ID (auto-extracted from delegateToken for deposits)
  * @param config.referenceId - Optional reference ID (auto-generated if not provided)
- * @param config.originator - Optional originator data in V2 format
+ * @param config.originator - Customer's IVMS101 data for withdrawals (customer is the sender)
+ * @param config.beneficiary - Customer's IVMS101 data for deposits (customer is the receiver)
  * @returns Object with `createTx`, `ivms101`, and optional `confirmRelationship` properties containing the respective request bodies
  *
  * @example
  * ```typescript
  * import { componentResponseToTxRequests } from '$lib/notabene-tx-transformer';
  *
+ * // For withdrawals: pass originator (customer is sending)
  * withdrawal.on('complete', async (result) => {
- *   const { createTx, ivms101, confirmRelationship } = componentResponseToTxRequests(
+ *   const { createTx, ivms101 } = componentResponseToTxRequests(
  *     result.response,
- *     session.user.token,
- *     { originator: originatorData }
+ *     delegateToken,
+ *     { originator: customerIvmsData }
  *   );
+ * });
  *
- *   // First, create the transaction
- *   const txResponse = await fetch('/entity/${vaspDid}/tx', {
- *     method: 'POST',
- *     body: JSON.stringify(createTx)
- *   });
- *
- *   // Then, append IVMS101 data
- *   const txId = txResponse.transfer['@id'];
- *   await fetch(`/entity/${vaspDid}/tx/${txId}/append`, {
- *     method: 'POST',
- *     body: JSON.stringify(ivms101)
- *   });
- *
- *   // Finally, confirm relationship
- *   if (confirmRelationship) {
- *   await fetch(`/entity/${vaspDid}/relationship?to=${to}&from=${from}`, {
- *       method: 'PATCH',
- *       body: JSON.stringify({ proof: confirmRelationship.proof })
- *     });
- *   }
+ * // For deposits: pass beneficiary (customer is receiving)
+ * deposit.on('complete', async (result) => {
+ *   const { createTx, ivms101 } = componentResponseToTxRequests(
+ *     result.response,
+ *     delegateToken,
+ *     { beneficiary: customerIvmsData }
+ *   );
  * });
  * ```
  */
 export function componentResponseToTxRequests(
-  response: TransactionResponse<Withdrawal>,
+  response: TransactionResponse<Withdrawal | Deposit>,
   delegateToken: string,
   config: ResponseToTxRequestConfig = {},
 ): {
@@ -169,17 +194,21 @@ export function componentResponseToTxRequests(
     proof: OwnershipProof;
   };
 } {
-  if (!response.txCreate || !response.ivms101) {
+  const { value, txCreate, txUpdate, ivms101, proof } = response;
+
+  // For withdrawals: use txCreate, for deposits: use txUpdate
+  const txPayload = isWithdrawal(value) ? txCreate : txUpdate;
+
+  if (!txPayload || !ivms101) {
     throw new Error(
-      'Invalid response: missing required txCreate or ivms101 data',
+      'Invalid response: missing required txCreate/txUpdate or ivms101 data',
     );
   }
 
-  const { value, txCreate, ivms101, proof } = response;
   const enrichedConfig = enrichConfig(config, delegateToken, value);
 
   return {
-    createTx: mapToTransactCreateRequest(value, txCreate, enrichedConfig),
+    createTx: mapToTransactCreateRequest(value, txPayload, enrichedConfig),
     ivms101: mapToAppendPiiRequest(value, ivms101, enrichedConfig),
     ...(proof && { confirmRelationship: { proof } }),
   };
@@ -200,9 +229,11 @@ export function componentResponseToTxRequests(
  * ```typescript
  * import { componentResponseToTxCreateRequest } from '$lib/notabene-tx-transformer';
  *
- * withdrawal.on('complete', async (result) => {
+ * // Works with both withdrawal and deposit responses
+ * transaction.on('complete', async (result) => {
  *   const requestBody = componentResponseToTxCreateRequest(
  *     result.response,
+ *     delegateToken,
  *     {
  *       originatorId: 'mailto:user@example.com',
  *       beneficiaryId: 'urn:beneficiary:recipient',
@@ -218,54 +249,71 @@ export function componentResponseToTxRequests(
  * ```
  */
 export function componentResponseToTxCreateRequest(
-  response: TransactionResponse<Withdrawal>,
+  response: TransactionResponse<Withdrawal | Deposit>,
   delegateToken: string,
-  config: Omit<ResponseToTxRequestConfig, 'originator'> = {},
+  config: ResponseToTxCreateRequestConfig = {},
 ) {
-  if (!response.txCreate || !response.ivms101) {
+  const { value, txCreate, txUpdate } = response;
+
+  // For withdrawals: use txCreate, for deposits: use txUpdate
+  const txPayload = isWithdrawal(value) ? txCreate : txUpdate;
+
+  if (!txPayload || !response.ivms101) {
     throw new Error(
-      'Invalid response: missing required txCreate or ivms101 data',
+      'Invalid response: missing required txCreate/txUpdate or ivms101 data',
     );
   }
 
-  const { value, txCreate } = response;
   const enrichedConfig = enrichConfig(config, delegateToken, value);
 
-  return mapToTransactCreateRequest(value, txCreate, enrichedConfig);
+  return mapToTransactCreateRequest(value, txPayload, enrichedConfig);
 }
 
 /**
  * Transforms a Notabene component response to IVMS101 format
  *
+ * ## IVMS101 Config by Transaction Type
+ *
+ * The `originator` and `beneficiary` config options provide the customer's PII data.
+ * Which one to use depends on the transaction type:
+ *
+ * - **Withdrawals**: Pass `originator` - the customer is sending funds (customer = originator)
+ * - **Deposits**: Pass `beneficiary` - the customer is receiving funds (customer = beneficiary)
+ *
+ * For self-transfers, the provided data is automatically reused for both parties.
+ *
  * @param response - The response from the Notabene Embedded Component
- * @param delegateToken - The JWT delegate token for extracting the originator ID
+ * @param delegateToken - The JWT delegate token for extracting the customer ID
  * @param config - Configuration object with optional IDs
- * @param config.originatorId - Optional originator ID (auto-extracted from delegateToken if not provided)
- * @param config.beneficiaryId - Optional beneficiary ID (auto-generated if not provided)
- * @param config.referenceId - Optional reference ID for the transaction
- * @param config.originator - Optional originator data in V2 format
+ * @param config.originatorId - Optional originator ID (auto-extracted from delegateToken for withdrawals)
+ * @param config.beneficiaryId - Optional beneficiary ID (auto-extracted from delegateToken for deposits)
+ * @param config.originator - Customer's IVMS101 data for withdrawals (customer is the sender)
+ * @param config.beneficiary - Customer's IVMS101 data for deposits (customer is the receiver)
  * @returns The transformed request body in IVMS101 format
  *
  * @example
  * ```typescript
  * import { componentResponseToIVMS101 } from '$lib/notabene-tx-transformer';
  *
- * const requestBody = componentResponseToIVMS101(
- *   result.response,
- *   session.user.token,
- *   { originator: myOriginatorData }
+ * // For withdrawals: pass originator (customer is sending)
+ * const withdrawalIvms = componentResponseToIVMS101(
+ *   withdrawalResponse,
+ *   delegateToken,
+ *   { originator: customerIvmsData }
  * );
  *
- * await fetch('/entity/${vaspDid}/tx/${txId}/append', {
- *   method: 'POST',
- *   body: JSON.stringify(requestBody)
- * });
+ * // For deposits: pass beneficiary (customer is receiving)
+ * const depositIvms = componentResponseToIVMS101(
+ *   depositResponse,
+ *   delegateToken,
+ *   { beneficiary: customerIvmsData }
+ * );
  * ```
  */
 export function componentResponseToIVMS101(
-  response: TransactionResponse<Withdrawal>,
+  response: TransactionResponse<Withdrawal | Deposit>,
   delegateToken: string,
-  config: ResponseToTxRequestConfig = {},
+  config: ResponseToIVMS101RequestConfig = {},
 ) {
   if (!response.ivms101) {
     throw new Error('Invalid response: missing required ivms101 data');

package/src/responseTransformer/types.ts

@@ -14,13 +14,24 @@ export interface DelegateToken {
   iat?: number;
 }
 
-export interface ResponseToTxRequestConfig {
+interface BaseRequestConfig {
   originatorId?: DID;
   beneficiaryId?: DID;
+}
+
+export interface ResponseToTxCreateRequestConfig extends BaseRequestConfig {
   referenceId?: string;
+  settlementAddress?: string;
+}
+
+export interface ResponseToIVMS101RequestConfig extends BaseRequestConfig {
   originator?: OriginatorV2;
+  beneficiary?: BeneficiaryV2;
 }
 
+export type ResponseToTxRequestConfig = ResponseToTxCreateRequestConfig &
+  ResponseToIVMS101RequestConfig;
+
 export interface TransactionCreateRequest {
   transactionAsset: any;
   transactionAmount: string;

package/src/responseTransformer/utils.ts

@@ -2,8 +2,21 @@ import type {
   NaturalPersonName,
   Person,
 } from '@notabene/javascript-sdk/src/ivms/types';
-import type { DID } from '@taprsvp/types';
+import { CAIP10Schema, type DID } from '@taprsvp/types';
 import type { NaturalPersonNameV2, PersonV2 } from '../ivms';
+import { Deposit, Withdrawal } from '../types';
+
+export function isDeposit(
+  transaction: Withdrawal | Deposit,
+): transaction is Deposit {
+  return 'source' in transaction && transaction.source !== undefined;
+}
+
+export function isWithdrawal(
+  transaction: Withdrawal | Deposit,
+): transaction is Withdrawal {
+  return !isDeposit(transaction);
+}
 
 /**
  * Generates a backup DID identifier for a party
@@ -59,3 +72,26 @@ export function convertPersonToV2(
     accountNumber: [accountNumber],
   };
 }
+
+/**
+ * Extracts the chain prefix ({namespace}:{chainId}) from a CAIP-10 address
+ * @param caip10Address - An address in the format {namespace}:{chainId}:{address}
+ * @returns The chain prefix (e.g., eip155:1)
+ * @throws Error if the address is not in valid CAIP-10 format
+ *
+ * @example
+ * getCaip10ChainPrefix('eip155:1:0x123...') // returns 'eip155:1'
+ * getCaip10ChainPrefix('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7kfAoE5o...') // returns 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
+ */
+export function getCaip10ChainPrefix(caip10Address: string): string {
+  const result = CAIP10Schema.safeParse(caip10Address);
+  if (!result.success) {
+    throw new Error(
+      `Invalid CAIP-10 format: "${caip10Address}". Expected format: {namespace}:{chainId}:{address}`,
+    );
+  }
+
+  // Extract chain (namespace:chainId) by removing the last segment (address)
+  const lastColonIndex = caip10Address.lastIndexOf(':');
+  return caip10Address.slice(0, lastColonIndex);
+}

package/src/types.ts

@@ -237,8 +237,11 @@ export type ISOCurrency = string;
  */
 export type Theme = {
   mode: 'light' | 'dark'; // Defaults to 'light'
+  backgroundColor?: string;
   primaryColor?: string;
+  primaryForeground?: string;
   secondaryColor?: string;
+  secondaryForeground?: string;
   fontFamily?: string;
   logo?: string;
 };
@@ -491,7 +494,7 @@ export type LegalPersonFields = Partial<{
  * @public
  */
 type OriginatorFields = {
-  source?: Source | Source[];
+  source: Source | Source[];
 };
 
 /**
@@ -499,7 +502,7 @@ type OriginatorFields = {
  * @public
  */
 type BeneficiaryFields = {
-  destination?: Destination;
+  destination: Destination;
 };
 
 /**
@@ -889,6 +892,7 @@ export interface TransactionOptions {
   hide?: ValidationSections[]; // You can hide a specific section of the component by listing it here
   counterpartyAssist?: CounterpartyAssistConfig;
   autoSubmit?: boolean; // Defaults to false
+  supportUrl?: string;
 }
 /**
  * Component Message Type enum representing different message types that can be sent

package/src/utils/arbitraries.ts

@@ -250,5 +250,5 @@ export const arbitraryDeposit = (): fc.Arbitrary<Deposit> =>
     asset: arbitraryTransactionAsset(),
     amountDecimal: fc.float({ min: 0, max: 1e6 }),
     origin: fc.oneof(arbitraryBlockchainAddress(), arbitraryCAIP10()),
-    destination: fc.oneof(arbitraryBlockchainAddress(), arbitraryCAIP10()),
+    source: fc.oneof(arbitraryBlockchainAddress(), arbitraryCAIP10()),
   });