@notabene/javascript-sdk 2.12.0 → 2.13.0-next.2

package/src/responseTransformer/transformer.ts

@@ -0,0 +1,278 @@
+import { decodeJwt } from 'jose';
+import {
+  PersonType,
+  type OwnershipProof,
+  type TransactionResponse,
+  type Withdrawal,
+} from '../types';
+import {
+  mapToAppendPiiRequest,
+  mapToTransactCreateRequest,
+  mapToV1CreateRequest,
+} from './mappers';
+import type {
+  DelegateToken,
+  ResponseToTxRequestConfig,
+  TransactionCreateRequest,
+  TransactionCreateRequestV2,
+  TransactionIVMS101Request,
+} from './types';
+
+/**
+ * Fills in missing config values by extracting them from the delegate token and withdrawal data
+ * @internal
+ */
+function enrichConfig(
+  config: ResponseToTxRequestConfig,
+  delegateToken: string,
+  withdrawal: Withdrawal,
+): 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;
+      }
+    } catch {
+      // If decoding fails, originatorId remains undefined
+    }
+  }
+
+  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}`;
+    }
+  }
+
+  return enrichedConfig;
+}
+
+/**
+ * Transforms a Notabene component response to a Version 1 API request body
+ *
+ * @param response - The response from the Notabene TX Create component
+ * @returns The transformed request body ready for the Version 1 API
+ *
+ * @example
+ * ```typescript
+ * import { componentResponseToV1TxCreateRequest } from '$lib/notabene-tx-transformer';
+ *
+ * withdrawal.on('complete', async (result) => {
+ *   const requestBody = componentResponseToV1TxCreateRequest(result.response);
+ *
+ *   await fetch(endpointUrl, {
+ *     method: 'POST',
+ *     body: JSON.stringify(requestBody)
+ *   });
+ * });
+ * ```
+ */
+export function componentResponseToV1TxCreateRequest(
+  response: TransactionResponse<Withdrawal>,
+): TransactionCreateRequest {
+  if (!response.txCreate || !response.ivms101) {
+    throw new Error(
+      'Invalid response: missing required txCreate or ivms101 data',
+    );
+  }
+
+  const { value, ivms101, proof, txCreate } = response;
+
+  // Build withdrawal object from response data for V1 API
+  const withdrawal: Withdrawal = {
+    destination: value?.destination || '',
+    counterparty: value?.counterparty || {},
+    agent: value?.agent,
+    account: value?.account,
+    proof,
+    asset:
+      value?.asset ||
+      (typeof txCreate.transactionAsset === 'string'
+        ? txCreate.transactionAsset
+        : txCreate.transactionAsset?.caip19) ||
+      '',
+    amountDecimal:
+      value?.amountDecimal ||
+      (txCreate.transactionAmount ? parseFloat(txCreate.transactionAmount) : 0),
+    customer: value?.customer,
+  } as Withdrawal;
+
+  return mapToV1CreateRequest(withdrawal, txCreate, ivms101 as any);
+}
+
+/**
+ * Transforms a Notabene component response into txCreate, IVMS101, and confirmRelationship request bodies
+ *
+ * This is a convenience function that generates the transaction creation request,
+ * the IVMS101 data, and optionally the relationship confirmation proof in a single call,
+ * 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.
+ *
+ * @param response - The response from the Notabene Embedded Component
+ * @param delegateToken - The JWT delegate token for extracting the originator 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.referenceId - Optional reference ID (auto-generated if not provided)
+ * @param config.originator - Optional originator data in V2 format
+ * @returns Object with `createTx`, `ivms101`, and optional `confirmRelationship` properties containing the respective request bodies
+ *
+ * @example
+ * ```typescript
+ * import { componentResponseToTxRequests } from '$lib/notabene-tx-transformer';
+ *
+ * withdrawal.on('complete', async (result) => {
+ *   const { createTx, ivms101, confirmRelationship } = componentResponseToTxRequests(
+ *     result.response,
+ *     session.user.token,
+ *     { originator: originatorData }
+ *   );
+ *
+ *   // 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 })
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export function componentResponseToTxRequests(
+  response: TransactionResponse<Withdrawal>,
+  delegateToken: string,
+  config: ResponseToTxRequestConfig = {},
+): {
+  createTx: TransactionCreateRequestV2;
+  ivms101: TransactionIVMS101Request;
+  confirmRelationship?: {
+    proof: OwnershipProof;
+  };
+} {
+  if (!response.txCreate || !response.ivms101) {
+    throw new Error(
+      'Invalid response: missing required txCreate or ivms101 data',
+    );
+  }
+
+  const { value, txCreate, ivms101, proof } = response;
+  const enrichedConfig = enrichConfig(config, delegateToken, value);
+
+  return {
+    createTx: mapToTransactCreateRequest(value, txCreate, enrichedConfig),
+    ivms101: mapToAppendPiiRequest(value, ivms101, enrichedConfig),
+    ...(proof && { confirmRelationship: { proof } }),
+  };
+}
+
+/**
+ * Transforms a Notabene component response to a Version 2 transaction create API request body
+ *
+ * @param response - The response from the Notabene Embedded Component
+ * @param delegateToken - The JWT delegate token for extracting the originator 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
+ * @returns The transformed request body ready for the Version 2 transaction create API
+ *
+ * @example
+ * ```typescript
+ * import { componentResponseToTxCreateRequest } from '$lib/notabene-tx-transformer';
+ *
+ * withdrawal.on('complete', async (result) => {
+ *   const requestBody = componentResponseToTxCreateRequest(
+ *     result.response,
+ *     {
+ *       originatorId: 'mailto:user@example.com',
+ *       beneficiaryId: 'urn:beneficiary:recipient',
+ *       referenceId: 'tx-12345'
+ *     }
+ *   );
+ *
+ *   await fetch('/entity/${vaspDid}/tx', {
+ *     method: 'POST',
+ *     body: JSON.stringify(requestBody)
+ *   });
+ * });
+ * ```
+ */
+export function componentResponseToTxCreateRequest(
+  response: TransactionResponse<Withdrawal>,
+  delegateToken: string,
+  config: Omit<ResponseToTxRequestConfig, 'originator'> = {},
+) {
+  if (!response.txCreate || !response.ivms101) {
+    throw new Error(
+      'Invalid response: missing required txCreate or ivms101 data',
+    );
+  }
+
+  const { value, txCreate } = response;
+  const enrichedConfig = enrichConfig(config, delegateToken, value);
+
+  return mapToTransactCreateRequest(value, txCreate, enrichedConfig);
+}
+
+/**
+ * Transforms a Notabene component response to IVMS101 format
+ *
+ * @param response - The response from the Notabene Embedded Component
+ * @param delegateToken - The JWT delegate token for extracting the originator 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
+ * @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 }
+ * );
+ *
+ * await fetch('/entity/${vaspDid}/tx/${txId}/append', {
+ *   method: 'POST',
+ *   body: JSON.stringify(requestBody)
+ * });
+ * ```
+ */
+export function componentResponseToIVMS101(
+  response: TransactionResponse<Withdrawal>,
+  delegateToken: string,
+  config: ResponseToTxRequestConfig = {},
+) {
+  if (!response.ivms101) {
+    throw new Error('Invalid response: missing required ivms101 data');
+  }
+
+  const { value, ivms101 } = response;
+  const enrichedConfig = enrichConfig(config, delegateToken, value);
+
+  return mapToAppendPiiRequest(value, ivms101, enrichedConfig);
+}

package/src/responseTransformer/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Types that are not available in @notabene/javascript-sdk
+ * These are specific to the API transformation logic
+ */
+
+import type { Agent, DID } from '@taprsvp/types';
+import type { BeneficiaryV2, OriginatorV2 } from '../ivms';
+
+export interface DelegateToken {
+  sub?: DID;
+  iss?: DID;
+  scope?: 'delegate';
+  exp?: number;
+  iat?: number;
+}
+
+export interface ResponseToTxRequestConfig {
+  originatorId?: DID;
+  beneficiaryId?: DID;
+  referenceId?: string;
+  originator?: OriginatorV2;
+}
+
+export interface TransactionCreateRequest {
+  transactionAsset: any;
+  transactionAmount: string;
+  beneficiaryDid?: string;
+  originatorVASPdid: string;
+  beneficiaryVASPdid?: string;
+  beneficiaryVASPname?: string;
+  beneficiaryVASPwebsite?: string;
+  transactionBlockchainInfo: {
+    origin?: string;
+    destination?: string;
+  };
+  beneficiaryProof?: any;
+  beneficiary?: any;
+  originator?: any;
+  originatorEqualsBeneficiary?: boolean;
+}
+
+export interface TransactionCreateRequestV2 {
+  originator: {
+    '@id': string;
+  };
+  beneficiary: {
+    '@id': string;
+  };
+  asset: string;
+  amount: string;
+  agents: Agent[];
+  ref: string;
+}
+
+export interface TransactionIVMS101Request {
+  ivms101: {
+    originator?: OriginatorV2;
+    beneficiary?: BeneficiaryV2;
+  };
+}

package/src/responseTransformer/utils.ts

@@ -0,0 +1,61 @@
+import type {
+  NaturalPersonName,
+  Person,
+} from '@notabene/javascript-sdk/src/ivms/types';
+import type { DID } from '@taprsvp/types';
+import type { NaturalPersonNameV2, PersonV2 } from '../ivms';
+
+/**
+ * Generates a backup DID identifier for a party
+ */
+export function getPartyId(
+  identifier: 'originator' | 'beneficiary',
+  party?: { email?: string; name?: string },
+): DID {
+  if (party?.email) {
+    return `did:email:${party.email}`;
+  }
+  if (party?.name) {
+    return `did:name:${encodeURIComponent(party.name.replace(/\s+/g, '-'))}`;
+  }
+  throw new Error(
+    `Unable to generate ${identifier} ID: missing required ${identifier} information`,
+  );
+}
+
+/**
+ * Converts NaturalPersonName from V1 format to V2 format
+ * Changes the nameIdentifierType field name to naturalPersonNameIdentifierType
+ */
+export function convertNaturalPersonNameToV2(
+  name: NaturalPersonName,
+): NaturalPersonNameV2 {
+  const { nameIdentifier, ...rest } = name;
+  return {
+    ...rest,
+    nameIdentifier: nameIdentifier?.map(({ nameIdentifierType, ...rest }) => ({
+      ...rest,
+      naturalPersonNameIdentifierType: nameIdentifierType,
+    })),
+  };
+}
+
+/**
+ * Converts a Person from V1 format to V2 format
+ * Applies deep conversion to natural person names and adds account number
+ */
+export function convertPersonToV2(
+  person: Person,
+  accountNumber: string,
+): PersonV2 {
+  return {
+    naturalPerson: person.naturalPerson
+      ? {
+          ...person.naturalPerson,
+          name: convertNaturalPersonNameToV2(person.naturalPerson.name),
+        }
+      : undefined,
+    legalPerson: person.legalPerson,
+    accountNumber: [accountNumber],
+  };
+}

package/src/types.ts

@@ -491,7 +491,7 @@ export type LegalPersonFields = Partial<{
  * @public
  */
 type OriginatorFields = {
-  source?: Source;
+  source?: Source | Source[];
 };
 
 /**
@@ -877,7 +877,6 @@ export interface TransactionOptions {
     microTransfer?: {
       destination: BlockchainAddress;
       amountSubunits: string;
-      timeout?: number; // Time to verify in seconds
     };
     fallbacks?: ProofTypes[];
     deminimis?: ThresholdOptions;
@@ -955,6 +954,18 @@ export enum ErrorIdentifierCode {
   TOKEN_INVALID = 'TOKEN_INVALID',
 }
 
+/**
+ * Identifier codes for warning messages
+ * @public
+ */
+export enum WarningIdentifierCode {
+  WALLET_ADDRESS_NOT_CONNECTED = 'WALLET_ADDRESS_NOT_CONNECTED',
+  WALLET_LOCKED = 'WALLET_LOCKED',
+  WALLET_UNREACHABLE = 'WALLET_UNREACHABLE',
+  JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE = 'JURISDICTIONAL_REQUIREMENTS_UNAVAILABLE',
+  IDV_UNAVAILABLE = 'IDV_UNAVAILABLE',
+}
+
 /**
  * Represents an error component message
  * @param message - Error message
@@ -994,12 +1005,14 @@ export type InvalidValue<T> = {
  * Represents a warning component message
  * @param message - Warning message
  * @param description - Description of the warning message
+ * @param identifier - Identifier code of the warning message
  * @public
  */
 export type Warning = {
   type: CMType.WARNING;
   message: string;
   description?: string;
+  identifier?: WarningIdentifierCode;
 };
 
 /**

package/src/utils/arbitraries.ts

@@ -208,7 +208,6 @@ export const arbitraryTransactionOptions =
             fc.record({
               destination: arbitraryBlockchainAddress(),
               amountSubunits: fc.string(),
-              timeout: fc.option(fc.nat()),
             }),
           ),
           fallbacks: fc.option(