@notabene/javascript-sdk 2.0.0-next.9 → 2.0.1

package/src/utils/MessageEventManager.ts

@@ -1,29 +1,78 @@
 import { ComponentMessage, HostMessage } from '../types';
 
-export type MessageCallback = (message: ComponentMessage) => void;
+/**
+ * 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 class MessageEventManager {
-  private listeners: Map<string, Set<MessageCallback>> = new Map();
+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();
   }
 
-  on(messageType: string, callback: MessageCallback): void {
+  /**
+   * 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);
   }
 
-  off(messageType: string, callback: MessageCallback): void {
+  /**
+   * 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);
@@ -33,8 +82,17 @@ export class MessageEventManager {
     }
   }
 
-  private handleMessage(event: MessageEvent): void {
-    console.log('received message', event.data);
+  /**
+   * 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;
@@ -45,8 +103,11 @@ export class MessageEventManager {
     }
   }
 
-  // Method to send messages through the port
-  send(message: HostMessage): void {
+  /**
+   * 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

@@ -1,9 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { HMType, UpdateValue } from '../../types';
+import {
+  HMType,
+  type TransactionOptions,
+  type UpdateValue,
+  type Withdrawal,
+} from '../../types';
 import { MessageEventManager } from '../MessageEventManager';
 
 describe('MessageEventManager', () => {
-  let messageEventManager: MessageEventManager;
+  let messageEventManager: MessageEventManager<Withdrawal, TransactionOptions>;
   let mockPort: MessagePort;
 
   beforeEach(() => {
@@ -13,7 +18,10 @@ describe('MessageEventManager', () => {
       start: vi.fn(),
     } as unknown as MessagePort;
 
-    messageEventManager = new MessageEventManager();
+    messageEventManager = new MessageEventManager<
+      Withdrawal,
+      TransactionOptions
+    >();
   });
 
   describe('setPort', () => {
@@ -73,9 +81,9 @@ describe('MessageEventManager', () => {
     });
 
     it('should send messages through the port', () => {
-      const message: UpdateValue = {
+      const message: UpdateValue<Withdrawal, TransactionOptions> = {
         type: HMType.UPDATE,
-        value: { asset: 'USDC' },
+        value: { requestId: 'id' },
       };
       messageEventManager.send(message);
 
@@ -91,5 +99,21 @@ describe('MessageEventManager', () => {
 
       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

@@ -1,5 +1,36 @@
 import fc from 'fast-check';
-import type { CAIP10, CAIP19, CAIP2, CAIP220 } from '../types';
+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,
@@ -8,6 +39,7 @@ import {
 } 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> =>
@@ -24,3 +56,189 @@ export const arbitraryCAIP220 = (): 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/urls.ts

@@ -1,15 +1,40 @@
 export function encodeObjectToFragment(obj: any) {
   return Object.entries(obj)
     .map(([key, value]) => {
-      if (!(key && value)) return undefined;
+      // 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)
-          : (value as string | number | boolean),
+        typeof value === 'object' ? JSON.stringify(value) : String(value), // Use String() to handle all primitive types
       );
       return `${encodedKey}=${encodedValue}`;
     })
-    .filter((entry) => !!entry)
+    .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>,
+  );
+}