{"_id":"@cmts-dev/carmentis-desk-connect-js","_rev":"3-b3f7fd4197f95ea9337a5070a296f9af","name":"@cmts-dev/carmentis-desk-connect-js","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@cmts-dev/carmentis-desk-connect-js","version":"1.0.0","license":"Apache-2.0","_id":"@cmts-dev/carmentis-desk-connect-js@1.0.0","maintainers":[{"name":"gamarcad","email":"gael.marcadet@carmentis.io"}],"dist":{"shasum":"ff87ca03b60f3ce5d09b4ce4290f2c758b7fcba3","tarball":"https://registry.npmjs.org/@cmts-dev/carmentis-desk-connect-js/-/carmentis-desk-connect-js-1.0.0.tgz","fileCount":8,"integrity":"sha512-QYEuj1Lf7Em5I3yFpefJ/jPvMdSTt90xtzOs+97OePV/Vyk0YKFJ91s9DNhosEUuKG8bGHEUySlcfH90JxiDhA==","signatures":[{"sig":"MEYCIQDIH38WG10c4MaF+Y3o5O6VrjLHhOJbkXNLJBDZqukHzwIhAMk1xurjdBQKm/tG1CkQ6kSoRamtw6Ikj+0P4FeUhLiM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26362},"main":"./dist/index.umd.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.umd.cjs"}},"gitHead":"e9a2627ecf61006d7b345c4d68ab22e512b59398","private":false,"scripts":{"build":"vite build"},"_npmUser":{"name":"gamarcad","email":"gael.marcadet@carmentis.io"},"_npmVersion":"10.9.4","description":"Framework-agnostic JS SDK for connecting web applications to Carmentis Desk","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@cmts-dev/carmentis-relay-client":"^1.2.0","@cmts-dev/carmentis-sdk-json-rpc":"^1.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.0.0","typescript":"^5.5.3","vite-plugin-dts":"^4.5.4","semantic-release":"^24.2.0","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/carmentis-desk-connect-js_1.0.0_1774885281177_0.5331063203711268","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@cmts-dev/carmentis-desk-connect-js","version":"1.1.0","license":"Apache-2.0","_id":"@cmts-dev/carmentis-desk-connect-js@1.1.0","maintainers":[{"name":"gamarcad","email":"gael.marcadet@carmentis.io"}],"dist":{"shasum":"69a403a2ac560e9ff794d20cda9a098f98300c86","tarball":"https://registry.npmjs.org/@cmts-dev/carmentis-desk-connect-js/-/carmentis-desk-connect-js-1.1.0.tgz","fileCount":8,"integrity":"sha512-rNnFI1btDbBOpMTuRlDazF5Y2YuV9bPdA7QNLPXYImqyyUoQp3bR5ukK5YlKN1rhlW5hgp9aBNTFKrpMWDpR0Q==","signatures":[{"sig":"MEQCIEIPA7heZJ69B3k4EnBijsoZuuKBXXQijwvkgd0IObbBAiAuDvceVQA0SldIsT/+1JZXZ5QsEbcRWQXGVaVrB3U6Uw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":338621},"main":"./dist/index.umd.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.umd.cjs"}},"gitHead":"2b3259e1544c94bad81a653d39fac16c385f6ad8","private":false,"scripts":{"build":"vite build"},"_npmUser":{"name":"gamarcad","email":"gael.marcadet@carmentis.io"},"_npmVersion":"10.9.4","description":"Framework-agnostic JS SDK for connecting web applications to Carmentis Desk","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@cmts-dev/carmentis-relay-client":"^1.2.0","@cmts-dev/carmentis-sdk-json-rpc":"^1.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.0.0","typescript":"^5.5.3","vite-plugin-dts":"^4.5.4","semantic-release":"^24.2.0","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/carmentis-desk-connect-js_1.1.0_1774888322335_0.6738728112194126","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-03-30T15:41:21.089Z","modified":"2026-05-21T09:16:57.476Z","1.0.0":"2026-03-30T15:41:21.331Z","1.1.0":"2026-03-30T16:32:02.499Z"},"license":"Apache-2.0","description":"Framework-agnostic JS SDK for connecting web applications to Carmentis Desk","maintainers":[{"email":"arnauld.chevallier@carmentis.io","name":"a.rnauld"},{"email":"gael.marcadet@carmentis.io","name":"gamarcad"}],"readme":"# @cmts-dev/carmentis-desk-connect-js\n\nFramework-agnostic JavaScript/TypeScript SDK for connecting web applications to [Carmentis Desk](https://carmentis.io).\n\nIt wraps [`@cmts-dev/carmentis-relay-client`](https://www.npmjs.com/package/@cmts-dev/carmentis-relay-client) to provide a simple API for creating relay sessions and communicating with the Carmentis Desk mobile application.\n\n## How it works\n\n```\nYour Web App\n    │\n    ├─ Creates a session via the relay server\n    ├─ Generates a deep link → user opens Carmentis Desk\n    │\nRelay Server (WebSocket bridge)\n    │\nCarmentis Desk (mobile app)\n    │\n    └─ Sends back signed responses (auth, approval, …)\n```\n\n## Installation\n\n```bash\nnpm install @cmts-dev/carmentis-desk-connect-js\n# or\npnpm add @cmts-dev/carmentis-desk-connect-js\n```\n\n## Usage\n\n### JSON-RPC popup (recommended)\n\nThe simplest way to integrate — `createCarmentisJsonRpcPopup` injects a modal overlay directly into the DOM, handles the connection lifecycle, automatically sends your JSON-RPC 2.0 request when Carmentis Desk connects, and resolves with a typed response.\n\n```ts\nimport { createCarmentisJsonRpcPopup } from '@cmts-dev/carmentis-desk-connect-js';\n\nconst popup = createCarmentisJsonRpcPopup({\n  relayUrl: 'https://relay.testnet.carmentis.io',\n  title: 'Authenticate with Carmentis Desk', // optional\n  request: {\n    jsonrpc: '2.0',\n    id: 1,\n    method: 'wr-auth-pk',\n    params: { base64EncodedChallenge: 'dGVzdA==' },\n  },\n\n  onResponse(response) {\n    console.log('Success:', response.result);\n    popup.close();\n  },\n\n  onError(err) {\n    console.error('JSON-RPC error:', err.message);\n    popup.close();\n  },\n\n  onClose() {\n    console.log('Popup dismissed');\n  },\n});\n\nawait popup.open();\n```\n\n### Low-level popup\n\nIf you need full control over what is sent (e.g. for non-JSON-RPC messages), use `createCarmentisPopup` directly:\n\n```ts\nimport { createCarmentisPopup } from '@cmts-dev/carmentis-desk-connect-js';\n\nconst popup = createCarmentisPopup({\n  relayUrl: 'https://relay.testnet.carmentis.io',\n  title: 'Authenticate with Carmentis Desk', // optional\n\n  onConnected() {\n    // Carmentis Desk has joined — send your request\n    popup.send({\n      jsonrpc: '2.0',\n      id: 1,\n      method: 'wr-auth-pk',\n      params: { base64EncodedChallenge: 'dGVzdA==' },\n    });\n  },\n\n  onMessage(message) {\n    console.log('Response:', message);\n    popup.close();\n  },\n\n  onClose() {\n    console.log('Popup dismissed');\n  },\n});\n\nawait popup.open();\n```\n\nThe popup goes through four visual states automatically:\n\n| State | Indicator | Info text |\n|-------|-----------|-----------|\n| Initializing | Grey dot | Creating session… |\n| Ready | Pulsing amber dot | Waiting for Carmentis Desk — link shown |\n| Connected | Green dot | Processing request… |\n| Disconnected | Red dot | Session closed |\n\nYou can also access the underlying session at any time:\n\n```ts\nconst session = popup.getSession();\nconsole.log(session.connectionStatus);\nconsole.log(session.getDeepLink());\n```\n\n---\n\n### Basic session\n\n```ts\nimport { createCarmentisSession } from '@cmts-dev/carmentis-desk-connect-js';\n\nconst session = createCarmentisSession();\n\nawait session.connect({\n  relayUrl: 'https://relay.testnet.carmentis.io',\n\n  onReady() {\n    // Session created on the relay — show the deep link / QR code to the user\n    const deepLink = session.getDeepLink();\n    console.log('Open in Carmentis Desk:', deepLink);\n  },\n\n  onConnected() {\n    // Carmentis Desk has joined the session — send your request\n    session.send({\n      jsonrpc: '2.0',\n      id: 1,\n      method: 'wr-auth-pk',\n      params: { base64EncodedChallenge: 'dGVzdA==' },\n    });\n  },\n\n  onMessage(message) {\n    console.log('Response from Carmentis Desk:', message);\n  },\n\n  onDisconnected() {\n    console.log('Session closed');\n  },\n});\n```\n\n### Deep link / QR code\n\nOnce the session is `ready`, call `getDeepLink()` to obtain the URL to share with the user (e.g. as a QR code):\n\n```ts\nconst deepLink = session.getDeepLink();\n// cmts://connect/carmentis-relay?relay=...&sessionId=...&symKey=...\n```\n\n### Sending a request\n\nAfter the session reaches the `connected` state (Carmentis Desk has scanned the QR code), send a JSON-RPC 2.0 request:\n\n```ts\nsession.send({\n  jsonrpc: '2.0',\n  id: 1,\n  method: 'wr-data-approval',\n  params: {\n    anchorRequestId: '1234',\n    serverUrl: 'https://server.testnet.carmentis.io',\n  },\n});\n```\n\n### Connection status\n\nThe `connectionStatus` property reflects the current state:\n\n| Value          | Meaning                                      |\n|----------------|----------------------------------------------|\n| `'unset'`      | `connect()` has not been called yet          |\n| `'ready'`      | Session created on the relay, waiting for Desk |\n| `'connected'`  | Carmentis Desk has joined                    |\n| `'disconnected'` | Session closed                             |\n\n```ts\nconsole.log(session.connectionStatus); // 'ready' | 'connected' | …\n```\n\n## API\n\n### `createCarmentisJsonRpcPopup(options): CarmentisJsonRpcPopup`\n\nFactory function returning a new `CarmentisJsonRpcPopup` instance. Sends the JSON-RPC request automatically when Carmentis Desk connects and handles response parsing. `options`:\n\n| Property        | Type                                    | Description                                      |\n|-----------------|-----------------------------------------|--------------------------------------------------|\n| `relayUrl`      | `string`                                | URL of the Carmentis relay server                |\n| `request`       | `JsonRpcRequest`                        | JSON-RPC 2.0 request to send on connect          |\n| `title`         | `string?`                               | Modal title (optional)                           |\n| `onReady`       | `() => void`                            | Called when the session is ready                 |\n| `onConnected`   | `() => void`                            | Called when Desk joins the session               |\n| `onDisconnected`| `() => void`                            | Called when the session closes                   |\n| `onResponse`    | `(response: JsonRpcSuccessResponse) => void` | Called on a successful JSON-RPC response    |\n| `onError`       | `(error: Error) => void`                | Called on a JSON-RPC error or invalid response   |\n| `onClose`       | `() => void`                            | Called when the modal is closed                  |\n\n### `jsonRpcPopup.open(): Promise<void>`\n\nInjects the modal into `document.body` and starts the relay session.\n\n### `jsonRpcPopup.close(): void`\n\nRemoves the modal from the DOM and calls `onClose`.\n\n### `jsonRpcPopup.getSession(): CarmentisSession`\n\nReturns the underlying `CarmentisSession` instance.\n\n---\n\n### `createCarmentisPopup(options): CarmentisPopup`\n\nFactory function returning a new `CarmentisPopup` instance. `options`:\n\n| Property        | Type                        | Description                          |\n|-----------------|-----------------------------|--------------------------------------|\n| `relayUrl`      | `string`                    | URL of the Carmentis relay server    |\n| `title`         | `string?`                   | Modal title (optional)               |\n| `onReady`       | `() => void`                | Called when the session is ready     |\n| `onConnected`   | `() => void`                | Called when Desk joins the session   |\n| `onDisconnected`| `() => void`                | Called when the session closes       |\n| `onMessage`     | `(message: unknown) => void`| Called on each message from Desk     |\n| `onClose`       | `() => void`                | Called when the modal is closed      |\n\n### `popup.open(): Promise<void>`\n\nInjects the modal into `document.body` and starts the relay session.\n\n### `popup.close(): void`\n\nRemoves the modal from the DOM and calls `onClose`.\n\n### `popup.send(request: unknown): void`\n\nSends a request to Carmentis Desk. Must be called after `onConnected`.\n\n### `popup.getSession(): CarmentisSession`\n\nReturns the underlying `CarmentisSession` instance.\n\n---\n\n### `createCarmentisSession(): CarmentisSession`\n\nFactory function returning a new `CarmentisSession` instance.\n\n### `session.connect(options): Promise<void>`\n\nOpens a relay session. `options`:\n\n| Property        | Type                        | Description                          |\n|-----------------|-----------------------------|--------------------------------------|\n| `relayUrl`      | `string`                    | URL of the Carmentis relay server    |\n| `onReady`       | `() => void`                | Called when the session is ready     |\n| `onConnected`   | `() => void`                | Called when Desk joins the session   |\n| `onDisconnected`| `() => void`                | Called when the session closes       |\n| `onMessage`     | `(message: unknown) => void`| Called on each message from Desk     |\n\n### `session.send(request: unknown): void`\n\nSends a request to Carmentis Desk. Must be called after `onConnected`.\n\n### `session.getDeepLink(): string`\n\nReturns the deep link URL to open in Carmentis Desk. Available after `onReady`.\n\n### `session.sessionId: string`\n\nRelay session identifier.\n\n### `session.symKey: string`\n\nSymmetric encryption key for the session.\n\n### `session.connectionStatus: ConnectionStatus`\n\nCurrent connection state: `'unset' | 'ready' | 'connected' | 'disconnected'`.\n\n### `session.messages: unknown[]`\n\nAll messages received from Carmentis Desk during the session.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}