|
1 | | -# Javascript / Typescript Seam API Library & CLI |
2 | | - |
3 | | -Control locks, lights and other internet of things devices with Seam's simple API! |
4 | | - |
5 | | -Check out [the generated typescript docs](./docs/modules.md) or some examples: |
6 | | -- [Getting Started Guide with Examples](https://docs.seam.co/github-seam-api-docs/device-guides/get-started-with-august-locks) |
7 | | -- [CLI Usage](#cli-usage) |
8 | | -- [Library Usage](#library-usage) |
9 | | -- [Receiving Webhooks](#receiving-webhooks) |
10 | | - |
11 | | -## Usage |
12 | | - |
13 | | -This package contains both a library and a CLI tool. |
14 | | - |
15 | | -### CLI Usage |
16 | | - |
17 | | -Install with `yarn global add seamapi` or `npm install -g seamapi`. |
18 | | - |
19 | | -Then: |
20 | | -```bash |
21 | | -export SEAM_API_KEY=<your api key> # you can also pass this as an argument to the CLI |
22 | | - |
23 | | -seam workspaces list |
24 | | -``` |
25 | | - |
26 | | -### Library Usage |
27 | | - |
28 | | -Install with `yarn add seamapi` or `npm install seamapi -s`. |
29 | | - |
30 | | -Then: |
31 | | -```ts |
32 | | -// Replace with |
33 | | -// const { Seam } = require("seamapi") |
34 | | -// if not using ES6 modules and/or TypeScript. |
35 | | -import Seam from "seamapi"; |
36 | | - |
37 | | -// Seam will automatically use the SEAM_API_KEY environment variable if you |
38 | | -// don't provide an apiKey to `new Seam()` |
39 | | -const seam = new Seam(); |
40 | | - |
41 | | -const myLock = await seam.locks.get({ name: "My Lock" }); |
42 | | -const myLockId = myLock.device_id |
43 | | -await seam.locks.lockDoor(myLockId); |
44 | | - |
45 | | -console.log(await seam.locks.list()) |
46 | | -/* |
47 | | -[ |
48 | | - { |
49 | | - device_id: '1815b031-e531-432a-9ae6-b3f2cfb77cab', |
50 | | - device_type: 'smartthings_lock', |
51 | | - capabilities_supported: [ 'access_code', 'lock' ], |
52 | | - properties: { |
53 | | - locked: true, |
54 | | - online: true, |
55 | | - name: 'My Lock' |
56 | | - }, |
57 | | - connected_account_id: '1696fff5-b791-4e30-b039-d8110c78231c', |
58 | | - workspace_id: '2ff17969-b283-426f-9e8f-045323615eee', |
59 | | - created_at: '2022-02-25T08:47:56.486Z' |
60 | | - } |
61 | | -] |
62 | | -*/ |
63 | | - |
64 | | -await seam.accessCodes.create({ |
65 | | - name: "Some Access Code", |
66 | | - code: "1234", |
67 | | - device_id: someLockId, |
68 | | -}); |
69 | | - |
70 | | -console.log(await seam.accessCodes.list({ device_id: myLockId })) |
71 | | -/* |
72 | | -[ |
73 | | - { |
74 | | - access_code_id: '6a556ffe-3253-4c31-804e-2c0a32d9015f', |
75 | | - code: '1234', |
76 | | - name: 'Some Access Code', |
77 | | - type: 'ongoing', |
78 | | - status: 'set', |
79 | | - created_at: '2022-02-25T18:46:20.318Z' |
80 | | - } |
81 | | -] |
82 | | -*/ |
83 | | -``` |
84 | | - |
85 | | -### Receiving Webhooks |
86 | | - |
87 | | -Although you don't need to use this package when receiving webhooks, we **strongly** recommend that you do. Using the included helper class will verify payloads (preventing malicious requests) and return a well-typed event. |
88 | | - |
89 | | -`SeamWebhook` is a thin wrapper around the `Webhook` class from the [Svix library](https://docs.svix.com/receiving/verifying-payloads/how). |
90 | | - |
91 | | -Example for Express: |
92 | | - |
93 | | -```ts |
94 | | -// Replace with |
95 | | -// const { SeamWebhook } = require("seamapi") |
96 | | -// if not using ES6 modules and/or TypeScript. |
97 | | -import { SeamWebhook } from "seamapi"; |
98 | | - |
99 | | -import bodyParser from "body-parser"; |
100 | | - |
101 | | -// Get this from the Seam dashboard |
102 | | -const secret = "sample-secret"; |
103 | | - |
104 | | -app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { |
105 | | - const payload = req.body; |
106 | | - const headers = req.headers; |
107 | | - |
108 | | - const wh = new SeamWebhook(secret); |
109 | | - let msg; |
110 | | - try { |
111 | | - msg = wh.verify(payload, headers); |
112 | | - } catch (err) { |
113 | | - res.status(400).json({}); |
114 | | - } |
115 | | - |
116 | | - // Do something with the message... |
117 | | - |
118 | | - res.json({}); |
119 | | -}); |
120 | | -``` |
121 | | - |
122 | | -For examples using other frameworks, see the [Svix docs](https://docs.svix.com/receiving/verifying-payloads/how#framework-specific-examples). |
123 | | - |
| 1 | +This package has moved to [seam](https://www.npmjs.com/package/seam). |
| 2 | +Please refer to the [migration guide](https://github.com/seamapi/javascript/releases/tag/v1.0.0). |
0 commit comments