dome-embedded-app-sdk/docs/card-sdk.md

Build Dome cards and document viewers with a single SDK. Cards let you extend a dome with custom functionality, while viewers let you render and edit documents inside Dome.

# 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.