@gibeon/sdk 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -2
- package/dist/index.cjs +882 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +179 -0
- package/dist/index.d.ts +179 -0
- package/dist/index.js +863 -0
- package/dist/index.js.map +1 -0
- package/package.json +53 -4
package/README.md
CHANGED
|
@@ -1,3 +1,84 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @gibeon/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Put content on a gibeon.io screen from Node: sign in once, make a playlist and a screen, get its play URL.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install @gibeon/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Node 20 or later. No runtime dependencies.
|
|
12
|
+
|
|
13
|
+
## Quickstart
|
|
14
|
+
|
|
15
|
+
Use the email address of your gibeon.io account.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { Gibeon } from '@gibeon/sdk'
|
|
19
|
+
|
|
20
|
+
const g = new Gibeon({ email: 'you@company.com' })
|
|
21
|
+
const playlist = await g.playlists.create({ name: 'Lobby' })
|
|
22
|
+
await g.playlists.addItem(playlist.id, {
|
|
23
|
+
type: 'youtube',
|
|
24
|
+
external_url: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ',
|
|
25
|
+
})
|
|
26
|
+
const screen = await g.screens.create('lobby-tv', { playlistId: playlist.id })
|
|
27
|
+
console.log(screen.playUrl) // https://p.gibeon.io/?d=AB12CD
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Open the play URL in a browser and the video plays.
|
|
31
|
+
|
|
32
|
+
## Sign-in
|
|
33
|
+
|
|
34
|
+
The first call prints a link and a code on stderr and waits up to 10 minutes for you to approve it. Open the link, sign in to your gibeon.io account and enter the code. The SDK opens the browser for you only when stdout is a terminal, `CI` is not set and a display exists; otherwise it just prints the link.
|
|
35
|
+
|
|
36
|
+
The email address comes from `new Gibeon({ email })`, then the `GIBEON_EMAIL` environment variable, then a prompt in the terminal. With none of these the call throws a `GibeonAuthError` with code `email_required`.
|
|
37
|
+
|
|
38
|
+
At most 20 sign-ins per hour are allowed per network.
|
|
39
|
+
|
|
40
|
+
In CI, set `GIBEON_TOKEN` from a secret. Do not sign in from CI.
|
|
41
|
+
|
|
42
|
+
## The token file
|
|
43
|
+
|
|
44
|
+
After the approval the tokens are stored in `~/.gibeon/credentials.json`. The file is readable by you only: mode 0600, in a directory with mode 0700. Set `GIBEON_CREDENTIALS_FILE` to keep it somewhere else. On Windows the file modes are a no-op, so the file is as private as your user folder.
|
|
45
|
+
|
|
46
|
+
Tokens refresh by themselves. Delete the file to sign this machine out. To revoke access for good, remove the app in the CMS under Settings, Connected apps.
|
|
47
|
+
|
|
48
|
+
## A token from the CMS
|
|
49
|
+
|
|
50
|
+
`new Gibeon({ token })` or the `GIBEON_TOKEN` environment variable uses a token you generated in the CMS as it is. It is never stored or refreshed, and it lasts 60 minutes. When it is refused the call throws a `GibeonAuthError` with code `token_expired`.
|
|
51
|
+
|
|
52
|
+
## Methods
|
|
53
|
+
|
|
54
|
+
| Method | Does |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `screens.list()` | `GET /v1/players` |
|
|
57
|
+
| `screens.get(id)` | `GET /v1/players/{id}` |
|
|
58
|
+
| `screens.create(name, { playlistId \| sequenceId \| planningId, orientation?, location? })` | Makes a screen, or reuses one (see below). Returns the screen with its `playUrl`. |
|
|
59
|
+
| `screens.update(id, patch)` | `PATCH /v1/players/{id}`. Returns the screen plus `publishRequired`. |
|
|
60
|
+
| `screens.publish(id?)` | Publishes one screen, or all screens without an id. |
|
|
61
|
+
| `playlists.list()`, `playlists.get(id)`, `playlists.create({ name })` | `/v1/playlists` |
|
|
62
|
+
| `playlists.addItem(playlistId, item)` | `POST /v1/playlists/{id}/items`. The item is the API body, in snake_case. |
|
|
63
|
+
| `assets.upload({ name, data, mimeType })` | Uploads an image (`image/*`), a PDF or an HTML file and returns the asset. |
|
|
64
|
+
| `request(method, path, body?)` | Any `/v1/*` route. Sends the body as it is and returns the raw JSON. |
|
|
65
|
+
|
|
66
|
+
Results are camelCase versions of the API fields (`playUrl`, `playlistId`), keys inside `config` included (`assetIds`), so do not pass the `config` of an item you read back to `addItem` as it is. `request` is the exception: it returns the API answer unchanged.
|
|
67
|
+
|
|
68
|
+
## `screens.create` reuses a screen
|
|
69
|
+
|
|
70
|
+
`screens.create(name, opts)` first lists your screens. If exactly one screen with a play URL has that name, it points that screen at the new content, publishes it when that changed what the screen plays, and returns it. If the screen already plays that content, nothing is published: after you change a playlist the screen already plays, call `screens.publish(id)`. Screens without a play URL, such as paired hardware boxes, are never touched. If two or more match, it throws a `GibeonApiError` with code `ambiguous_name` and the ids. If none match, it makes a new screen. So running the quickstart twice gives one screen.
|
|
71
|
+
|
|
72
|
+
`create` with the name of an existing screen replaces what that screen plays, the starter screen "Mijn eerste scherm" included.
|
|
73
|
+
|
|
74
|
+
## Errors
|
|
75
|
+
|
|
76
|
+
`GibeonApiError` comes from the API. It has `status`, `code` and `requestId`, plus `ids` for `ambiguous_name`.
|
|
77
|
+
|
|
78
|
+
`GibeonAuthError` comes from the sign-in. Its `code` is one of `email_required`, `claim_expired`, `rate_limited`, `token_expired` and `sign_in_failed`.
|
|
79
|
+
|
|
80
|
+
If sign-in keeps ending in `claim_expired`, delete the credentials file and run again.
|
|
81
|
+
|
|
82
|
+
## License
|
|
83
|
+
|
|
84
|
+
MIT
|