@notabene/javascript-sdk 2.16.0-next.1 → 2.16.0-next.4

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.16.0-next.1",
+  "version": "2.16.0-next.4",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/src/__tests__/notabene.test.ts

@@ -340,6 +340,30 @@ describe('Notabene', () => {
     });
   });
 
+  describe('createInvoiceReader', () => {
+    test.prop([
+      fc.string({ minLength: 3 }), // authToken
+      arbitraryNodeUrl(), // nodeUrl
+    ])(
+      'Should create invoice reader component with correct URL',
+      (authToken, nodeUrl) => {
+        const notabene = new Notabene({
+          nodeUrl,
+          authToken,
+        });
+
+        const component = notabene.createInvoiceReader();
+        const url = new URL(component.url);
+
+        return (
+          url.pathname === '/flow-link/invoice-reader' &&
+          url.hash ===
+            `#authToken=${encodeURIComponent(authToken)}&value=${encodeURIComponent(JSON.stringify({}))}` &&
+          url.searchParams.get('nodeUrl') === nodeUrl
+        );
+      },
+    );
+  });
   describe('uxUrl trailing slash normalization', () => {
     it('should strip a single trailing slash', () => {
       const notabene = new Notabene({

package/src/ivms/v2Types.ts

@@ -7,12 +7,10 @@ import type {
 
 export type OriginatorV2 = {
   originatorPerson: PersonV2[];
-  customerIdentification?: string;
 };
 
 export type BeneficiaryV2 = {
   beneficiaryPerson: PersonV2[];
-  customerIdentification?: string;
 };
 
 export type NaturalPersonNameIDV2 = {
@@ -27,6 +25,7 @@ export type NaturalPersonNameV2 = Omit<NaturalPersonName, 'nameIdentifier'> & {
 
 export type NaturalPersonV2 = Omit<NaturalPerson, 'name'> & {
   name: NaturalPersonNameV2;
+  customerIdentification?: string;
 };
 
 export type PersonV2 = Omit<Person, 'naturalPerson'> & {

package/src/notabene.ts

@@ -30,6 +30,7 @@ import type {
   FieldTypes,
   HostMessage,
   InvalidValue,
+  InvoiceReaderResponse,
   IVMS101,
   LegalPerson,
   LegalPersonFieldName,
@@ -96,6 +97,7 @@ export type {
   TransactionCreateRequestV2,
   TransactionIVMS101Request,
 } from './responseTransformer';
+export type { Invoice } from './types';
 export {
   ConnectionManager,
   getRefreshResult,
@@ -153,6 +155,7 @@ export type {
   FieldTypes,
   HostMessage,
   InvalidValue,
+  InvoiceReaderResponse,
   IVMS101,
   LegalPerson,
   LegalPersonFieldName,
@@ -403,6 +406,23 @@ export default class Notabene {
     );
   }
 
+  /**
+   * Creates an invoice reader component for extracting TAIP-16 invoice data from PDF invoices
+   *
+   * The component provides a PDF drag-and-drop upload UI. On upload, the PDF is
+   * parsed and the extracted invoice data is returned. On completion,
+   * the response contains the TAIP-16 invoice data.
+   *
+   * @returns A new EmbeddedComponent instance for invoice reader creation
+   * @public
+   */
+  public createInvoiceReader() {
+    return this.createComponent<InvoiceReaderResponse, Record<string, never>>(
+      'flow-link/invoice-reader',
+      {},
+    );
+  }
+
   /**
    * Creates a deposit assist component
    *

package/src/responseTransformer/__tests__/transformer.test.ts

@@ -2,7 +2,11 @@ import { describe, expect, it } from 'vitest';
 import type { OriginatorV2 } from '../../ivms/v2Types';
 import type { Deposit, TransactionResponse, Withdrawal } from '../../types';
 import { PersonType } from '../../types';
-import { componentResponseToTxRequests, enrichConfig } from '../transformer';
+import {
+  componentResponseToTxRequests,
+  enrichConfig,
+  uuid,
+} from '../transformer';
 
 // Common test constants
 const TEST_DELEGATE_TOKEN = 'test-delegate-token';
@@ -506,6 +510,35 @@ describe('componentResponseToTxRequests', () => {
   });
 });
 
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+describe('uuid', () => {
+  it('should return a valid UUID v4 format', () => {
+    const result = uuid();
+    expect(result).toMatch(UUID_REGEX);
+  });
+
+  it('should return unique values on each call', () => {
+    const results = new Set(Array.from({ length: 100 }, () => uuid()));
+    expect(results.size).toBe(100);
+  });
+
+  it('should always have version 4 indicator', () => {
+    for (let i = 0; i < 50; i++) {
+      const result = uuid();
+      expect(result[14]).toBe('4');
+    }
+  });
+
+  it('should always have a valid variant nibble (8, 9, a, or b)', () => {
+    for (let i = 0; i < 50; i++) {
+      const result = uuid();
+      expect('89ab').toContain(result[19]);
+    }
+  });
+});
+
 describe('enrichConfig', () => {
   const CUSTOMER_DID = 'did:key:customer123';
   const SOURCE_ADDRESS = '0xsource123';
@@ -520,7 +553,7 @@ describe('enrichConfig', () => {
   }
 
   describe('withdrawal transactions', () => {
-    it('should extract originatorId from delegate token and generate beneficiaryId from destination', () => {
+    it('should extract originatorId from delegate token and fall back to urn:uuid for beneficiaryId', () => {
       const delegateToken = createDelegateToken(CUSTOMER_DID);
       const withdrawal = {
         destination: DESTINATION_ADDRESS,
@@ -531,7 +564,7 @@ describe('enrichConfig', () => {
       const result = enrichConfig({}, delegateToken, withdrawal);
 
       expect(result.originatorId).toBe(CUSTOMER_DID);
-      expect(result.beneficiaryId).toBe(`did:key:${DESTINATION_ADDRESS}`);
+      expect(result.beneficiaryId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
     });
 
     it('should set beneficiaryId equal to originatorId for self-transfers', () => {
@@ -572,7 +605,7 @@ describe('enrichConfig', () => {
   });
 
   describe('deposit transactions', () => {
-    it('should extract beneficiaryId from delegate token and generate originatorId from source', () => {
+    it('should extract beneficiaryId from delegate token and fall back to urn:uuid for originatorId', () => {
       const delegateToken = createDelegateToken(CUSTOMER_DID);
       const deposit = {
         source: SOURCE_ADDRESS,
@@ -583,7 +616,7 @@ describe('enrichConfig', () => {
       const result = enrichConfig({}, delegateToken, deposit);
 
       expect(result.beneficiaryId).toBe(CUSTOMER_DID);
-      expect(result.originatorId).toBe(`did:key:${SOURCE_ADDRESS}`);
+      expect(result.originatorId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
     });
 
     it('should set originatorId equal to beneficiaryId for self-transfers', () => {
@@ -632,7 +665,51 @@ describe('enrichConfig', () => {
 
     const result = enrichConfig({}, 'invalid-token', withdrawal);
 
-    expect(result.originatorId).toBeUndefined();
-    expect(result.beneficiaryId).toBe(`did:key:${DESTINATION_ADDRESS}`);
+    expect(result.originatorId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
+    expect(result.beneficiaryId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
+  });
+
+  describe('UUID fallback', () => {
+    it('should generate a valid urn:uuid for missing beneficiaryId', () => {
+      const delegateToken = createDelegateToken(CUSTOMER_DID);
+      const withdrawal = {
+        destination: DESTINATION_ADDRESS,
+        asset: TEST_ASSET,
+        amountDecimal: 100,
+      } as Withdrawal;
+
+      const result = enrichConfig({}, delegateToken, withdrawal);
+
+      expect(result.originatorId).toBe(CUSTOMER_DID);
+      expect(result.beneficiaryId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
+    });
+
+    it('should generate a valid urn:uuid for missing originatorId', () => {
+      const delegateToken = createDelegateToken(CUSTOMER_DID);
+      const deposit = {
+        source: SOURCE_ADDRESS,
+        asset: TEST_ASSET,
+        amountDecimal: 100,
+      } as Deposit;
+
+      const result = enrichConfig({}, delegateToken, deposit);
+
+      expect(result.beneficiaryId).toBe(CUSTOMER_DID);
+      expect(result.originatorId).toMatch(/^urn:uuid:[0-9a-f-]{36}$/);
+    });
+
+    it('should generate unique UUIDs for each call', () => {
+      const withdrawal = {
+        destination: DESTINATION_ADDRESS,
+        asset: TEST_ASSET,
+        amountDecimal: 100,
+      } as Withdrawal;
+
+      const result1 = enrichConfig({}, 'invalid-token', withdrawal);
+      const result2 = enrichConfig({}, 'invalid-token', withdrawal);
+
+      expect(result1.beneficiaryId).not.toBe(result2.beneficiaryId);
+      expect(result1.originatorId).not.toBe(result2.originatorId);
+    });
   });
 });

package/src/responseTransformer/__tests__/utils.test.ts

@@ -1,5 +1,25 @@
 import { describe, expect, it } from 'vitest';
-import { getCaip10ChainPrefix } from '../utils';
+import { getCaip10ChainPrefix, getPartyId } from '../utils';
+
+describe('getPartyId', () => {
+  it('should return mailto: IRI when party has email', () => {
+    expect(getPartyId({ email: 'test@example.com' })).toBe(
+      'mailto:test@example.com',
+    );
+  });
+
+  it('should return undefined when party has no email', () => {
+    expect(getPartyId({})).toBeUndefined();
+  });
+
+  it('should return undefined when party is undefined', () => {
+    expect(getPartyId(undefined)).toBeUndefined();
+  });
+
+  it('should return undefined when called with no arguments', () => {
+    expect(getPartyId()).toBeUndefined();
+  });
+});
 
 describe('getCaip10ChainPrefix', () => {
   it('should extract chain prefix from EIP155 CAIP-10 address', () => {

package/src/responseTransformer/mappers.ts

@@ -1,11 +1,11 @@
+import type { Agent, DID } from '@taprsvp/types';
 import type {
   Beneficiary,
   NaturalPerson,
   NaturalPersonName,
   Originator,
   Person,
-} from '@notabene/javascript-sdk/src/ivms/types';
-import type { Agent } from '@taprsvp/types';
+} from '../ivms';
 import {
   PersonType,
   type Deposit,
@@ -14,6 +14,7 @@ import {
   type Withdrawal,
 } from '../types';
 import type {
+  BaseRequestConfig,
   ResponseToIVMS101RequestConfig,
   ResponseToTxCreateRequestConfig,
   TransactionCreateRequest,
@@ -23,7 +24,6 @@ import type {
 import {
   convertPersonToV2,
   getCaip10ChainPrefix,
-  getPartyId,
   isDeposit,
   isWithdrawal,
 } from './utils';
@@ -237,22 +237,10 @@ export function mapToV1CreateRequest(
 export function mapToTransactCreateRequest(
   transaction: Withdrawal | Deposit,
   payload: V1Transaction,
-  config: ResponseToTxCreateRequestConfig = {},
+  config: ResponseToTxCreateRequestConfig & Required<BaseRequestConfig>,
 ): 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', originatorParty);
-  const beneficiaryId =
-    config?.beneficiaryId || getPartyId('beneficiary', beneficiaryParty);
+  const originatorId = config.originatorId;
+  const beneficiaryId = config.beneficiaryId;
   const referenceId =
     config?.referenceId ||
     payload.transactionId ||
@@ -262,7 +250,8 @@ export function mapToTransactCreateRequest(
   if (payload.originatorVASPdid) {
     agents.push({
       '@id': payload.originatorVASPdid,
-      for: originatorId,
+      // tap type needs to be updated to accept IRI as valid id
+      for: originatorId as DID,
       role: 'VASP',
     });
   }
@@ -270,7 +259,8 @@ export function mapToTransactCreateRequest(
   if (payload.beneficiaryVASPdid) {
     agents.push({
       '@id': payload.beneficiaryVASPdid,
-      for: beneficiaryId,
+      // tap type needs to be updated to accept IRI as valid id
+      for: beneficiaryId as DID,
       role: 'VASP',
     });
   }
@@ -278,7 +268,8 @@ export function mapToTransactCreateRequest(
   if (isWithdrawal(transaction) && transaction?.account?.did) {
     agents.push({
       '@id': transaction.account.did,
-      for: payload.beneficiaryVASPdid || beneficiaryId,
+      // tap type needs to be updated to accept IRI as valid id
+      for: (payload.beneficiaryVASPdid || beneficiaryId) as DID,
       role: 'SettlementAddress',
     });
   }
@@ -287,7 +278,8 @@ export function mapToTransactCreateRequest(
     if (transaction.account.did) {
       agents.push({
         '@id': transaction.account.did,
-        for: payload.originatorVASPdid || originatorId,
+        // tap type needs to be updated to accept IRI as valid id
+        for: (payload.originatorVASPdid || originatorId) as DID,
         role: 'SourceAddress',
       });
     }
@@ -296,7 +288,8 @@ export function mapToTransactCreateRequest(
       const chainPrefix = getCaip10ChainPrefix(transaction.account.caip10);
       agents.push({
         '@id': `did:pkh:${chainPrefix}:${config.settlementAddress}`,
-        for: payload.beneficiaryVASPdid || beneficiaryId,
+        // tap type needs to be updated to accept IRI as valid id
+        for: (payload.beneficiaryVASPdid || beneficiaryId) as DID,
         role: 'SettlementAddress',
       });
     }
@@ -315,12 +308,10 @@ export function mapToTransactCreateRequest(
 export function mapToAppendPiiRequest(
   transaction: Withdrawal | Deposit,
   ivms101: IVMS101,
-  config: ResponseToIVMS101RequestConfig = {},
+  config: ResponseToIVMS101RequestConfig & Required<BaseRequestConfig>,
 ): TransactionIVMS101Request {
   if (isWithdrawal(transaction)) {
-    const beneficiaryId =
-      config.beneficiaryId ||
-      getPartyId('beneficiary', transaction.counterparty);
+    const beneficiaryId = config.beneficiaryId;
 
     const beneficiaryPersons =
       // If counterparty type is SELF, reuse originator data for beneficiary
@@ -341,8 +332,7 @@ export function mapToAppendPiiRequest(
     };
   }
 
-  const originatorId =
-    config.originatorId || getPartyId('originator', transaction.counterparty);
+  const originatorId = config.originatorId;
 
   const originatorPersons =
     transaction.counterparty?.type === PersonType.SELF && config.beneficiary

package/src/responseTransformer/transformer.ts

@@ -1,4 +1,5 @@
 import { decodeJwt } from 'jose';
+
 import {
   PersonType,
   type Deposit,
@@ -13,6 +14,7 @@ import {
   mapToV1CreateRequest,
 } from './mappers';
 import type {
+  BaseRequestConfig,
   DelegateToken,
   ResponseToIVMS101RequestConfig,
   ResponseToTxCreateRequestConfig,
@@ -21,7 +23,33 @@ import type {
   TransactionCreateRequestV2,
   TransactionIVMS101Request,
 } from './types';
-import { isDeposit, isWithdrawal } from './utils';
+import { getPartyId, isDeposit, isWithdrawal } from './utils';
+
+export function uuid(): string {
+  if (typeof crypto === 'undefined') {
+    throw new Error(
+      '[Notabene/SDK] Web Crypto API is not available. A secure environment with crypto support is required (Node.js 16+ or a modern browser).',
+    );
+  }
+  // Use native randomUUID when available (Node 19+, modern browsers)
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+
+  // Fallback for older environments (Node 16–18) using crypto.getRandomValues
+  return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
+    (
+      +c ^
+      (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (+c / 4)))
+    ).toString(16),
+  );
+}
+
+// This is the format we expect for beneficiaryId and originatorId;
+// however for now we don't use it since the backend doesn't do the check
+// const validateIRI = (uri: string): uri is IRI => {
+//   return uri.indexOf(':') > 0;
+// };
 
 /**
  * Fills in missing config values by extracting them from the delegate token and transaction data
@@ -31,7 +59,7 @@ export function enrichConfig(
   config: ResponseToTxRequestConfig,
   delegateToken: string,
   transaction: Withdrawal | Deposit,
-): ResponseToTxRequestConfig {
+): ResponseToTxRequestConfig & Required<BaseRequestConfig> {
   const enrichedConfig = { ...config };
 
   // Extract customer ID from delegate token
@@ -42,6 +70,7 @@ export function enrichConfig(
     customerIdFromToken = tokenPayload?.sub;
   } catch {
     // If decoding fails, customerIdFromToken remains undefined
+    // TODO: check what should we do in this scenario.
   }
 
   if (isWithdrawal(transaction)) {
@@ -54,9 +83,8 @@ export function enrichConfig(
       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}`;
+        // no-op: TODO: review this logic later if we need to derive beneficiaryId using a public key scheme.
+        // enrichedConfig.beneficiaryId = `did:key:${transaction.destination}`;
       }
     }
   } else if (isDeposit(transaction)) {
@@ -69,14 +97,54 @@ export function enrichConfig(
       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}`;
+        // no-op: TODO: review this logic later if we need to derive originatorId using a public key scheme.
+        // enrichedConfig.originatorId = `did:key:${transaction.source}`;
       }
     }
   }
 
-  return enrichedConfig;
+  // Resolve IDs from party information (email/name) if still missing
+  if (!enrichedConfig.originatorId) {
+    const party = isWithdrawal(transaction)
+      ? transaction.customer
+      : transaction.counterparty;
+    enrichedConfig.originatorId = getPartyId(party);
+  }
+
+  if (!enrichedConfig.beneficiaryId) {
+    const party = isWithdrawal(transaction)
+      ? transaction.counterparty
+      : transaction.customer;
+    enrichedConfig.beneficiaryId = getPartyId(party);
+  }
+
+  if (!enrichedConfig.beneficiaryId) {
+    // TODO : Check if we should throw an exception instead
+    console.warn(
+      `[Notabene/SDK] beneficiaryId not provided; falling back to a generated random identifier.`,
+    );
+    enrichedConfig.beneficiaryId = `urn:uuid:${uuid()}`;
+  }
+
+  if (!enrichedConfig.originatorId) {
+    // TODO : Check if we should throw an exception instead
+    console.warn(
+      `[Notabene/SDK] originatorId not provided; falling back to a generated random identifier.`,
+    );
+    enrichedConfig.originatorId = `urn:uuid:${uuid()}`;
+  }
+
+  // TODO: Re-enable IRI validation once the backend enforces it
+  // if (!validateIRI(enrichedConfig.beneficiaryId)) {
+  //   throw new Error('beneficiaryId is not a valid IRI');
+  // }
+
+  // if (!validateIRI(enrichedConfig.originatorId)) {
+  //   throw new Error('originatorId is not a valid IRI');
+  // }
+
+  return enrichedConfig as ResponseToTxRequestConfig &
+    Required<BaseRequestConfig>;
 }
 
 /**

package/src/responseTransformer/types.ts

@@ -3,7 +3,7 @@
  * These are specific to the API transformation logic
  */
 
-import type { Agent, DID } from '@taprsvp/types';
+import type { Agent, DID, IRI } from '@taprsvp/types';
 import type { BeneficiaryV2, OriginatorV2 } from '../ivms';
 
 export interface DelegateToken {
@@ -14,9 +14,9 @@ export interface DelegateToken {
   iat?: number;
 }
 
-interface BaseRequestConfig {
-  originatorId?: DID;
-  beneficiaryId?: DID;
+export interface BaseRequestConfig {
+  originatorId?: IRI;
+  beneficiaryId?: IRI;
 }
 
 export interface ResponseToTxCreateRequestConfig extends BaseRequestConfig {

package/src/responseTransformer/utils.ts

@@ -1,9 +1,10 @@
+import { CAIP10Schema } from '@taprsvp/types';
 import type {
   NaturalPersonName,
+  NaturalPersonNameV2,
   Person,
-} from '@notabene/javascript-sdk/src/ivms/types';
-import { CAIP10Schema, type DID } from '@taprsvp/types';
-import type { NaturalPersonNameV2, PersonV2 } from '../ivms';
+  PersonV2,
+} from '../ivms';
 import type { Deposit, Withdrawal } from '../types';
 
 export function isDeposit(
@@ -19,21 +20,15 @@ export function isWithdrawal(
 }
 
 /**
- * Generates a backup DID identifier for a party
+ * Resolves a party's IRI identifier from their email, if available.
  */
-export function getPartyId(
-  identifier: 'originator' | 'beneficiary',
-  party?: { email?: string; name?: string },
-): DID {
+export function getPartyId(party?: {
+  email?: string;
+}): `${string}:${string}` | undefined {
   if (party?.email) {
-    return `did:email:${party.email}`;
+    return `mailto:${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`,
-  );
+  return undefined;
 }
 
 /**

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { Invoice, Party } from '@taprsvp/types';
 import type {
   Address,
   Beneficiary,
@@ -23,6 +24,8 @@ export type {
   NationalIdentification,
   Originator,
 };
+// Re-export TAIP-16 invoice types for SDK consumers
+export type { Invoice };
 /**
  * Interoperable Virtual Asset Service Provider (VASP) Messaging Standard
  * @public
@@ -209,6 +212,7 @@ export type Source = BlockchainAddress | CAIP10;
 
 /**
  * A Uniform Resource Identifier
+ * @remarks This type will be narrowed to `` `${string}:${string}` `` in the next major release.
  * @public
  */
 export type URI = string;
@@ -617,6 +621,14 @@ export interface DepositRequestOptions {
   showQrCode?: boolean; // Defaults to true
 }
 
+/** Output fields populated by the component on completion */
+export interface InvoiceReaderResponse {
+  /** TAIP-16 compliant invoice data (populated by the component after PDF parsing) */
+  invoice?: Invoice;
+  merchant?: Party;
+  customer?: Party;
+}
+
 /**
  * An object representing a connection request
  * @public