seam 0.46.0 → 0.48.0

package/README.md

@@ -46,7 +46,59 @@ $ npm install seam
 
 [npm]: https://www.npmjs.com/
 
-### Usage
+## Usage
+
+First, create a webhook using the Seam API or Seam Console
+and obtain a Seam webhook secret.
+
+_This example is for [Express], see the [Svix docs for more examples in specific frameworks](https://docs.svix.com/receiving/verifying-payloads/how)._
+
+```js
+import { SeamWebhook } from 'seam'
+import express from 'express'
+import bodyParser from 'body-parser'
+
+import { storeEvent } from './store-event.js'
+
+const app = express()
+
+const webhook = new SeamWebhook(process.env.SEAM_WEBHOOK_SECRET)
+
+app.post(
+  '/webhook',
+  bodyParser.raw({ type: 'application/json' }),
+  (req, res) => {
+    let data
+    try {
+      data = webhook.verify(payload, headers)
+    } catch {
+      return res.status(400).send()
+    }
+
+    storeEvent(data, (err) => {
+      if (err != null) {
+        return res.status(500).send()
+      }
+      res.status(204).send()
+    })
+  },
+)
+```
+
+[Express]: https://expressjs.com/
+
+### Examples
+
+_These examples assume `SEAM_API_KEY` is set in your environment._
+
+#### List devices
+
+```ts
+import { Seam } from 'seam'
+
+const seam = new Seam()
+const devices = await seam.devices.list()
+```
 
 #### Unlock a door
 
@@ -58,13 +110,332 @@ const lock = await seam.locks.get({ name: 'Front Door' })
 await seam.locks.unlockDoor({ device_id: lock.device_id })
 ```
 
-#### Parse and validate a webhook
+### Authentication Methods
+
+The SDK supports several authentication mechanisms.
+Authentication may be configured by passing the corresponding
+options directly to the `Seam` constructor,
+or with the more ergonomic static factory methods.
+
+> Publishable Key authentication is not supported by the constructor
+> and must be configured using `Seam.fromPublishableKey`.
+
+#### API Key
+
+An API key is scoped to a single workspace and should only be used on the server.
+Obtain one from the Seam Console.
 
 ```ts
-import { SeamWebhook } from 'seam'
+// Set the `SEAM_API_KEY` environment variable
+const seam = new Seam()
+
+// Pass as the first argument to the constructor
+const seam = new Seam('your-api-key')
+
+// Pass as an option the constructor
+const seam = new Seam({ apiKey: 'your-api-key' })
+
+// Use the factory method
+const seam = Seam.fromApiKey('your-api-key')
+```
+
+#### Client Session Token
+
+A Client Session Token is scoped to a client session and should only be used on the client.
+
+```ts
+// Pass as an option the constructor
+const seam = new Seam({ clientSessionToken: 'some-client-session-token' })
+
+// Use the factory method
+const seam = Seam.fromClientSessionToken('some-client-session-token')
+```
+
+The client session token may be updated using
+
+```ts
+const seam = Seam.fromClientSessionToken('some-client-session-token')
+
+await seam.updateClientSessionToken('some-new-client-session-token')
+```
+
+#### Publishable Key
+
+A Publishable Key is used by the client to acquire Client Session Token for a workspace.
+Obtain one from the Seam Console.
+
+Use the async factory method to return a client authenticated with a client session token:
+
+```ts
+const seam = await Seam.fromPublishableKey(
+  'your-publishable-key',
+  'some-user-identifier-key',
+)
+```
+
+This will get an existing client session matching the user identifier key,
+or create a new empty client session.
+
+#### Personal Access Token
+
+A Personal Access Token is scoped to a Seam Console user.
+Obtain one from the Seam Console.
+A workspace id must be provided when using this method
+and all requests will be scoped to that workspace.
+
+```ts
+// Pass as an option the constructor
+
+const seam = new Seam({
+  personalAccessToken: 'your-personal-access-token',
+  workspaceId: 'your-workspace-id',
+})
+
+// Use the factory method
+const seam = Seam.fromPersonalAccessToken(
+  'some-console-session-token',
+  'your-workspace-id',
+)
+```
+
+#### Console Session Token
+
+A Console Session Token is used by the Seam Console.
+This authentication method is only used by internal Seam applications.
+A workspace id must be provided when using this method
+and all requests will be scoped to that workspace.
+
+```ts
+// Pass as an option the constructor
+const seam = new Seam({
+  consoleSessionToken: 'some-console-session-token',
+  workspaceId: 'your-workspace-id',
+})
+
+// Use the factory method
+const seam = Seam.fromConsoleSessionToken(
+  'some-console-session-token',
+  'your-workspace-id',
+)
+```
+
+### Action Attempts
+
+Some asynchronous operations, e.g., unlocking a door, return an [action attempt].
+Seam tracks the progress of requested operation and updates the action attempt.
+
+To make working with action attempts more convenient for applications,
+this library provides the `waitForActionAttempt` option.
+
+Pass the option per-request,
+
+```ts
+await seam.locks.unlockDoor(
+  { device_id },
+  {
+    waitForActionAttempt: true,
+  },
+)
+```
+
+or set the default option for the client:
+
+```ts
+const seam = new Seam({
+  apiKey: 'your-api-key',
+  waitForActionAttempt: true,
+})
+
+await seam.locks.unlockDoor({ device_id })
+```
+
+If you have already have an action attempt id
+and want to wait for it to resolve, simply use
+
+```ts
+await seam.actionAttempts.get(
+  { action_attempt_id },
+  {
+    waitForActionAttempt: true,
+  },
+)
+```
+
+Using the `waitForActionAttempt` option:
+
+- Polls the action attempt up to the `timeout`
+  at the `pollingInterval` (both in milliseconds).
+- Resolves with a fresh copy of the successful action attempt.
+- Rejects with a `SeamActionAttemptFailedError` if the action attempt is unsuccessful.
+- Rejects with a `SeamActionAttemptTimeoutError` if the action attempt is still pending when the `timeout` is reached.
+- Both errors expose an `actionAttempt` property.
+
+```ts
+import {
+  Seam,
+  isSeamActionAttemptFailedError,
+  isSeamActionAttemptTimeoutError,
+} from 'seam'
+
+const seam = new Seam('your-api-key')
+
+const [lock] = await seam.locks.list()
+
+if (lock == null) throw new Error('No locks in this workspace')
+
+try {
+  await seam.locks.unlockDoor(
+    { device_id: lock.device_id },
+    {
+      waitForActionAttempt: {
+        pollingInterval: 1000,
+        timeout: 5000,
+      },
+    },
+  )
+  console.log('Door unlocked')
+} catch (err: unknown) {
+  if (isSeamActionAttemptFailedError(err)) {
+    console.log('Could not unlock the door')
+    return
+  }
+
+  if (isSeamActionAttemptTimeoutError(err)) {
+    console.log('Door took too long to unlock')
+    return
+  }
+
+  throw err
+}
+```
+
+[action attempt]: https://docs.seam.co/latest/core-concepts/action-attempts
+
+### Interacting with Multiple Workspaces
+
+Some Seam API endpoints interact with multiple workspaces.
+The `SeamMultiWorkspace` client is not bound to a specific workspace
+and may use those endpoints with an appropriate authentication method.
+
+#### Personal Access Token
+
+A Personal Access Token is scoped to a Seam Console user.
+Obtain one from the Seam Console.
+
+```ts
+// Pass as an option the constructor
+const seam = new SeamMultiWorkspace({
+  personalAccessToken: 'your-personal-access-token',
+})
+
+// Use the factory method
+const seam = SeamMultiWorkspace.fromPersonalAccessToken(
+  'some-console-session-token',
+)
+
+// List workspaces authorized for this Personal Access Token
+const workspaces = await seam.workspaces.list()
+```
+
+#### Console Session Token
+
+A Console Session Token is used by the Seam Console.
+This authentication method is only used by internal Seam applications.
+
+```ts
+// Pass as an option the constructor
+const seam = new SeamMultiWorkspace({
+  consoleSessionToken: 'some-console-session-token',
+})
+
+// Use the factory method
+const seam = SeamMultiWorkspace.fromConsoleSessionToken(
+  'some-console-session-token',
+)
+
+// List workspaces authorized for this Seam Console user
+const workspaces = await seam.workspaces.list()
+```
+
+### Advanced Usage
+
+#### Additional Options
+
+In addition the various authentication options,
+the constructor takes some advanced options that affect behavior.
+
+```ts
+const seam = new Seam({
+  apiKey: 'your-api-key',
+  endpoint: 'https://example.com',
+  axiosOptions: {},
+  axiosRetryOptions: {},
+})
+```
+
+When using the static factory methods,
+these options may be passed in as the last argument.
+
+```ts
+const seam = Seam.fromApiKey('some-api-key', {
+  endpoint: 'https://example.com',
+  axiosOptions: {},
+  axiosRetryOptions: {},
+})
+```
+
+#### Setting the endpoint
+
+Some contexts may need to override the API endpoint,
+e.g., testing or proxy setups.
+This option corresponds to the Axios `baseURL` setting.
+
+Either pass the `endpoint` option, or set the `SEAM_ENDPOINT` environment variable.
+
+#### Configuring the Axios Client
+
+The Axios client and retry behavior may be configured with custom initiation options
+via [`axiosOptions`][axiosOptions] and [`axiosRetryOptions`][axiosRetryOptions].
+Options are deep merged with the default options.
+
+[axiosOptions]: https://axios-http.com/docs/config_defaults
+[axiosRetryOptions]: https://github.com/softonic/axios-retry
+
+#### Using the Axios Client
+
+The Axios client is exposed and may be used or configured directly:
+
+```ts
+import { Seam, DevicesListResponse } from 'seam'
+
+const seam = new Seam()
+
+seam.client.interceptors.response.use((response) => {
+  console.log(response)
+  return response
+})
+
+const devices = await seam.client.get<DevicesListResponse>('/devices/list')
+```
+
+#### Overriding the Client
+
+An Axios compatible client may be provided to create a `Seam` instance.
+This API is used internally and is not directly supported.
+
+#### Inspecting the Request
+
+All client methods return an instance of `SeamRequest`.
+Inspect the request before it is sent to the server by intentionally not awaiting the `SeamRequest`:
+
+```ts
+const seam = new Seam('your-api-key')
+
+const request = seam.devices.list()
+
+console.log(`${request.method} ${request.url}`, JSON.stringify(request.body))
 
-const webhook = new SeamWebhook('webhook-secret')
-const data = webhook.verify(payload, headers)
+const devices = await request.execute()
 ```
 
 ## Development and Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seam",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "JavaScript SDK for the Seam API written in TypeScript.",
   "type": "module",
   "main": "index.js",
@@ -52,6 +52,9 @@
     "lint": "eslint --ignore-path .gitignore .",
     "prelint": "prettier --check --ignore-path .gitignore .",
     "postversion": "git push --follow-tags",
+    "generate:readme": "tsx ./generate-readme.ts",
+    "example": "tsx examples",
+    "example:inspect": "tsx --inspect examples",
     "format": "eslint --ignore-path .gitignore --fix .",
     "preformat": "prettier --write --ignore-path .gitignore ."
   },
@@ -60,8 +63,8 @@
     "npm": ">= 9.0.0"
   },
   "dependencies": {
-    "@seamapi/http": "0.25.0",
-    "@seamapi/types": "1.144.0",
+    "@seamapi/http": "0.25.2",
+    "@seamapi/types": "1.146.0",
     "@seamapi/webhook": "1.0.0-rc.0",
     "seamapi-types": "1.42.0"
   },
@@ -74,6 +77,7 @@
     "eslint-config-standard-with-typescript": "^43.0.0",
     "eslint-plugin-simple-import-sort": "^12.0.0",
     "eslint-plugin-unused-imports": "^3.0.0",
+    "landlubber": "^2.0.0",
     "prettier": "^3.0.0",
     "tsc-alias": "^1.8.2",
     "tsup": "^8.0.1",

package/src/env.d.ts

@@ -0,0 +1,10 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      SEAM_API_KEY?: string
+      SEAM_ENDPOINT?: string
+    }
+  }
+}
+
+export {}