dome-embedded-app-sdk 0.4.3 → 0.5.0

package/docs/card-sdk.md

@@ -1,162 +1,162 @@
-# Card SDK Guide
-
-The Card SDK powers embedded card experiences inside a dome.
-
-## Install
-
-```bash
-npm install dome-embedded-app-sdk
-```
-
-## Starter projects
-
-- React card starter: <https://github.com/InTouchSO/card-react_starter>
-- Angular card starter: <https://github.com/InTouchSO/card-angular_starter>
-
-## Initialize
-
-```JavaScript
-import { CardSdk, getKeyFromBlob } from "dome-embedded-app-sdk";
-
-const my_card_decryption_blob = {...};
-
-CardSdk.init(getKeyFromBlob(my_card_decryption_blob), {
-  onInit: (data) => {
-    console.debug("onInit payload", data);
-  },
-  onInitError: ({ error_code, message }) => {
-    console.error("Initialization error", error_code, message);
-  }
-  onError: ({ error_code, message }) => {
-    console.error("Card error", error_code, message);
-  }
-}).then((sdk) => this.sdk = sdk);
-```
-
-`onInit` receives the user payload, permissions, role, container info, and UI metadata.
-
-### onInit payload
-
-The payload is a `CardInitData` object with these commonly used fields:
-
-- `api_token`: token for authenticated API calls.
-- `iuid`: card instance identifier.
-- `user`: current user profile (see `CardUser`), includes `name`, `photo`, `organization`, and `getFullName()`.
-- `perms_v2`: permission map keyed by role abbreviation.
-- `role`: role metadata for the current user.
-- `container`: container metadata (includes `iuid`).
-- `ui`: UI metadata including `ui.theme`
-
-Use the exported `CardInitData` and `CardUser` types for full payload typing.
-
-## Events
-
-- `onInit(data)`: Fired after the card payload is decrypted.
-- `onInitError(data)`: Fired when initialization fails.
-- `onError(data)`: Fired for runtime errors.
-
-## Card permissions
-
-```JavaScript
-import { CardPermission, cardPermission } from "dome-embedded-app-sdk";
-```
-
-- `CardPermission`: enum of permission codes (`READ`, `WRITE`, `FORWARD`, `SHARE`, `DOWNLOAD`).
-- `cardPermission`: convenience alias for the enum.
-- `hasPerm(permission)`: Check for a specific `CardPermission`.
-- `canRead()` / `canWrite()`: Convenience permission checks.
-
-## CardFS error codes
-
-```JavaScript
-import { CardFsErrorCode } from "dome-embedded-app-sdk";
-```
-
-`CardFsErrorCode` provides standardized error codes for cardFS operations:
-`NO_INTERNET`, `NO_PERMISSION`, `NOT_FOUND`, `SERVER_ERROR`, `TIMEOUT`, `INVALID_REQUEST`, `UNKNOWN`.
-
-## CardFS (file storage)
-
-`cardFS` is a high-level API for reading, writing, deleting, and listing files. Each method either returns a promise or uses handlers for streaming updates.
-
-### Understanding `is_stale`, `is_complete`, `is_dirty`
-
-- `is_stale`: the payload may be from cache and could be outdated; a fresh payload can arrive later.
-- `is_complete`: no more updates are expected for this request (final chunk or last page).
-- `is_dirty`: the file/listing has pending local changes that aren’t yet synchronized.
-
-#### Common scenarios
-
-- **Cached read**: `is_stale: true`, `is_complete: true` (cached result only).
-- **Cached + live read**: first payload `is_stale: true`, then a later payload `is_stale: false`.
-- **Streaming read/list**: intermediate updates `is_complete: false`, final update `is_complete: true`.
-
-### Read
-
-```JavaScript
-sdk.cardFS.read("my-journal.json", {
-  next: (payload) => {
-    console.debug("Read payload", payload);
-  },
-  error: (err) => {
-    console.error("Read error", err);
-  }
-});
-```
-
-- `read(name, handler, allowStale?)`
-- `readById(iuid, handler, allowStale?)`
-
-`read` and `readById` fetch a file by name or id and stream updates through the handler until `is_complete` is true.
-
-`payload` includes `object`, `data`, `is_stale`, `is_complete`, and `is_dirty` flags.
-
-### Write
-
-```JavaScript
-import { CardFsFileType } from "dome-embedded-app-sdk";
-
-sdk.cardFS.write("my-journal.json", { text: "Hello" }, CardFsFileType.JSON, (update) => {
-  console.debug("Upload status", update.status, update.progress);
-});
-```
-
-- `write(name, fileData, fileType, onUpdate?)`
-- `writeById(iuid, fileData, fileType, onUpdate?)`
-
-`write` and `writeById` upload new data for a file and optionally report progress through `onUpdate`.
-
-`fileType` can be `CardFsFileType.JSON`, `CardFsFileType.TEXT`, or `CardFsFileType.BINARY`.
-
-`onUpdate` receives `{ status, progress, uploaded_bytes }` when available.
-
-### Delete
-
-- `delete(name, onUpdate?)`
-- `deleteById(iuid, onUpdate?)`
-
-`delete` and `deleteById` remove a file by name or id and optionally report progress.
-
-### List
-
-When listing folders, the folder name should not start with `/` and must end with `/` (for example: `notes/`).
-
-```JavaScript
-sdk.cardFS.list("notes/", {
-  next: (payload) => {
-    console.debug("Folder listing", payload.documents);
-  },
-  error: (err) => {
-    console.error("List error", err);
-  }
-});
-```
-
-`list(folderName, handler)` yields the folder data with `documents`, `is_stale`, and `is_complete` flags.
-
-`list` retrieves a folder listing and streams page updates until the final page is reached.
-
-## Utilities
-
-- `openDeepLink(url)`: Ask the host to open a supported deep link.
-- `getKeyFromBlob(blob)`: Decode a `CardKeyBlob` into the secret string.
+# Card SDK Guide
+
+The Card SDK powers embedded card experiences inside a dome.
+
+## Install
+
+```bash
+npm install dome-embedded-app-sdk
+```
+
+## Starter projects
+
+- React card starter: <https://github.com/InTouchSO/card-react_starter>
+- Angular card starter: <https://github.com/InTouchSO/card-angular_starter>
+
+## Initialize
+
+```JavaScript
+import { CardSdk, getKeyFromBlob } from "dome-embedded-app-sdk";
+
+const my_card_decryption_blob = {...};
+
+CardSdk.init(getKeyFromBlob(my_card_decryption_blob), {
+  onInit: (data) => {
+    console.debug("onInit payload", data);
+  },
+  onInitError: ({ error_code, message }) => {
+    console.error("Initialization error", error_code, message);
+  }
+  onError: ({ error_code, message }) => {
+    console.error("Card error", error_code, message);
+  }
+}).then((sdk) => this.sdk = sdk);
+```
+
+`onInit` receives the user payload, permissions, role, container info, and UI metadata.
+
+### onInit payload
+
+The payload is a `CardInitData` object with these commonly used fields:
+
+- `api_token`: token for authenticated API calls.
+- `iuid`: card instance identifier.
+- `user`: current user profile (see `CardUser`), includes `name`, `photo`, `organization`, and `getFullName()`.
+- `perms_v2`: permission map keyed by role abbreviation.
+- `role`: role metadata for the current user.
+- `container`: container metadata (includes `iuid`).
+- `ui`: UI metadata including `ui.theme`
+
+Use the exported `CardInitData` and `CardUser` types for full payload typing.
+
+## Events
+
+- `onInit(data)`: Fired after the card payload is decrypted.
+- `onInitError(data)`: Fired when initialization fails.
+- `onError(data)`: Fired for runtime errors.
+
+## Card permissions
+
+```JavaScript
+import { CardPermission, cardPermission } from "dome-embedded-app-sdk";
+```
+
+- `CardPermission`: enum of permission codes (`READ`, `WRITE`, `FORWARD`, `SHARE`, `DOWNLOAD`).
+- `cardPermission`: convenience alias for the enum.
+- `hasPerm(permission)`: Check for a specific `CardPermission`.
+- `canRead()` / `canWrite()`: Convenience permission checks.
+
+## CardFS error codes
+
+```JavaScript
+import { CardFsErrorCode } from "dome-embedded-app-sdk";
+```
+
+`CardFsErrorCode` provides standardized error codes for cardFS operations:
+`NO_INTERNET`, `NO_PERMISSION`, `NOT_FOUND`, `SERVER_ERROR`, `TIMEOUT`, `INVALID_REQUEST`, `UNKNOWN`.
+
+## CardFS (file storage)
+
+`cardFS` is a high-level API for reading, writing, deleting, and listing files. Each method either returns a promise or uses handlers for streaming updates.
+
+### Understanding `is_stale`, `is_complete`, `is_dirty`
+
+- `is_stale`: the payload may be from cache and could be outdated; a fresh payload can arrive later.
+- `is_complete`: no more updates are expected for this request (final chunk or last page).
+- `is_dirty`: the file/listing has pending local changes that aren’t yet synchronized.
+
+#### Common scenarios
+
+- **Cached read**: `is_stale: true`, `is_complete: true` (cached result only).
+- **Cached + live read**: first payload `is_stale: true`, then a later payload `is_stale: false`.
+- **Streaming read/list**: intermediate updates `is_complete: false`, final update `is_complete: true`.
+
+### Read
+
+```JavaScript
+sdk.cardFS.read("my-journal.json", {
+  next: (payload) => {
+    console.debug("Read payload", payload);
+  },
+  error: (err) => {
+    console.error("Read error", err);
+  }
+});
+```
+
+- `read(name, handler, allowStale?)`
+- `readById(iuid, handler, allowStale?)`
+
+`read` and `readById` fetch a file by name or id and stream updates through the handler until `is_complete` is true.
+
+`payload` includes `object`, `data`, `is_stale`, `is_complete`, and `is_dirty` flags.
+
+### Write
+
+```JavaScript
+import { CardFsFileType } from "dome-embedded-app-sdk";
+
+sdk.cardFS.write("my-journal.json", { text: "Hello" }, CardFsFileType.JSON, (update) => {
+  console.debug("Upload status", update.status, update.progress);
+});
+```
+
+- `write(name, fileData, fileType, onUpdate?)`
+- `writeById(iuid, fileData, fileType, onUpdate?)`
+
+`write` and `writeById` upload new data for a file and optionally report progress through `onUpdate`.
+
+`fileType` can be `CardFsFileType.JSON`, `CardFsFileType.TEXT`, or `CardFsFileType.BINARY`.
+
+`onUpdate` receives `{ status, progress, uploaded_bytes }` when available.
+
+### Delete
+
+- `delete(name, onUpdate?)`
+- `deleteById(iuid, onUpdate?)`
+
+`delete` and `deleteById` remove a file by name or id and optionally report progress.
+
+### List
+
+When listing folders, the folder name should not start with `/` and must end with `/` (for example: `notes/`).
+
+```JavaScript
+sdk.cardFS.list("notes/", {
+  next: (payload) => {
+    console.debug("Folder listing", payload.documents);
+  },
+  error: (err) => {
+    console.error("List error", err);
+  }
+});
+```
+
+`list(folderName, handler)` yields the folder data with `documents`, `is_stale`, and `is_complete` flags.
+
+`list` retrieves a folder listing and streams page updates until the final page is reached.
+
+## Utilities
+
+- `openDeepLink(url)`: Ask the host to open a supported deep link.
+- `getKeyFromBlob(blob)`: Decode a `CardKeyBlob` into the secret string.

package/docs/viewer-sdk.md

@@ -1,50 +1,50 @@
-# Viewer SDK Guide
-
-The Viewer SDK lets you build custom viewers/editors for documents inside Dome.
-
-## Install
-
-```bash
-npm install dome-embedded-app-sdk
-```
-
-## Initialize
-
-```JavaScript
-import { ViewerSdk } from "dome-embedded-app-sdk";
-
-ViewerSdk.init({
-  onInitialData: ({ doc, ui }) => {
-    console.debug("Initial data", doc, ui);
-  },
-  onDataChange: ({ doc }) => {
-    console.debug("Doc changed", doc);
-  },
-  onCloseRequest: () => {
-    console.debug("Close requested");
-  },
-  onSaveRequest: () => {
-    console.debug("Save requested");
-  }
-});
-```
-
-## Events
-
-- `onInitialData({ doc, ui, isNewFile, perms, config })`: Initial payload for the viewer.
-- `onDataChange({ doc, perms, userConsent })`: Updates when the document changes.
-- `onCloseRequest()`: Parent requests close.
-- `onSaveRequest()`: Parent requests save.
-
-## Permissions
-
-- `canRead(perms)`: Returns true if read is allowed.
-- `canWrite(perms)`: Returns true if write is allowed.
-
-## Viewer actions
-
-- `requestInitialData()`: Ask the host to resend initial data.
-- `requestSave(doc, isDataDirty)`: Ask the host to save and return a status promise.
-- `setDirty(isDirty)`: Notify the host about dirty state.
-- `sendClose(doc, isDataDirty)`: Notify the host to close.
-- `sendException(error)`: Report an exception to the host.
+# Viewer SDK Guide
+
+The Viewer SDK lets you build custom viewers/editors for documents inside Dome.
+
+## Install
+
+```bash
+npm install dome-embedded-app-sdk
+```
+
+## Initialize
+
+```JavaScript
+import { ViewerSdk } from "dome-embedded-app-sdk";
+
+ViewerSdk.init({
+  onInitialData: ({ doc, ui }) => {
+    console.debug("Initial data", doc, ui);
+  },
+  onDataChange: ({ doc }) => {
+    console.debug("Doc changed", doc);
+  },
+  onCloseRequest: () => {
+    console.debug("Close requested");
+  },
+  onSaveRequest: () => {
+    console.debug("Save requested");
+  }
+});
+```
+
+## Events
+
+- `onInitialData({ doc, ui, isNewFile, perms, config })`: Initial payload for the viewer.
+- `onDataChange({ doc, perms, userConsent })`: Updates when the document changes.
+- `onCloseRequest()`: Parent requests close.
+- `onSaveRequest()`: Parent requests save.
+
+## Permissions
+
+- `canRead(perms)`: Returns true if read is allowed.
+- `canWrite(perms)`: Returns true if write is allowed.
+
+## Viewer actions
+
+- `requestInitialData()`: Ask the host to resend initial data.
+- `requestSave(doc, isDataDirty)`: Ask the host to save and return a status promise.
+- `setDirty(isDirty)`: Notify the host about dirty state.
+- `sendClose(doc, isDataDirty)`: Notify the host to close.
+- `sendException(error)`: Report an exception to the host.

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "dome-embedded-app-sdk",
-  "version": "0.4.3",
-  "source": "src/index.ts",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "docs"
-  ],
-  "scripts": {
-    "clean": "node ./scripts/clean-dist.mjs",
-    "build:tsc": "tsc --emitDeclarationOnly",
-    "build:webpack": "webpack --config webpack.config.ts",
-    "build:webpack:experimental": "webpack --config webpack.config.ts --env experimental",
-    "build": "npm run clean && npm run build:tsc && npm run build:webpack",
-    "build:experimental": "npm run clean && npm run build:tsc && npm run build:webpack:experimental",
-    "release": "npm run build && npm publish",
-    "release:experimental": "npm run build:experimental && npm publish --tag experimental",
-    "version:patch": "npm version patch && git push && git push --tags && npm run release",
-    "version:minor": "npm version minor && git push && git push --tags && npm run release",
-    "version:major": "npm version major && git push && git push --tags && npm run release",
-    "version:experimental": "npm version prerelease --preid=experimental && git push && git push --tags && git push origin HEAD:experimental && npm run release:experimental",
-    "test-pack": "npm pack --dry-run",
-    "watch": "webpack --watch"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "dome",
-    "dome-sdk"
-  ],
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "dependencies": {
-    "cbor-x": "^1.6.0"
-  },
-  "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"
-  }
-}
+{
+  "name": "dome-embedded-app-sdk",
+  "version": "0.5.0",
+  "source": "src/index.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "clean": "node ./scripts/clean-dist.mjs",
+    "build:tsc": "tsc --emitDeclarationOnly",
+    "build:webpack": "webpack --config webpack.config.ts",
+    "build:webpack:experimental": "webpack --config webpack.config.ts --env experimental",
+    "build": "npm run clean && npm run build:tsc && npm run build:webpack",
+    "build:experimental": "npm run clean && npm run build:tsc && npm run build:webpack:experimental",
+    "release": "npm run build && npm publish",
+    "release:experimental": "npm run build:experimental && npm publish --tag experimental",
+    "version:patch": "npm version patch && git push && git push --tags && npm run release",
+    "version:minor": "npm version minor && git push && git push --tags && npm run release",
+    "version:major": "npm version major && git push && git push --tags && npm run release",
+    "version:experimental": "npm version prerelease --preid=experimental && git push && git push --tags && git push origin HEAD:experimental && npm run release:experimental",
+    "test-pack": "npm pack --dry-run",
+    "watch": "webpack --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dome",
+    "dome-sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "cbor-x": "^1.6.0"
+  },
+  "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"
+  }
+}