@notabene/javascript-sdk 1.35.2 → 2.0.0-RC

package/src/utils/MessageEventManager.ts

@@ -0,0 +1,115 @@
+import { ComponentMessage, HostMessage } from '../types';
+
+/**
+ * Callback function for handling component messages.
+ *
+ * @typeParam T - The type of data contained in the component message
+ * @param message - The message object containing the component data and type
+ * @public
+ */
+
+export type MessageCallback<T> = (message: ComponentMessage<T>) => void;
+
+/**
+ * Manages message event communication through MessagePorts.
+ *
+ * This class handles bidirectional communication between components using MessagePorts,
+ * allowing subscription to specific message types and dispatching messages to registered callbacks.
+ *
+ * @typeParam T - The type of data contained in messages received from components
+ * @typeParam O - The type of data contained in messages sent from the host
+ */
+
+export class MessageEventManager<T, O> {
+  private listeners: Map<string, Set<MessageCallback<T>>> = new Map();
+  private port?: MessagePort;
+
+  constructor() {
+    this.handleMessage = this.handleMessage.bind(this);
+  }
+
+  /**
+   * Sets up the message port for communication.
+   *
+   * Initializes the MessagePort for receiving messages by setting up the message handler
+   * and starting the port.
+   *
+   * @param port - The MessagePort instance to use for communication
+   */
+
+  setPort(port: MessagePort): void {
+    this.port = port;
+    this.port.onmessage = this.handleMessage;
+    this.port.start();
+  }
+
+  /**
+   * Registers a callback for a specific message type.
+   *
+   * When messages of the specified type are received, the callback will be executed
+   * with the message data.
+   *
+   * @param messageType - The type of message to listen for
+   * @param callback - The callback function to execute when matching messages are received
+
+   */
+
+  on(messageType: string, callback: MessageCallback<T>): () => void {
+    if (!this.listeners.has(messageType)) {
+      this.listeners.set(messageType, new Set());
+    }
+    this.listeners.get(messageType)!.add(callback);
+    return () => this.off(messageType, callback);
+  }
+
+  /**
+   * Removes a callback for a specific message type.
+   *
+   * If the callback is the last one registered for the message type,
+   * the message type entry will be removed entirely.
+   *
+   * @param messageType - The type of message to remove listener from
+   * @param callback - The callback function to remove
+   */
+
+  off(messageType: string, callback: MessageCallback<T>): void {
+    const callbacks = this.listeners.get(messageType);
+    if (callbacks) {
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        this.listeners.delete(messageType);
+      }
+    }
+  }
+
+  /**
+   * Internal message handler for processing received messages.
+   *
+   * Validates incoming messages and dispatches them to registered callbacks
+   * based on the message type.
+   *
+   * @param event - The message event containing the component message
+   */
+
+  private handleMessage(event: MessageEvent<ComponentMessage<T>>): void {
+    // console.log('received message', event.data);
+    const message = event.data;
+    if (typeof message === 'object' && message !== null && 'type' in message) {
+      const messageType = message.type as string;
+      const callbacks = this.listeners.get(messageType);
+      if (callbacks) {
+        callbacks.forEach((callback) => callback(message));
+      }
+    }
+  }
+
+  /**
+   * Sends a message through the message port
+   * @param message The host message to send
+   */
+  send(message: HostMessage<T, O>): void {
+    if (this.port) {
+      this.port.postMessage(message);
+    }
+  }
+}

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

@@ -0,0 +1,119 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  HMType,
+  type TransactionOptions,
+  type UpdateValue,
+  type Withdrawal,
+} from '../../types';
+import { MessageEventManager } from '../MessageEventManager';
+
+describe('MessageEventManager', () => {
+  let messageEventManager: MessageEventManager<Withdrawal, TransactionOptions>;
+  let mockPort: MessagePort;
+
+  beforeEach(() => {
+    mockPort = {
+      onmessage: null,
+      postMessage: vi.fn(),
+      start: vi.fn(),
+    } as unknown as MessagePort;
+
+    messageEventManager = new MessageEventManager<
+      Withdrawal,
+      TransactionOptions
+    >();
+  });
+
+  describe('setPort', () => {
+    beforeEach(() => {
+      messageEventManager.setPort(mockPort);
+    });
+
+    it('should start the port when initialized', () => {
+      expect(mockPort.start).toHaveBeenCalled();
+    });
+
+    it('should subscribe and receive messages of a specific type', () => {
+      const readyHandler = vi.fn();
+      messageEventManager.on('ready', readyHandler);
+
+      const readyMessage = { type: 'ready' };
+      mockPort.onmessage!({ data: readyMessage } as MessageEvent);
+
+      expect(readyHandler).toHaveBeenCalledWith(readyMessage);
+    });
+
+    it('should not call handlers for different message types', () => {
+      const updateHandler = vi.fn();
+      const errorHandler = vi.fn();
+      messageEventManager.on('update', updateHandler);
+      messageEventManager.on('error', errorHandler);
+
+      const errorMessage = { type: 'error', message: 'Something went wrong' };
+      mockPort.onmessage!({ data: errorMessage } as MessageEvent);
+
+      expect(updateHandler).not.toHaveBeenCalled();
+      expect(errorHandler).toHaveBeenCalledWith(errorMessage);
+    });
+
+    it('should unsubscribe handlers', () => {
+      const updateHandler = vi.fn();
+      messageEventManager.on('update', updateHandler);
+      messageEventManager.off('update', updateHandler);
+
+      const updateMessage = { type: 'update', data: { foo: 'bar' } };
+      mockPort.onmessage!({ data: updateMessage } as MessageEvent);
+
+      expect(updateHandler).not.toHaveBeenCalled();
+    });
+
+    it('should allow multiple subscribers for the same message type', () => {
+      const updateHandler1 = vi.fn();
+      const updateHandler2 = vi.fn();
+      messageEventManager.on('update', updateHandler1);
+      messageEventManager.on('update', updateHandler2);
+
+      const updateMessage = { type: 'update', data: { foo: 'bar' } };
+      mockPort.onmessage!({ data: updateMessage } as MessageEvent);
+
+      expect(updateHandler1).toHaveBeenCalledWith(updateMessage);
+      expect(updateHandler2).toHaveBeenCalledWith(updateMessage);
+    });
+
+    it('should send messages through the port', () => {
+      const message: UpdateValue<Withdrawal, TransactionOptions> = {
+        type: HMType.UPDATE,
+        value: { requestId: 'id' },
+      };
+      messageEventManager.send(message);
+
+      expect(mockPort.postMessage).toHaveBeenCalledWith(message);
+    });
+
+    it('should ignore messages without a type', () => {
+      const handler = vi.fn();
+      messageEventManager.on('update', handler);
+
+      const invalidMessage = { data: 'no type field' };
+      mockPort.onmessage!({ data: invalidMessage } as MessageEvent);
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('on returns unsubscribe function', () => {
+      const messageType = 'customEvent';
+      const callback = vi.fn();
+      const unsubscribe = messageEventManager.on(messageType, callback);
+
+      // Verify it's a function
+      expect(typeof unsubscribe).toBe('function');
+
+      // Call it and verify the handler is removed
+      unsubscribe();
+
+      // Simulate a message - callback should not be called
+      mockPort.onmessage!({ data: { type: messageType } } as MessageEvent);
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,112 @@
+import { fc, test } from '@fast-check/vitest';
+import { describe, expect } from 'vitest';
+import { decodeFragmentToObject, encodeObjectToFragment } from '../urls';
+
+describe('encodeObjectToFragment', () => {
+  test.prop([
+    fc.record({
+      key1: fc.string(),
+      key2: fc.string(),
+      key3: fc.string(),
+    }),
+  ])('Should correctly encode simple string values', (obj) => {
+    const encoded = encodeObjectToFragment(obj);
+    const parts = encoded.split('&');
+
+    return Object.entries(obj).every(([key, value]) => {
+      const part = `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      return parts.includes(part);
+    });
+  });
+
+  test.prop([
+    fc.record({
+      str: fc.string(),
+      num: fc.float(),
+      bool: fc.boolean(),
+    }),
+  ])('Should handle different primitive types', (obj) => {
+    const encoded = encodeObjectToFragment(obj);
+    const parts = encoded.split('&');
+
+    return Object.entries(obj).every(([key, value]) => {
+      const part = `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      return parts.includes(part);
+    });
+  });
+
+  test.prop([
+    fc.record({
+      obj: fc.object(),
+      arr: fc.array(fc.string()),
+      nested: fc.record({
+        a: fc.string(),
+        b: fc.integer(),
+      }),
+    }),
+  ])('Should properly encode nested objects', (obj) => {
+    const encoded = encodeObjectToFragment(obj);
+    const parts = encoded.split('&');
+
+    return Object.entries(obj).every(([key, value]) => {
+      const part = `${encodeURIComponent(key)}=${encodeURIComponent(JSON.stringify(value))}`;
+      return parts.includes(part);
+    });
+  });
+
+  test('Should skip undefined or null values', () => {
+    const obj = {
+      valid: 'value',
+      empty: undefined,
+      null: null,
+      falsy: 0,
+    };
+
+    const encoded = encodeObjectToFragment(obj);
+    expect(encoded).toBe('valid=value&falsy=0');
+  });
+
+  test('Should handle empty objects', () => {
+    const encoded = encodeObjectToFragment({});
+    expect(encoded).toBe('');
+  });
+});
+
+describe('decodeFragmentToObject', () => {
+  test.prop([
+    fc.record({
+      key1: fc.string(),
+      key2: fc.string(),
+      key3: fc.string(),
+    }),
+  ])('Should correctly decode URL fragment to object', (obj) => {
+    const fragment =
+      '#' +
+      Object.entries(obj)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join('&');
+
+    const decoded = decodeFragmentToObject(fragment);
+    return Object.entries(obj).every(([k, v]) => decoded[k] === v);
+  });
+
+  test('Should handle empty fragment', () => {
+    const decoded = decodeFragmentToObject('#');
+    expect(decoded).toEqual({});
+  });
+
+  test('Should handle fragment without values', () => {
+    const decoded = decodeFragmentToObject('#key1=&key2=');
+    expect(decoded).toEqual({ key1: '', key2: '' });
+  });
+
+  test('Should decode special characters', () => {
+    const fragment = '#key1=%20space%20&key2=%3Dequals%3D&key3=%26ampersand%26';
+    const decoded = decodeFragmentToObject(fragment);
+    expect(decoded).toEqual({
+      key1: ' space ',
+      key2: '=equals=',
+      key3: '&ampersand&',
+    });
+  });
+});

package/src/utils/arbitraries.ts

@@ -0,0 +1,244 @@
+import fc from 'fast-check';
+import type {
+  Agent,
+  BlockchainAddress,
+  CAIP10,
+  CAIP19,
+  CAIP2,
+  CAIP220,
+  CallbackOptions,
+  ConnectionOptions,
+  ConnectionRequest,
+  Counterparty,
+  CryptoCredential,
+  DepositRequest,
+  DepositRequestOptions,
+  DID,
+  FieldTypes,
+  ISOCurrency,
+  ISODate,
+  NaturalPerson,
+  ThresholdOptions,
+  TransactionAsset,
+  TransactionOptions,
+  TravelAddress,
+  VASPOptions,
+  Withdrawal,
+} from '../types';
+import {
+  AgentType,
+  PersonType,
+  ProofTypes,
+  ValidationSections,
+} from '../types';
+import {
+  CAIP10_MATCHER,
+  CAIP19_MATCHER,
+  CAIP220_MATCHER,
+  CAIP2_MATCHER,
+} from './caip';
+
+const LOCALE = new RegExp(/^[a-z]{2}(-[A-Z]{2})?$/);
+const COMPONENT_MATCHER = /^[a-z0-9-_]+$/;
+
+// Arbitraries
+export const arbitraryCAIP10 = (): fc.Arbitrary<CAIP10> =>
+  fc.stringMatching(CAIP10_MATCHER) as fc.Arbitrary<CAIP10>;
+
+export const arbitraryCAIP2 = (): fc.Arbitrary<CAIP2> =>
+  fc.stringMatching(CAIP2_MATCHER) as fc.Arbitrary<CAIP2>;
+
+export const arbitraryCAIP19 = (): fc.Arbitrary<CAIP19> =>
+  fc.stringMatching(CAIP19_MATCHER) as fc.Arbitrary<CAIP19>;
+
+export const arbitraryCAIP220 = (): fc.Arbitrary<CAIP220> =>
+  fc.stringMatching(CAIP220_MATCHER) as fc.Arbitrary<CAIP220>;
+
+export const arbitraryLocale = (): fc.Arbitrary<string> =>
+  fc.stringMatching(LOCALE) as fc.Arbitrary<string>;
+
+// Arbitraries
+export const arbitraryComponent = (): fc.Arbitrary<string> =>
+  fc.stringMatching(COMPONENT_MATCHER);
+
+export const abitraryCallbackOptions = (): fc.Arbitrary<CallbackOptions> =>
+  fc.record({
+    callback: fc.webUrl(),
+    redirectUri: fc.webUrl(),
+  });
+
+export const arbitraryDID = (): fc.Arbitrary<DID> =>
+  fc.string().map((s) => `did:ethr:${s}` as DID);
+
+export const arbitraryBlockchainAddress = (): fc.Arbitrary<BlockchainAddress> =>
+  fc.hexaString({ minLength: 40, maxLength: 40 }).map((s) => `0x${s}`);
+
+export const arbitraryTransactionAsset = (): fc.Arbitrary<TransactionAsset> =>
+  fc.oneof(
+    fc.string(), // NotabeneAsset
+    arbitraryCAIP19(), // CAIP19
+    fc.string().map((s) => `DTI${s.slice(0, 5)}`), // DTI
+  );
+
+export const arbitraryAgent = (): fc.Arbitrary<Agent> =>
+  fc.record({
+    did: arbitraryDID(),
+    type: fc.constantFrom(...Object.values(AgentType)),
+    logo: fc.option(fc.webUrl()),
+    url: fc.option(fc.webUrl()),
+    name: fc.option(fc.string()),
+    verified: fc.boolean(),
+  });
+
+export const arbitraryCounterparty = (): fc.Arbitrary<Counterparty> =>
+  arbitraryNaturalPerson(); // For simplicity we'll just use NaturalPerson
+
+export const arbitraryWithdrawal = (): fc.Arbitrary<Withdrawal> =>
+  fc.record({
+    agent: arbitraryAgent(),
+    counterparty: arbitraryCounterparty(),
+    asset: arbitraryTransactionAsset(),
+    amountDecimal: fc.float(),
+    destination: fc.oneof(arbitraryBlockchainAddress(), arbitraryCAIP10()),
+  });
+
+export const arbitraryConnectionRequest = (): fc.Arbitrary<ConnectionRequest> =>
+  fc.record({
+    asset: arbitraryTransactionAsset(),
+    requestId: fc.option(fc.uuid()),
+    customer: fc.option(arbitraryCounterparty()),
+  });
+
+// Helper for ISO date format
+export const arbitraryISODate = (): fc.Arbitrary<ISODate> =>
+  fc.date().map((d) => {
+    const [year, month, day] = d.toISOString().split('T')[0].split('-');
+    return `${year}-${month}-${day}` as ISODate;
+  });
+
+// Helper for ISO currency
+export const arbitraryISOCurrency = (): fc.Arbitrary<ISOCurrency> =>
+  fc.constantFrom('USD', 'EUR', 'GBP', 'JPY');
+
+export const arbitraryNaturalPerson = (): fc.Arbitrary<NaturalPerson> =>
+  fc.record({
+    type: fc.constant(PersonType.NATURAL),
+    name: fc.string(),
+    accountNumber: fc.option(fc.string()),
+    did: fc.option(arbitraryDID()),
+    verified: fc.option(fc.boolean()),
+    website: fc.option(fc.webUrl()),
+    phone: fc.option(fc.string()),
+    email: fc.option(fc.string()),
+    dateOfBirth: fc.option(arbitraryISODate()),
+    placeOfBirth: fc.option(fc.string()),
+    countryOfResidence: fc.option(fc.string()),
+  });
+
+export const arbitraryTravelAddress = (): fc.Arbitrary<TravelAddress> =>
+  fc.string().map((s) => `ta${s}` as TravelAddress);
+
+export const arbitraryCryptoCredential = (): fc.Arbitrary<CryptoCredential> =>
+  fc
+    .tuple(fc.string(), fc.string())
+    .map(([a, b]) => `${a}.${b}.mastercard` as CryptoCredential);
+
+export const arbitraryDepositRequest = (): fc.Arbitrary<DepositRequest> =>
+  fc.record({
+    agent: arbitraryAgent(),
+    counterparty: arbitraryCounterparty(),
+    asset: arbitraryTransactionAsset(),
+    amountDecimal: fc.float(),
+    destination: fc.oneof(arbitraryBlockchainAddress(), arbitraryCAIP10()),
+    travelAddress: fc.option(arbitraryTravelAddress()),
+    cryptoCredential: fc.option(arbitraryCryptoCredential()),
+  });
+
+// Options arbitraries
+export const arbitraryThresholdOptions = (): fc.Arbitrary<ThresholdOptions> =>
+  fc.record({
+    threshold: fc.float(),
+    currency: arbitraryISOCurrency(),
+    proofTypes: fc.option(
+      fc.array(fc.constantFrom(...Object.values(ProofTypes))),
+    ),
+  });
+
+export const arbitraryFieldTypes = (): fc.Arbitrary<FieldTypes> =>
+  fc.record({
+    naturalPerson: fc.option(
+      fc.dictionary(
+        fc.string(),
+        fc.oneof(
+          fc.boolean(),
+          fc.record({
+            optional: fc.boolean(),
+            transmit: fc.boolean(),
+          }),
+        ),
+      ),
+    ),
+    legalPerson: fc.option(
+      fc.dictionary(
+        fc.string(),
+        fc.oneof(
+          fc.boolean(),
+          fc.record({
+            optional: fc.boolean(),
+            transmit: fc.boolean(),
+          }),
+        ),
+      ),
+    ),
+  });
+
+export const arbitraryVASPOptions = (): fc.Arbitrary<VASPOptions> =>
+  fc.record({
+    addUnknown: fc.option(fc.boolean()),
+    onlyActive: fc.option(fc.boolean()),
+  });
+
+export const arbitraryTransactionOptions =
+  (): fc.Arbitrary<TransactionOptions> =>
+    fc.record({
+      proofs: fc.option(
+        fc.record({
+          microTransfer: fc.option(
+            fc.record({
+              destination: arbitraryBlockchainAddress(),
+              amountSubunits: fc.string(),
+              timeout: fc.option(fc.nat()),
+            }),
+          ),
+          fallbacks: fc.option(
+            fc.array(fc.constantFrom(...Object.values(ProofTypes))),
+          ),
+          deminimis: fc.option(arbitraryThresholdOptions()),
+        }),
+      ),
+      allowedAgentTypes: fc.option(
+        fc.array(fc.constantFrom(...Object.values(AgentType))),
+      ),
+      allowedCounterpartyTypes: fc.option(
+        fc.array(fc.constantFrom(...Object.values(PersonType))),
+      ),
+      fields: fc.option(arbitraryFieldTypes()),
+      vasps: fc.option(arbitraryVASPOptions()),
+      hide: fc.option(
+        fc.array(fc.constantFrom(...Object.values(ValidationSections))),
+      ),
+    });
+
+export const arbitraryDepositRequestOptions =
+  (): fc.Arbitrary<DepositRequestOptions> =>
+    fc.record({
+      showQrCode: fc.option(fc.boolean()),
+    });
+
+export const arbitraryConnectionOptions =
+  (): fc.Arbitrary<ConnectionOptions> => {
+    const transactionOptions = arbitraryTransactionOptions();
+    return fc.record({
+      proofs: transactionOptions.map((opt) => opt.proofs),
+    });
+  };

package/src/utils/caip.ts

@@ -0,0 +1,16 @@
+// Regexes
+export const ACCOUNT_ADDRESS_REGEX = '[-.%a-zA-Z0-9]{1,128}';
+export const CAIP2_REGEX = '[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}';
+export const CAIP10_REGEX = `^${CAIP2_REGEX}:${ACCOUNT_ADDRESS_REGEX}$`;
+export const CAIP19_REGEX = `^${CAIP2_REGEX}/[-a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}(/[-.%a-zA-Z0-9]{1,78})?$`;
+export const CAIP220_REGEX = `^${CAIP2_REGEX}:[block:]?tx/[-.%a-zA-Z0-9]{1,128}$`;
+export const CRYPTO_SYMBOL_REGEX = '^[A-Z0-9]{2,10}$';
+export const DTI_REGEX = '^[A-Za-z0-9]{10}$';
+export const COMBINED_ASSET_REGEX = `(${CRYPTO_SYMBOL_REGEX})|(${CAIP19_REGEX})|(${DTI_REGEX})`;
+
+// Matchers
+export const CAIP2_MATCHER = new RegExp(CAIP2_REGEX);
+export const CAIP10_MATCHER = new RegExp(CAIP10_REGEX);
+export const CAIP19_MATCHER = new RegExp(CAIP19_REGEX);
+export const CAIP220_MATCHER = new RegExp(CAIP220_REGEX);
+export const COMBINED_ASSET_MATCHER = new RegExp(COMBINED_ASSET_REGEX);

package/src/utils/urls.ts

@@ -0,0 +1,40 @@
+export function encodeObjectToFragment(obj: any) {
+  return Object.entries(obj)
+    .map(([key, value]) => {
+      // Change condition to check for undefined/null specifically
+      if (value === undefined || value === null) return undefined;
+      const encodedKey = encodeURIComponent(key);
+      const encodedValue = encodeURIComponent(
+        typeof value === 'object' ? JSON.stringify(value) : String(value), // Use String() to handle all primitive types
+      );
+      return `${encodedKey}=${encodedValue}`;
+    })
+    .filter((entry) => entry !== undefined)
+    .join('&');
+}
+/**
+ * Decodes a URL fragment into an object
+ *
+ * @param fragment - The URL fragment to decode
+ * @returns An object containing the decoded key-value pairs
+ * @public
+ */
+export function decodeFragmentToObject(
+  fragment: string,
+): Record<string, string> {
+  const withoutHash = fragment.slice(1);
+  if (!withoutHash) return {}; // Return empty object for empty fragment
+
+  const pairs = withoutHash.split('&').filter(Boolean); // Filter out empty strings
+  return pairs.reduce(
+    (obj, pair) => {
+      const [key, value] = pair.split('=');
+      if (key) {
+        // Only add if key exists
+        obj[decodeURIComponent(key)] = value ? decodeURIComponent(value) : '';
+      }
+      return obj;
+    },
+    {} as Record<string, string>,
+  );
+}

package/.editorconfig

@@ -1,10 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-
-[*.{js,json,yml}]
-charset = utf-8
-indent_style = space
-indent_size = 2

package/.envrc.template

@@ -1 +0,0 @@
-export GITLAB_TOKEN="your-gitlab-token"

package/.eslintignore

@@ -1,3 +0,0 @@
-dist
-.eslintrc.js
-jest.config.js

package/.eslintrc.js

@@ -1,13 +0,0 @@
-module.exports = {
-  root: true,
-  parser: '@typescript-eslint/parser',
-  plugins: ['@typescript-eslint'],
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:prettier/recommended',
-  ],
-  rules: {
-    '@typescript-eslint/ban-ts-comment': 'off',
-  },
-};