feat: Merge pull request #32 from seamapi/feat-webhooks

Author: codetheweb

README.md

@@ -76,3 +76,42 @@ console.log(await seam.accessCodes.list({ device_id: myLockId }))
 ]
 */
 ```
+
+### Receiving Webhooks
+
+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.
+
+`SeamWebhook` is a thin wrapper around the `Webhook` class from the [Svix library](https://docs.svix.com/receiving/verifying-payloads/how).
+
+Example for Express:
+
+```ts
+// Replace with
+// const {SeamWebhook} = require("seamapi")
+// if not using ES6 modules and/or TypeScript.
+import {SeamWebhook} from "seamapi";
+
+import bodyParser from "body-parser";
+
+// Get this from the Seam dashboard
+const secret = "sample-secret";
+
+app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => {
+    const payload = req.body;
+    const headers = req.headers;
+
+    const wh = new SeamWebhook(secret);
+    let msg;
+    try {
+        msg = wh.verify(payload, headers);
+    } catch (err) {
+        res.status(400).json({});
+    }
+
+    // Do something with the message...
+
+    res.json({});
+});
+```
+
+For examples using other frameworks, see the [Svix docs](https://docs.svix.com/receiving/verifying-payloads/how#framework-specific-examples).

cjs-wrapper.js

@@ -1 +1,4 @@
-module.exports = require("./dist/index.js").default
+module.exports = {
+  ...require("./dist/index.js").default,
+  ...require("./dist/index.js"),
+}

docs/README.md

@@ -78,3 +78,42 @@ console.log(await seam.accessCodes.list({ device_id: myLockId }))
 ]
 */
 ```
+
+### Receiving Webhooks
+
+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.
+
+`SeamWebhook` is a thin wrapper around the `Webhook` class from the [Svix library](https://docs.svix.com/receiving/verifying-payloads/how).
+
+Example for Express:
+
+```ts
+// Replace with
+// const {SeamWebhook} = require("seamapi")
+// if not using ES6 modules and/or TypeScript.
+import {SeamWebhook} from "seamapi";
+
+import bodyParser from "body-parser";
+
+// Get this from the Seam dashboard
+const secret = "sample-secret";
+
+app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => {
+    const payload = req.body;
+    const headers = req.headers;
+
+    const wh = new SeamWebhook(secret);
+    let msg;
+    try {
+        msg = wh.verify(payload, headers);
+    } catch (err) {
+        res.status(400).json({});
+    }
+
+    // Do something with the message...
+
+    res.json({});
+});
+```
+
+For examples using other frameworks, see the [Svix docs](https://docs.svix.com/receiving/verifying-payloads/how#framework-specific-examples).

docs/classes/default.md renamed to docs/classes/Seam.md

@@ -1,39 +1,39 @@
-[seamapi](../README.md) / [Exports](../modules.md) / default
+[seamapi](../README.md) / [Exports](../modules.md) / Seam
 
-# Class: default
+# Class: Seam
 
 ## Hierarchy
 
 - `Routes`
 
-  ↳ **`default`**
+  ↳ **`Seam`**
 
 ## Table of contents
 
 ### Constructors
 
-- [constructor](default.md#constructor)
+- [constructor](Seam.md#constructor)
 
 ### Properties
 
-- [accessCodes](default.md#accesscodes)
-- [actionAttempts](default.md#actionattempts)
-- [client](default.md#client)
-- [connectWebviews](default.md#connectwebviews)
-- [connectedAccounts](default.md#connectedaccounts)
-- [devices](default.md#devices)
-- [locks](default.md#locks)
-- [workspaces](default.md#workspaces)
+- [accessCodes](Seam.md#accesscodes)
+- [actionAttempts](Seam.md#actionattempts)
+- [client](Seam.md#client)
+- [connectWebviews](Seam.md#connectwebviews)
+- [connectedAccounts](Seam.md#connectedaccounts)
+- [devices](Seam.md#devices)
+- [locks](Seam.md#locks)
+- [workspaces](Seam.md#workspaces)
 
 ### Methods
 
-- [makeRequest](default.md#makerequest)
+- [makeRequest](Seam.md#makerequest)
 
 ## Constructors
 
 ### constructor
 
-• **new default**(`apiKeyOrOptions?`)
+• **new Seam**(`apiKeyOrOptions?`)
 
 #### Parameters
 
@@ -47,7 +47,7 @@ Routes.constructor
 
 #### Defined in
 
-[src/index.ts:38](https://github.com/seamapi/seamapi-javascript/blob/main/src/index.ts#L38)
+[src/client.ts:38](https://github.com/seamapi/seamapi-javascript/blob/main/src/client.ts#L38)
 
 ## Properties
 
@@ -59,7 +59,7 @@ Routes.constructor
 
 | Name | Type |
 | :------ | :------ |
-| `create` | (`params`: [`AccessCodeCreateBaseRequest`](../interfaces/AccessCodeCreateBaseRequest.md)) => `Promise`<[`OngoingAccessCode`](../interfaces/OngoingAccessCode.md)\> \| (`params`: [`AccessCodeCreateScheduledRequest`](../interfaces/AccessCodeCreateScheduledRequest.md)) => `Promise`<[`TimeBoundAccessCode`](../interfaces/TimeBoundAccessCode.md)\> |
+| `create` | (`params`: [`AccessCodeCreateOngoingRequest`](../interfaces/AccessCodeCreateOngoingRequest.md)) => `Promise`<[`OngoingAccessCode`](../interfaces/OngoingAccessCode.md)\>(`params`: [`AccessCodeCreateScheduledRequest`](../interfaces/AccessCodeCreateScheduledRequest.md)) => `Promise`<[`TimeBoundAccessCode`](../interfaces/TimeBoundAccessCode.md)\> |
 | `delete` | (`params`: [`AccessCodeDeleteRequest`](../modules.md#accesscodedeleterequest)) => `Promise`<`unknown`\> |
 | `list` | (`params`: { `device_id`: `string`  }) => `Promise`<[`AccessCode`](../modules.md#accesscode)[]\> |
 
@@ -89,7 +89,7 @@ Routes.actionAttempts
 
 #### Defined in
 
-[src/routes.ts:269](https://github.com/seamapi/seamapi-javascript/blob/main/src/routes.ts#L269)
+[src/routes.ts:268](https://github.com/seamapi/seamapi-javascript/blob/main/src/routes.ts#L268)
 
 ___
 
@@ -99,7 +99,7 @@ ___
 
 #### Defined in
 
-[src/index.ts:36](https://github.com/seamapi/seamapi-javascript/blob/main/src/index.ts#L36)
+[src/client.ts:36](https://github.com/seamapi/seamapi-javascript/blob/main/src/client.ts#L36)
 
 ___
 
@@ -142,7 +142,7 @@ Routes.connectedAccounts
 
 #### Defined in
 
-[src/routes.ts:248](https://github.com/seamapi/seamapi-javascript/blob/main/src/routes.ts#L248)
+[src/routes.ts:247](https://github.com/seamapi/seamapi-javascript/blob/main/src/routes.ts#L247)
 
 ___
 
@@ -239,4 +239,4 @@ Routes.makeRequest
 
 #### Defined in
 
-[src/index.ts:68](https://github.com/seamapi/seamapi-javascript/blob/main/src/index.ts#L68)
+[src/client.ts:68](https://github.com/seamapi/seamapi-javascript/blob/main/src/client.ts#L68)

docs/classes/SeamWebhook.md

@@ -0,0 +1,72 @@
+[seamapi](../README.md) / [Exports](../modules.md) / SeamWebhook
+
+# Class: SeamWebhook
+
+Parse and verify webhook payloads.
+
+## Table of contents
+
+### Constructors
+
+- [constructor](SeamWebhook.md#constructor)
+
+### Properties
+
+- [wh](SeamWebhook.md#wh)
+
+### Methods
+
+- [verify](SeamWebhook.md#verify)
+
+## Constructors
+
+### constructor
+
+• **new SeamWebhook**(`secret`)
+
+Create a new instance of SeamWebhook.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `secret` | `string` | your webhook secret from the dashboard |
+
+#### Defined in
+
+[src/webhooks.ts:14](https://github.com/seamapi/seamapi-javascript/blob/main/src/webhooks.ts#L14)
+
+## Properties
+
+### wh
+
+• `Private` **wh**: `Webhook`
+
+#### Defined in
+
+[src/webhooks.ts:8](https://github.com/seamapi/seamapi-javascript/blob/main/src/webhooks.ts#L8)
+
+## Methods
+
+### verify
+
+▸ **verify**(`payload`, `headers`): [`SeamEvent`](../modules.md#seamevent)
+
+Verify a payload received from a webhook and return the typed event.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `payload` | `string` | must be a string (should not be the parsed JSON object) |
+| `headers` | `Record`<`string`, `string`\> | request headers (used to verify against the secret) |
+
+#### Returns
+
+[`SeamEvent`](../modules.md#seamevent)
+
+event
+
+#### Defined in
+
+[src/webhooks.ts:24](https://github.com/seamapi/seamapi-javascript/blob/main/src/webhooks.ts#L24)

docs/interfaces/AccessCodeCreateBaseRequest.md

@@ -6,6 +6,8 @@
 
 - **`AccessCodeCreateBaseRequest`**
 
+  ↳ [`AccessCodeCreateOngoingRequest`](AccessCodeCreateOngoingRequest.md)
+
   ↳ [`AccessCodeCreateScheduledRequest`](AccessCodeCreateScheduledRequest.md)
 
 ## Table of contents

docs/interfaces/AccessCodeCreateOngoingRequest.md

@@ -0,0 +1,59 @@
+[seamapi](../README.md) / [Exports](../modules.md) / AccessCodeCreateOngoingRequest
+
+# Interface: AccessCodeCreateOngoingRequest
+
+## Hierarchy
+
+- [`AccessCodeCreateBaseRequest`](AccessCodeCreateBaseRequest.md)
+
+  ↳ **`AccessCodeCreateOngoingRequest`**
+
+## Table of contents
+
+### Properties
+
+- [code](AccessCodeCreateOngoingRequest.md#code)
+- [device\_id](AccessCodeCreateOngoingRequest.md#device_id)
+- [name](AccessCodeCreateOngoingRequest.md#name)
+
+## Properties
+
+### code
+
+• `Optional` **code**: `string`
+
+#### Inherited from
+
+[AccessCodeCreateBaseRequest](AccessCodeCreateBaseRequest.md).[code](AccessCodeCreateBaseRequest.md#code)
+
+#### Defined in
+
+[src/types/route-requests.ts:10](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L10)
+
+___
+
+### device\_id
+
+• **device\_id**: `string`
+
+#### Inherited from
+
+[AccessCodeCreateBaseRequest](AccessCodeCreateBaseRequest.md).[device_id](AccessCodeCreateBaseRequest.md#device_id)
+
+#### Defined in
+
+[src/types/route-requests.ts:8](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L8)
+
+___
+
+### name
+
+• `Optional` **name**: `string`
+
+#### Inherited from
+
+[AccessCodeCreateBaseRequest](AccessCodeCreateBaseRequest.md).[name](AccessCodeCreateBaseRequest.md#name)
+
+#### Defined in
+
+[src/types/route-requests.ts:9](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L9)

docs/interfaces/AccessCodeCreateScheduledRequest.md

@@ -54,7 +54,7 @@ ___
 
 #### Defined in
 
-[src/types/route-requests.ts:18](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L18)
+[src/types/route-requests.ts:19](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L19)
 
 ___
 
@@ -78,4 +78,4 @@ ___
 
 #### Defined in
 
-[src/types/route-requests.ts:17](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L17)
+[src/types/route-requests.ts:18](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/route-requests.ts#L18)

docs/interfaces/CommonDeviceEvent.md

@@ -0,0 +1,37 @@
+[seamapi](../README.md) / [Exports](../modules.md) / CommonDeviceEvent
+
+# Interface: CommonDeviceEvent<EventType, Payload\>
+
+## Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `EventType` | extends `string` |
+| `Payload` | extends `Record`<`string`, `unknown`\> \| {} = {} |
+
+## Table of contents
+
+### Properties
+
+- [data](CommonDeviceEvent.md#data)
+- [event\_type](CommonDeviceEvent.md#event_type)
+
+## Properties
+
+### data
+
+• **data**: `Payload` & { `device_id`: `string` ; `workspace_id`: `string`  }
+
+#### Defined in
+
+[src/types/webhook-events.ts:7](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/webhook-events.ts#L7)
+
+___
+
+### event\_type
+
+• **event\_type**: `EventType`
+
+#### Defined in
+
+[src/types/webhook-events.ts:6](https://github.com/seamapi/seamapi-javascript/blob/main/src/types/webhook-events.ts#L6)