dome-embedded-app-sdk 0.1.2

package/README.md

@@ -0,0 +1,64 @@
+# The Official Dome SDK
+
+Use this SDK to build plugins for Dome. There are two plugins supported:
+
+1. Cards : Extend the functionality of Dome by adding custom cards.
+
+2. Document Viewer : Add support for editing & viewing any document in Dome.
+
+
+## 1. Cards
+
+A "card" in Dome enables you to extend the functionality of a dome. Each "card" is like a mini website (webapp) that you can build as per your needs. Each dome is made up of cards. By adding your custom card to your dome, you can extend it's functionality.
+
+Use this SDK to create your custom card that can do whatever you like: a simple todo list, snake & ladder game, to a complex project management tool, a 3D AR visualization, to anything else you can imagine! Anything you can build in React or Angular can be created into a card!
+
+As of Dec 2024, we support Angular and React cards. In future, we will add support for more frameworks.
+
+
+### Getting Started with your first Card
+
+#### Register your card
+Register your card at https://dev.dome.so
+
+#### Code
+Import the SDK
+```
+import { CardSdk } from "dome-embedded-app-sdk";
+```
+
+Call init to get instance of the SDK. It takes a secret and event handler as input.
+```
+CardSdk.init(my_dev_card_secret, {
+    onInit: (data: any) => {
+      this.user = data?.user;
+      this.api_token = data?.api_token;
+    },
+    onError: (error_code: string | number, message: string, data: any) => {
+      console.error("Some Error", message + "(" + error_code + ")");
+    },
+    onRefreshRequest: (data: any) => {
+      console.debug("Refresh requested", data);
+    }
+  })
+```
+Note: the `secret` is given to you when you register your card (step 1)
+
+### Deploy
+Deploy your code at https://dev.dome.so
+
+
+## 2. Document Viewer
+
+Add view / edit capability for any document in Dome. For example, you can come up with your own spreadsheet and make it instantly available to all users of Dome. Alternatively, you can create your own viewer that views & (optionally) edits existing documents such as Excel files. The options a limitless!
+
+As of Dec 2024, we support Angular and React document viewers. In future, we will add support for more frameworks.
+
+
+### Getting Started with your first Document Viewer
+
+
+
+## Help
+
+Join our developer community on Dome here: <url>. Hang out, get latest updates, ask questions, experience Dome, and much more!

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "dome-embedded-app-sdk",
+  "version": "0.1.2",
+  "source": "src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build:tsc": "tsc --emitDeclarationOnly",
+    "build:webpack": "webpack --config webpack.config.ts",
+    "build": "npm run build:tsc && npm run build:webpack",
+    "release": "npm run build && npm publish",
+    "watch": "webpack --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dome",
+    "dome-sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@types/webpack": "^5.28.5",
+    "ts-loader": "^9.5.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2",
+    "webpack-cli": "^5.1.4"
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,133 @@
+
+// Provide enc / dec using Algorithm01
+export class CryptoA01 {
+  private subtleCrypto: SubtleCrypto;
+
+  constructor() {
+    // Initialize subtleCrypto once
+    this.subtleCrypto = window.crypto?.subtle;
+    if (!this.subtleCrypto) {
+      throw new Error('SubtleCrypto API is not available in this environment.');
+    }
+  }
+
+  /**
+   * Perform decryption using AES based V1 algorithm.
+   * 
+   * string: the encrypted string (base64 encoded)
+   * password: the password used for encryption
+   * salt: the base64 encoded salt used
+   */
+  public async decrypt(token: string, password: string, salt: string): Promise<string> {
+    try {
+
+      if (!token) {
+          throw new Error("Invalid token");
+      }
+
+      const tokenBytes = this.base64UrlDecode(token);
+
+      // Extract token components
+      const version = tokenBytes[0];
+      if (version !== 0x80) {
+        // console.log("Incorrect Version: ", version);
+        throw new Error('Invalid version');
+      }
+
+      const timestamp = tokenBytes.slice(1, 9);
+      const iv = tokenBytes.slice(9, 25);
+      const ciphertext = tokenBytes.slice(25, -32);
+      const hmacFromToken = tokenBytes.slice(-32);
+
+      // Derive the key and split it into HMAC and AES keys
+      const fullKey = await this.deriveKey(password, salt);
+      const { hmacKey, aesKey } = await this.splitKey(fullKey);
+
+      // Compute HMAC over version + timestamp + IV + ciphertext
+      const hmacInput = tokenBytes.slice(0, -32);
+      const computedHmac = new Uint8Array(await this.subtleCrypto.sign('HMAC', hmacKey, hmacInput));
+
+      // Validate HMAC
+      if (!computedHmac.every((byte, i) => byte === hmacFromToken[i])) {
+        throw new Error('Invalid HMAC. Token has been tampered with!');
+      }
+
+      // Decrypt the ciphertext
+      const decrypted = await this.subtleCrypto.decrypt(
+        {
+          name: 'AES-CBC',
+          iv: iv,
+        },
+        aesKey,
+        ciphertext
+      );
+
+      // Convert decrypted data to UTF-8 string
+      const decoder = new TextDecoder();
+      return decoder.decode(decrypted);
+    } catch (err) {
+      console.log("Error in decrypt:", err);
+      throw err;
+    }
+  }
+
+
+  private async deriveKey(password: string, salt: string, iterations: number=10000): Promise<CryptoKey> {
+    const encoder = new TextEncoder();
+    const keyMaterial = await this.subtleCrypto.importKey(
+      "raw",
+      encoder.encode(password),
+      "PBKDF2",
+      false,
+      ["deriveKey"]
+    );
+
+    return this.subtleCrypto.deriveKey(
+      {
+        name: "PBKDF2",
+        hash: "SHA-256",
+        salt: encoder.encode(salt),
+        iterations: iterations,
+      },
+      keyMaterial,
+      { name: "AES-CBC", length: 256 },
+      true, // Allow export of the derived key (req for splitting)
+      ["encrypt", "decrypt"]
+    );
+  }
+
+
+  // Split the full key into HMAC and AES keys
+  private async splitKey(fullKey: CryptoKey): Promise<{ hmacKey: CryptoKey; aesKey: CryptoKey }> {
+    const rawKey = new Uint8Array(await this.subtleCrypto.exportKey('raw', fullKey));
+
+    // Split the key into HMAC (first 16 bytes) and AES (last 16 bytes)
+    const hmacKey = await this.subtleCrypto.importKey(
+      'raw',
+      rawKey.slice(0, 16),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign', 'verify']
+    );
+
+    const aesKey = await this.subtleCrypto.importKey(
+      'raw',
+      rawKey.slice(16),
+      { name: 'AES-CBC' },
+      false,
+      ['encrypt', 'decrypt']
+    );
+
+    return { hmacKey, aesKey };
+  }
+
+
+  // Decode Base64 URL-safe strings
+  private base64UrlDecode(base64: string): Uint8Array {
+    // assumes URL safe encoding that has + in place of - and _ in place of /
+    const base64String = base64.replace(/-/g, '+').replace(/_/g, '/');
+    const decodedString = atob(base64String);
+    return new Uint8Array([...decodedString].map(c => c.charCodeAt(0)));
+  }
+
+}

package/src/dome-sdk.ts

@@ -0,0 +1,778 @@
+import pkg from "../package.json";
+
+import { generateUUID, getNameString } from './utils'
+import { CryptoA01 } from './crypto'
+
+// Enum defining message types sent from the viewer to the parent application
+export enum ViewerMessageType {
+  CONNECTION_SUCCESS = "CONNECTION_SUCCESS",
+  INIT = "INIT",              // Indicates the app is initialized
+  REQUEST_SAVE = "REQUEST_SAVE",        // Request to save data in the parent
+  REQUEST_CLOSE = "REQUEST_CLOSE",      // Request to save data in the parent
+  REQUEST_INITIAL_DATA = "REQUEST_INITIAL_DATA", // Request to load initial data from the parent
+  SET_DIRTY = "SET_DIRTY",              // Indicates the app has unsaved changes
+  SEND_CLOSE = "SEND_CLOSE",            // Signals the app is ready to close
+  SEND_EXCEPTION = "SEND_EXCEPTION"     // Sends an exception event to parent
+}
+
+// Enum defining message types sent from the parent application to the embedded app
+enum ClientMessageType {
+  CONNECT = "CONNECT",
+  REQUEST_CLOSE = "REQUEST_CLOSE",      // Requests the app to close
+  REQUEST_SAVE = "REQUEST_SAVE",        // Requests the app for data to be saved
+  SAVE_ERROR = "SAVE_ERROR",            // Sends status of the save event
+  SAVE_SUCCESS = "SAVE_SUCCESS",        // Sends status of the save event
+  DATA_CHANGE = "DATA_CHANGE",
+  INIT_ACK = "INIT_ACK",
+  ERROR = "ERROR",
+  REFRESH = "REFRESH",
+}
+
+
+// Interface defining the structure of a message from the parent
+interface ClientMessageEvent {
+  type: ClientMessageType;              // Message type
+  data: any;                            // Payload data for the message
+}
+
+interface SaveStatusData {
+  status: 'success' | 'error';
+  message: string;
+}
+
+// Interface defining handlers for different message types received from the parent
+export interface ViewerEventHandler {
+  onInitialData: (data: { doc: Document, ui: UiProps, isNewFile: boolean, perms: any, config?: Record<string, any> }) => void;
+  onDataChange?: (data: { doc: Document, perms: any, userConsent: "override" | null }) => void;
+  onCloseRequest: () => void;
+  onSaveRequest: () => void;
+};
+
+// Interface defining the structure for the doc object
+export interface Document {
+  data: any;
+  name: string;
+  type: string;
+}
+
+// Interface defining the UI properties
+export interface UiProps {
+  theme: string;
+}
+
+const ALLOWED_ORIGINS = new Set(getAllowedOrigins());
+
+
+function getAllowedOrigins(): string[] {
+  if (typeof window === 'undefined') return [];
+
+  return [
+    window.location.origin,
+    'https://dome.so',
+    'https://spaces.intouchapp.com/',
+    'http://localhost:4200',
+    'http://localhost:4201',
+    'null',
+  ];
+}
+
+/**
+ * DomeEmbeddedAppSdk:
+ * Base SDK class providing methods to send messages to the parent application.
+ */
+class DomeEmbeddedAppSdk {
+  private readonly targetOrigin: string = "*";
+  protected isAppReady: boolean = false;
+  protected port2: MessagePort | null = null;
+  private platform: "android" | "ios" | "web" | "unknown" = "unknown"; // Store detected platform
+
+  constructor() {
+    this.detectPlatform();
+  }
+
+
+  /**
+   * Detects the platform (iOS, Android, or Web) and saves it.
+   */
+  private detectPlatform(): void {
+    if (typeof window.AndroidBridge !== "undefined") {
+      this.platform = "android";
+    } else if (typeof window.webkit !== "undefined") {
+      this.platform = "ios";
+    } else {
+      this.platform = "web";
+    }
+
+    console.debug(`Detected platform: ${this.platform}`);
+  }
+
+
+  /**
+  * Method to send messages to the parent application.
+  * Ensures the parent window exists and sends a structured message with type and data.
+  * @param type - The type of message being sent
+  * @param data - (Optional) payload data for the message
+  */
+  protected sendMessage(type: ViewerMessageType | CardMessageType, data?: any): void {
+    const message = { type, data: data ?? null };
+
+    switch (this.platform) {
+      case "android":
+        window.AndroidBridge?.sendMessage(JSON.stringify(message));
+        break;
+
+      case "ios":
+        if (window?.webkit?.messageHandlers) {
+          window.webkit?.messageHandlers.appHandler.postMessage(JSON.stringify(message));
+        } else {
+          console.error("webkit.messageHandlers not found")
+        }
+        break;
+
+      case "web":
+        if (this.port2) {
+          this.port2.postMessage(message);
+        } else {
+          console.error("Web connection is not established.");
+        }
+        break;
+
+      default:
+        console.error("Unsupported platform, cannot send message.");
+        break;
+    }
+
+    console.debug(`Sent message to ${this.platform}:`, message);
+  }
+
+  /**
+   * Notifies the parent application that the app is ready, if it hasn’t already.
+   */
+  protected sendAppInit(): void {
+    if (!this.isAppReady) {
+      this.isAppReady = true;
+      this.sendMessage(ViewerMessageType.INIT, { sdk: { ver: pkg.version } })
+    }
+  }
+
+  /**
+   * Safely invokes a function from the handler object if it exists.
+   * and logs a warning if the handler is not provided for the given message type.
+   *
+   * @param eventName - Name of the event method to be invoked from the handler.
+   * @param handlerObj - The handler object that contains the message handling methods.
+   * @param data - (Optional) The data to be passed to the handler function if invoked.
+   */
+  protected safeInvoke<T extends ViewerEventHandler | CardEventHandler>(eventName: keyof T, handlerObj: T, data?: any): void {
+    const handler = handlerObj[eventName];
+
+    if (typeof handler === 'function') {
+      handler(data);
+    } else {
+      console.warn(`Handler for '${String(eventName)}' is not defined.`);
+    }
+  }
+
+
+  // Sets up connection with iframe parent using message channel
+  // Call this once only in the lifetime. Should be called
+  // _before_ iFrame's onLoad is called (otherwise messaging will
+  // not be setup)
+  protected setupParentConnection(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      switch (this.platform) {
+        case "android":
+          window.receiveFromAndroid = (message: { type: string; data: any }) => {
+            console.debug("Message received from Android:", message);
+            this.handleMessage(message.type, message.data);
+          };
+          resolve();
+          break;
+
+        case "ios":
+          window.receiveFromIOS = (message: { type: string; data: any }) => {
+            console.debug("Message received from iOS:", message);
+            this.handleMessage(message.type, message.data);
+          };
+          resolve();
+          break;
+
+        case "web":
+          if (this.port2) {
+            console.warn("Connection already established. Skipping reinitialization.");
+            resolve();
+          }
+
+          const handleMessage = (event: MessageEvent) => {
+            const { type } = event.data || {};
+
+            if (type !== ClientMessageType.CONNECT) return;
+
+            if (event.ports && event.ports.length > 0) {
+              this.port2 = event.ports[0];
+              this.port2.onmessage = (e) => this.handlePortMessage(e);
+              window.removeEventListener("message", handleMessage); // Cleanup
+              this.notifyConnectionSuccess();
+              resolve();
+            }
+          };
+
+          // Listen for browser-based `message` events
+          window.addEventListener("message", handleMessage);
+          break;
+
+        default:
+          console.error("Unknown platform.");
+          reject("Unknown platform");
+      }
+    });
+  }
+
+
+  // Send CONNECTION_SUCCESS message to parent
+  private notifyConnectionSuccess(): void {
+    this.sendMessage(ViewerMessageType.CONNECTION_SUCCESS);
+  }
+
+  // Handle messages coming over message channel port
+  private handlePortMessage(event: MessageEvent) {
+    const { type, data } = event.data || {};
+    if (!type) return;
+
+    // Delegate to subclass-specific message handler
+    this.handleMessage(type, data);
+  }
+
+  // Common method for handling messages to be implemented by sub-classes
+  protected handleMessage(type: string, data: any): void {
+    throw new Error("Subclasses must implement handleMessage.");
+  }
+
+}
+
+/**
+ * ViewerSdk:
+ * A subclass of DomeEmbeddedAppSdk specifically for document viewer applications.
+ * It includes additional methods and properties to manage app interactions.
+ */
+export class ViewerSdk extends DomeEmbeddedAppSdk {
+
+  private static instance: ViewerSdk;           // Singleton instance of ViewerSdk
+  private static initialized = false;
+  private handler: ViewerEventHandler | null = null;              // Handler instance for client messages
+  private pendingRequests: Map<string, (status: SaveStatusData) => void> = new Map();
+  private pendingInitAck: unknown | null = null;
+
+
+  private constructor() {
+    super();
+  }
+
+
+  /**
+   * Static initialization method to get or create the singleton instance of ViewerSdk.
+   * Allows setting the handler during initialization.
+   * @param handler - (Optional) Custom handler for different message types
+   * @returns The singleton ViewerSdk instance
+   */
+  static init(handler?: ViewerEventHandler): ViewerSdk {
+    console.debug("init called", handler && "with handler");
+    // Prevent reinitialization if already initialized
+    if (ViewerSdk.initialized) {
+      console.warn("ViewerSdk is already initialized. Skipping initialization.");
+      return ViewerSdk.instance;
+    }
+
+    if (!ViewerSdk.instance) {
+      ViewerSdk.instance = new ViewerSdk();
+
+      // Initialize parent communication - REQUIRED!
+      ViewerSdk.instance.setupParentConnection()
+        .then(() => {
+          try {
+            // Connection established with parent
+            ViewerSdk.instance.initializeViewerSdk();
+          } catch (err) {
+            console.error("Error in initializeViewerSdk:", err);
+          }
+        })
+        .catch((err: any) => {
+          console.error("init: Error setting up parent connection!", err);
+          console.trace("called from:")
+        });
+    }
+
+    if (handler) {
+      ViewerSdk.instance.setHandler(handler); // Set handler if provided during initialization
+    }
+
+    // Mark as initialized
+    ViewerSdk.initialized = true;
+
+    return ViewerSdk.instance;
+  }
+
+
+  /**
+   * Method to set or update the handler object.
+   * @param handler - Custom handler for different message types
+   */
+  setHandler(handler: ViewerEventHandler): void {
+    this.handler = handler;
+
+    // If INIT_ACK message was received and stored, process it now
+    if (this.pendingInitAck) {
+      console.debug("Processing pending INIT_ACK message after handler is set.");
+      this.safeInvoke("onInitialData", this.handler, this.pendingInitAck);
+      this.pendingInitAck = null; // Clear the stored message
+    }
+  }
+
+
+  /**
+   * Checks if the given permissions string allows reading.
+   * @param perms - The permissions string.
+   * @returns - True if the permission string includes read access.
+   */
+  canRead(perms?: string): boolean {
+    return !!perms?.includes('r');
+  }
+
+  /**
+   * Checks if the given permissions string allows writing.
+   * @param perms - The permissions string.
+   * @returns - True if the permission string includes write access.
+   */
+  canWrite(perms?: string): boolean {
+    return !!perms?.includes('w') || !!perms?.includes('*');
+  }
+
+
+  // Initializes the viewer SDK, setting up the message listener and sending an initial "ready" message.
+  initializeViewerSdk() {
+    console.debug("initializing viewer sdk");
+    this.sendAppInit();
+  }
+
+  /**
+   * Sends a request to the parent application to retrieve initial data.
+   */
+  requestInitialData(): void {
+    this.sendMessage(ViewerMessageType.REQUEST_INITIAL_DATA);
+  }
+
+
+  /**
+   * Sends a request to the parent application to save data.
+   * @param doc - payload data to be saved
+   * @param isDataDirty - Boolean indicating indicating modified data
+   */
+  requestSave(doc: Document, isDataDirty: boolean): Promise<SaveStatusData> {
+    const requestId = generateUUID();
+
+    // Send save request with the generated requestId
+    this.sendMessage(ViewerMessageType.REQUEST_SAVE, { doc, isDataDirty, requestId });
+
+    return new Promise((resolve, reject) => {
+
+      this.pendingRequests.set(requestId, resolve);
+      this.pendingRequests.set(requestId + '_reject', reject);
+
+      // Timeout if the parent fails to respond in time
+      setTimeout(() => {
+        if (this.pendingRequests.has(requestId)) {
+          this.pendingRequests.delete(requestId);
+          this.pendingRequests.delete(requestId + '_reject');
+        }
+      }, 30000);
+    });
+  }
+
+  private handleOnSave(data: { requestId: string, status: "error" | "success", message: string }) {
+    const { requestId, status, message } = data;
+
+    // Check if we have a pending request for this requestId
+    const resolve = this.pendingRequests.get(requestId);
+    const reject = this.pendingRequests.get(requestId + '_reject');
+
+    if (resolve) {
+      // If status is "error", reject the promise, otherwise resolve it
+      if (status === "error") {
+        reject?.({ status, message });
+      } else {
+        resolve({ status, message });
+      }
+
+      // Clean up
+      this.pendingRequests.delete(requestId);
+      this.pendingRequests.delete(requestId + '_reject');
+    }
+  }
+
+
+  /**
+   * Sets the viewer's "dirty" state, indicating modified data.
+   * @param isDirty - Boolean indicating whether the viewer has modified data
+   */
+  setDirty(isDirty: boolean) {
+    this.sendMessage(ViewerMessageType.SET_DIRTY, isDirty);
+  }
+
+  /**
+   * Sends a close request to the parent, with information on whether the data is dirty.
+   * @param doc - Latest document data
+   * @param isDataDirty - Boolean indicating indicating modified data
+   */
+  sendClose(doc: Document, isDataDirty: boolean): void {
+    this.sendMessage(ViewerMessageType.SEND_CLOSE, { doc, isDataDirty });
+  }
+
+  /**
+   * Sends an exception to parent.
+   * @param error - An error object with name and message or an error string
+   */
+  sendException(error: { name?: string, message: string } | string): void {
+    this.sendMessage(ViewerMessageType.SEND_EXCEPTION, error);
+  }
+
+
+  // Sets up the message listener for viewer to receive messages from the parent.
+  protected handleMessage(type: ClientMessageType, data: any): void {
+
+    console.debug("handleMessage called for:", type, "with data:", data);
+
+    if (!this.handler) {
+      if (type === ClientMessageType.INIT_ACK) {
+        console.warn("Handler not set. Storing INIT_ACK message for later processing.");
+        this.pendingInitAck = data; // Save INIT_ACK message
+      } else {
+        console.error("Message handler not found for type:", type);
+      }
+      return;
+    }
+
+    switch (type) {
+      case ClientMessageType.INIT_ACK:
+        this.safeInvoke("onInitialData", this.handler, data);
+        break;
+      case ClientMessageType.DATA_CHANGE:
+        this.safeInvoke("onDataChange", this.handler, data);
+        break;
+      case ClientMessageType.REQUEST_CLOSE:
+        this.safeInvoke("onCloseRequest", this.handler);
+        break;
+      case ClientMessageType.REQUEST_SAVE:
+        this.safeInvoke("onSaveRequest", this.handler);
+        break;
+      case ClientMessageType.SAVE_SUCCESS:
+        this.handleOnSave(data);
+        break;
+      case ClientMessageType.SAVE_ERROR:
+        this.handleOnSave(data);
+        break;
+      default:
+        console.warn(`No handler found for message type: ${type}`);
+    }
+  }
+
+}
+
+// Card SDK
+
+// Enum defining message types sent from the card to the parent application
+export enum CardMessageType {
+  APP_READY = "APP_READY",              // Indicates the app is ready to be interacted with
+  INIT = "INIT"       // Event to send the init key to the viewer
+}
+
+export interface CardEventHandler {
+  onInit: (data: any) => void;
+  onError: (data: { error_code: string | number, message: string, data: any }) => void;
+  onRefreshRequest: (data: any) => void;
+};
+
+/**
+ * Use CardSdk to create webapp cards
+ */
+export class CardSdk extends DomeEmbeddedAppSdk {
+  private static instance: CardSdk;           // Singleton instance of CardSdk
+  private handler: CardEventHandler | null = null;              // Handler instance for client messages
+  private cryptoA01: any;
+
+  public dataStore: any;
+
+  private constructor() {
+    super();
+    this.cryptoA01 = new CryptoA01();
+    console.debug("CardSdk::constructor: done");
+  }
+
+  /**
+   * Static initialization method to get or create the singleton instance of CardSdk.
+   * @param secret - The card developer secret key
+   * @param handler - (Optional) Handler for different events emitted by the SDK
+   * @returns The singleton CardSdk instance
+   */
+  public static async init(secret: string, handler?: CardEventHandler, options?: { devMode?: boolean }): Promise<CardSdk> {
+    try {
+      console.debug("CardSdk::init");
+
+      if (!CardSdk.instance) {
+        CardSdk.instance = new CardSdk();
+        // Initialize parent communication - REQUIRED!
+        CardSdk.instance.setupParentConnection()
+          .then(() => {
+            // Connection established with parents..
+
+            // Initialize SDK in async
+            CardSdk.instance.initializeCardSdk(secret);
+          })
+          .catch((err: any) => {
+            console.error(err);
+          })
+      } else {
+        return CardSdk.instance;
+      }
+
+      // Setup handlers
+      if (handler) {
+        CardSdk.instance.setHandler(handler); // Set handler if provided during initialization
+      }
+
+      return CardSdk.instance;
+
+    } catch (err) {
+      console.error("CardSdk: Unrecoverable error in init", err);
+      throw err;
+    }
+  }
+
+  /**
+   * Method to set or update the handler object.
+   * @param handler - Custom handler for different message types
+   */
+  public setHandler(handler: CardEventHandler): void {
+    this.handler = handler;
+  }
+
+  // Function to initialize SDK after instance is created
+  private async initializeCardSdk(secret: any) {
+    let TAG = "CardSdk::initializeCardSdk:";
+    try {
+      console.debug(TAG, "enter");
+
+      if (!secret) {
+        throw new Error("Invalid secret");
+      }
+
+      // Get data from HTML
+      const data_af1 = (window as any).IT_DATA_AF1;
+
+      if (!data_af1) {
+        console.error(TAG, "No data");
+        throw new Error('No data');
+      }
+
+      const url = window.location.href;
+      console.debug(TAG, "url:", url);
+      const urlObject = new URL(url)
+      const segments = urlObject.pathname.split('/').filter(segment => segment);
+      let url_part;
+      if (segments.length > 1) {
+        url_part = segments[segments.length - 2];
+      } else if (segments.length == 1) {
+        url_part = segments[0];
+      } else {
+        throw new Error('Invalid URL');
+      }
+      const ss = url_part.split('').reverse().join('').substring(4, 25);
+      console.debug(TAG, "ss:", ss);
+      if (!ss) {
+        throw new Error('Cannot decrypt (1)');
+      }
+
+      const decData = await this.cryptoA01.decrypt(data_af1, secret, ss)
+      try {
+        const dataFromServer = JSON.parse(decData);
+        console.debug("CardSdk: dataFromServer:", dataFromServer);
+        if (!dataFromServer.ite) {
+          throw new Error("Invalid data");
+        }
+
+        this.dataStore = {
+          'denc': dataFromServer.d,
+          'kw2': dataFromServer.kw2
+        };
+
+        CardSdk.instance.sendInit(dataFromServer.ite);
+
+      } catch (err) {
+        console.error("Initial Decryption failed (2):", err);
+        throw err;
+      }
+
+    } catch (err: any) {
+      console.error(TAG, "Init failed:", err);
+      this.sendEventError('init_failed', err.message);
+    }
+  }
+
+  private async sendInit(token: string) {
+    this.sendMessage(CardMessageType.INIT, { 'token': token, sdk: { ver: pkg.version } });
+  }
+
+  // Sets up the message listener for cards to receive messages from the parent.
+  protected handleMessage = (type: ClientMessageType, data: any) => {
+
+    if (!this.handler) {
+      throw new Error("Message handler not found!");
+    }
+
+    switch (type) {
+      case ClientMessageType.INIT_ACK:
+        // Parent sent INIT_ACK
+        console.debug("CardSdk: INIT_ACK received");
+
+        this.dataStore.kw1 = data.key_wa1;
+        this.dataStore.iuid = data.iuid;
+
+        try {
+          this.cryptoA01.decrypt(this.dataStore.denc, data.key_wa1 + this.dataStore.kw2, data.iuid)
+            .then((decData: any) => {
+              console.debug("CardSdk: INIT_ACK: decrypted data ", decData);
+              const decryptedData = JSON.parse(decData);
+              if (this.handler) this.safeInvoke("onInit", this.handler, { ...decryptedData, ui: data.ui });
+              // no need for orig enc data.. free to delete it
+              delete this.dataStore.denc;
+            })
+            .catch((err: any) => {
+              console.error("Final decrypt error", err);
+              throw err;
+            });
+        } catch (err: any) {
+          console.error("Decryption failed!", err);
+          this.sendEventError('dec2_failed', err.message);
+        }
+
+        break;
+
+      case ClientMessageType.ERROR:
+        // Parent sent an ERROR
+        this.safeInvoke("onError", this.handler, data);
+        break;
+
+      case ClientMessageType.REFRESH:
+        // Asking for UI refresh
+        this.safeInvoke("onRefreshRequest", this.handler, data);
+        break;
+
+      default:
+        console.warn(`No handler found for message type: ${type}`);
+    }
+  };
+
+  /**
+   * Converts a JavaScript object to a JSON file.
+   */
+  private async convertToJsonFile(object: any, type = 'json', fileName = 'file.json'): Promise<File> {
+    const jsonString = JSON.stringify(object, null, 2);
+    const jsonFileType = 'application/json';
+    const blob = new Blob([jsonString], { type: jsonFileType });
+
+    return new File([blob], fileName, { type: jsonFileType });
+  }
+
+  /**
+   * Converts data to a file.
+   */
+  private async convertToFile(data: any, fileName: string, fileType: 'json' | 'blob' = 'json', fileMimeType?: string): Promise<File> {
+    if (fileType === 'json') {
+      return this.convertToJsonFile(data, 'json', fileName);
+    } else {
+      const blob = new Blob([data], fileMimeType ? { type: fileMimeType } : undefined);
+      return new File([blob], fileName, { type: blob.type });
+    }
+  }
+
+  /**
+   * Get document associated with the current card
+   */
+  public async getCardDocument(documentIuid?: string, cardIuid?: string): Promise<any> {
+    const fetchUrl = `/api/v1/${documentIuid}/`;
+    const createUrl = `/api/v1/documents/create_for/${cardIuid}`;
+
+    // Helper to handle response content
+    const parseResponse = async (response: Response) => {
+      const contentType = response.headers.get('Content-Type') || '';
+      if (contentType.includes('application/json')) return response.json();
+      if (contentType.includes('text/')) return response.text();
+      throw new Error(`Unsupported response type: ${contentType}`);
+    };
+
+    try {
+      // Try to fetch the document
+      const fetchResponse = await fetch(fetchUrl, { method: 'GET' });
+      if (fetchResponse.ok) return parseResponse(fetchResponse);
+
+      if (fetchResponse.status === 404) {
+        // Create the document if not found
+        const createResponse = await fetch(createUrl, { method: 'POST' });
+        if (!createResponse.ok) throw new Error(`Failed to create document: ${createResponse.status}`);
+        return parseResponse(createResponse);
+      }
+
+      throw new Error(`Failed to fetch document: ${fetchResponse.status}`);
+    } catch (error) {
+      console.error('Error handling document:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Uploads a file to the specified document IUID endpoint.
+   */
+  public async saveDocument(fileObj: any, documentIuid: string): Promise<Response> {
+    // Convert the fileObj to a File
+    const { name, type } = fileObj;
+
+    const file = await this.convertToFile(fileObj, name, type);
+
+    // Construct the full URL
+    const apiUrl = `/api/v1/${documentIuid}/`;
+
+    // Create FormData and append the file
+    const formData = new FormData();
+    formData.append('file', file);
+
+    // Make the POST request
+    return fetch(apiUrl, {
+      method: 'PUT',
+      body: formData,
+    });
+  }
+
+
+  // Send event on error (clients will get "onError" event)
+  private sendEventError(error_code: string, message: string, data: any = undefined) {
+    let data_to_send = {
+      'message': message,
+      'error_code': error_code,
+      'data': data
+    }
+    if (this.handler) this.safeInvoke("onError", this.handler, data_to_send);
+  }
+
+
+  // Get username string from user object received from parent
+  public getUsername(userObj: any): string {
+    const nameObj = userObj?.name;
+
+    if (nameObj && Object.values(nameObj).some(value => value)) {
+      return getNameString(nameObj);
+    }
+
+    return '';
+  }
+
+}
+

package/src/index.ts

@@ -0,0 +1,9 @@
+// Class imports
+export { ViewerSdk, CardSdk } from "./dome-sdk";
+export { CryptoA01 } from "./crypto";
+
+// Viewer Type imports
+export type { ViewerMessageType, ViewerEventHandler, Document, UiProps } from "./dome-sdk";
+
+// Card Type imports
+export type { CardMessageType, CardEventHandler } from "./dome-sdk";

package/src/types/globals.d.ts

@@ -0,0 +1,20 @@
+interface AndroidBridgeType {
+  postMessage(message: any): void;
+  sendMessage(message: any): void;
+}
+
+interface WebkitType {
+  messageHandlers: {
+    [handlerName: string]: {
+      postMessage(message: any): void;
+    };
+  };
+}
+
+interface Window {
+  AndroidBridge?: AndroidBridgeType;
+  webkit?: WebkitType;
+  app?: any;
+  receiveFromAndroid: (message: { type: string, data: any }) => void;
+  receiveFromIOS: (message: { type: string, data: any }) => void;
+}

package/src/utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Helper function to generate a unique requestId (UUID).
+ * This uses the browser's crypto API for random UUID generation.
+ */
+export function generateUUID(): string {
+  // If in a browser environment with crypto support (modern browsers)
+  if (typeof window !== 'undefined' && window.crypto && window.crypto.randomUUID) {
+    return window.crypto.randomUUID();
+  }
+
+  // Fallback for non-browser environments (e.g., Node.js)
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  // Fallback for environments without crypto support
+  throw new Error('UUID generation is not supported in this environment');
+}
+
+/**
+ * Helper function to get username from user object
+ * @param nameObj the user object
+ */
+export function getNameString(nameObj: any): string {
+  const { prefix = '', given = '', middle = '', family = '', suffix = '' } = nameObj || {};
+  const fullname = [prefix, given, middle, family, suffix].filter(namePart => namePart).join(' ');
+
+  return fullname.trim();
+}
+

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "lib": ["es2020", "dom"],
+  },
+  "ts-node": {
+    "compilerOptions": {
+      "module": "CommonJS"
+    }
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}

package/webpack.config.ts

@@ -0,0 +1,35 @@
+import path from 'path';
+import webpack from 'webpack';
+
+const config: webpack.Configuration =  {
+  mode: "production",
+  entry: "./src/index.ts",
+  output: {
+    path: path.resolve(__dirname, "dist"),
+    clean: true,
+    filename: "index.js",
+    library: 'domeSdk',
+    libraryTarget: 'umd',
+    globalObject: "this",
+  },
+  resolve: {
+    extensions: [".ts", ".js"],
+  },
+  module: {
+    rules: [
+      {
+        test: /\.ts$/,
+        use: "ts-loader",
+        exclude: /node_modules/,
+      },
+    ],
+  },
+  optimization: {
+    splitChunks: {
+      chunks: "all",
+    },
+  },
+  devtool: "source-map",
+};
+
+export default config;