seam 0.47.0 → 0.49.0

package/README.md

@@ -5,10 +5,6 @@
 
 JavaScript SDK for the Seam API written in TypeScript.
 
-_This repository hosts the next major version of the Seam JavaScript SDK.
-This SDK is available for early preview.
-It will eventually replace the [seamapi](https://github.com/seamapi/javascript/) package._
-
 ## Description
 
 [Seam] makes it easy to integrate IoT devices with your applications.
@@ -19,12 +15,7 @@ The SDK is fully tree-shakeable
 and optimized for use in both client and server applications.
 
 The repository does not contain the SDK code.
-Instead, it re-exports from a core set of Seam modules.
-
-_While this SDK is still in preview,
-please refer to the individual README files in these repositories for
-additional usage documentation not yet available in the primary Seam documentation.
-See [this issue for a draft migration guide](https://github.com/seamapi/javascript-next/issues/1) from the seamapi package._
+Instead, it re-exports from a core set of Seam modules:
 
 - [@seamapi/http]: JavaScript HTTP client for the Seam API written in TypeScript.
 - [@seamapi/webhook]: Webhook SDK for the Seam API written in TypeScript.
@@ -36,6 +27,47 @@ See [this issue for a draft migration guide](https://github.com/seamapi/javascri
 [@seamapi/http]: https://github.com/seamapi/javascript-http
 [@seamapi/webhook]: https://github.com/seamapi/javascript-webhook
 
+## Contents
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Examples](#examples)
+    - [List devices](#list-devices)
+    - [Unlock a door](#unlock-a-door)
+  - [Authentication Methods](#authentication-methods)
+    - [API Key](#api-key)
+    - [Client Session Token](#client-session-token)
+    - [Publishable Key](#publishable-key)
+    - [Personal Access Token](#personal-access-token)
+    - [Console Session Token](#console-session-token)
+  - [Action Attempts](#action-attempts)
+  - [Interacting with Multiple Workspaces](#interacting-with-multiple-workspaces)
+    - [Personal Access Token](#personal-access-token-1)
+    - [Console Session Token](#console-session-token-1)
+  - [Advanced Usage](#advanced-usage)
+    - [Additional Options](#additional-options)
+    - [Setting the endpoint](#setting-the-endpoint)
+    - [Configuring the Axios Client](#configuring-the-axios-client)
+    - [Using the Axios Client](#using-the-axios-client)
+    - [Overriding the Client](#overriding-the-client)
+    - [Inspecting the Request](#inspecting-the-request)
+  - [Receiving Webhooks](#receiving-webhooks)
+- [Development and Testing](#development-and-testing)
+  - [Quickstart](#quickstart)
+  - [Source code](#source-code)
+  - [Requirements](#requirements)
+  - [Publishing](#publishing)
+    - [Automatic](#automatic)
+    - [Manual](#manual)
+- [GitHub Actions](#github-actions)
+- [Contributing](#contributing)
+- [License](#license)
+- [Warranty](#warranty)
+
+<!-- tocstop -->
+
 ## Installation
 
 Add this as a dependency to your project using [npm] with
@@ -46,7 +78,20 @@ $ npm install seam
 
 [npm]: https://www.npmjs.com/
 
-### Usage
+## Usage
+
+### 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,15 +103,375 @@ 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 })
+```
 
-const webhook = new SeamWebhook('webhook-secret')
-const data = webhook.verify(payload, headers)
+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 devices = await request.execute()
+```
+
+### Receiving Webhooks
+
+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/
+
 ## Development and Testing
 
 ### Quickstart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seam",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "JavaScript SDK for the Seam API written in TypeScript.",
   "type": "module",
   "main": "index.js",
@@ -52,6 +52,8 @@
     "lint": "eslint --ignore-path .gitignore .",
     "prelint": "prettier --check --ignore-path .gitignore .",
     "postversion": "git push --follow-tags",
+    "generate": "tsx generate-readme.ts",
+    "postgenerate": "markdown-toc -i README.md --bullets '-'",
     "example": "tsx examples",
     "example:inspect": "tsx --inspect examples",
     "format": "eslint --ignore-path .gitignore --fix .",
@@ -63,7 +65,7 @@
   },
   "dependencies": {
     "@seamapi/http": "0.25.2",
-    "@seamapi/types": "1.146.0",
+    "@seamapi/types": "1.147.1",
     "@seamapi/webhook": "1.0.0-rc.0",
     "seamapi-types": "1.42.0"
   },
@@ -77,6 +79,7 @@
     "eslint-plugin-simple-import-sort": "^12.0.0",
     "eslint-plugin-unused-imports": "^3.0.0",
     "landlubber": "^2.0.0",
+    "markdown-toc": "^1.2.0",
     "prettier": "^3.0.0",
     "tsc-alias": "^1.8.2",
     "tsup": "^8.0.1",