# @cantoo/cantoo-api

> A client api for integration with Cantoo Scribe

Latest version **1.0.18** (published 2025-06-30) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cantoo/cantoo-api
pnpm add @cantoo/cantoo-api
yarn add @cantoo/cantoo-api
bun add @cantoo/cantoo-api
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.18 |
| Published | 2025-06-30 |
| First published | 2022-11-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 19.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cantoo - Inschool SAS |
| Maintainers | sharcoux, ribeirofmatheus, matheusrdsantos, gabrielnsd, nicodemos234 |

## Links

- npm: https://www.npmjs.com/package/@cantoo/cantoo-api
- npm.io page: https://npm.io/package/@cantoo/cantoo-api

## Recent versions

- 1.0.18 (latest) — 2025-06-30
- 1.0.17 — 2025-06-30
- 1.0.16 — 2023-11-24
- 1.0.15 — 2023-10-25
- 1.0.14 — 2023-10-05
- 1.0.13 — 2023-09-03
- 1.0.12 — 2023-06-22
- 1.0.11 — 2023-06-01
- 1.0.10 — 2023-06-01
- 1.0.9 — 2023-06-01
- 1.0.8 — 2023-02-16
- 1.0.7 — 2023-02-14
- 1.0.6 — 2023-02-08
- 1.0.5 — 2023-02-08
- 1.0.4 — 2023-02-08
- … 3 more at https://npm.io/package/@cantoo/cantoo-api/versions

## README

# cantoo-api

## Creating a new connection

To create a new connection with the cantoo api you must call the static method `CantooApi.connect()`. This method will create an iframe on the provided DOM node and return a new CantooApi instance. Don't forget to call `destroy` before getting rid of the CantooApi instance.

`CantooApi.connect()` receives an Object as param. The object should have the following properties:

| key | type | required | description |
|-----|------|----------|-------------|
| domElement | ` HTMLElement` | required | The DOM element which the iframe will be attached to. It should use `display:flex;` |
| accessToken | `string` | required | The token of the user that wants to interact with the api (as received from the GAR) |
| fileId | `string` | optional | The file id that is going to be edited (as received in the "ready" and "completed" events) |
| title | `string` | optional | The title of the file that will be created. Should not be set if fileId is set |
| env | `'prod' \| 'preprod' \| 'develop'` | required | The environment that the client will connect to |
| readOnly | `boolean` | required | Should the user be able to edit the file, or is it only a viewer? |

```js
const api = await CantooAPI.connect({domElement, env: 'develop', accessToken: '1', fileId: '10', readOnly: true})
```

## The CantooApi instance

Once the connection is done you can interact with the cantoo api through the following methods:

|name|type|description|
|----|----|-----------|
| loadDocument |`(id: string, readOnly?: boolean \| undefined) => Promise<void>`| Loads a new document on the Iframe |
| addEventListener | `(eventName: 'ready', callback: (event: { id: string, userId: string, fileId: string }) => void) => void`| Adds a new listener to the 'ready' event |
| addEventListener | `(eventName: 'completed', callback: (event: { id: string, title: string, userId: string }) => void) => void` | Adds a new listener to the `'completed'` event |
| addEventListener | `(eventName: 'destroyed', callback: () => void) => void`| Adds a new listener to the 'destroyed' event |
| addEventListener | `(eventName: 'logout', callback: (event: { id: string, userId: string }) => void) => void`| Adds a new listener to the 'logout' event |
| removeEventListener | `(eventName: 'ready\|completed\|destroyed\|logout', callback) => void`| Removes a listener that is attached to some event. The callback is the function instance that was previously added to the listener |
| destroy | `() => void`| Closes the connection with the api. This function also removes all listeners and call the listerners that were attached to the `'destroyed'` event|

### The connection state
The CantooApi holds the connection state on the readOnly attribute `state`.

There are 4 possible states:

|name|description|
|----|-----------|
|launching| The iframe was attached to the DOM and is loading its content |
|ready| The document `id` is ready for edition |
|completed| The document `id` has been created and can be retrieved or shared |
|destroyed| The iframe was destroyed and detached |

---
_Source: https://npm.io/package/@cantoo/cantoo-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._