seam 1.232.0 → 1.233.0

package/README.md

@@ -53,12 +53,19 @@ Instead, it builds on a core set of Seam modules:
   - [Advanced Usage](#advanced-usage)
     - [Additional Options](#additional-options)
     - [Setting the endpoint](#setting-the-endpoint)
+    - [Setting the request timeout](#setting-the-request-timeout)
     - [Configuring the Axios Client](#configuring-the-axios-client)
     - [Using the Axios Client](#using-the-axios-client)
     - [Overriding the Client](#overriding-the-client)
     - [Alternative endpoint path interface](#alternative-endpoint-path-interface)
     - [Inspecting the Request](#inspecting-the-request)
+    - [Serializing URL search params](#serializing-url-search-params)
   - [Command Line Interface](#command-line-interface)
+  - [Output](#output)
+  - [Pagination](#pagination-1)
+  - [JSON](#json)
+  - [Selecting an endpoint and a workspace](#selecting-an-endpoint-and-a-workspace)
+  - [Environment variables](#environment-variables)
   - [Receiving Webhooks](#receiving-webhooks)
 - [Development and Testing](#development-and-testing)
   - [Quickstart](#quickstart)
@@ -468,6 +475,7 @@ the constructor takes some advanced options that affect behavior.
 const seam = new Seam({
   apiKey: 'your-api-key',
   endpoint: 'https://example.com',
+  timeout: 30000,
   axiosOptions: {},
   axiosRetryOptions: {},
 })
@@ -479,6 +487,7 @@ these options may be passed in as the last argument.
 ```ts
 const seam = Seam.fromApiKey('some-api-key', {
   endpoint: 'https://example.com',
+  timeout: 30000,
   axiosOptions: {},
   axiosRetryOptions: {},
 })
@@ -492,12 +501,39 @@ This option corresponds to the Axios `baseURL` setting.
 
 Either pass the `endpoint` option, or set the `SEAM_ENDPOINT` environment variable.
 
+#### Setting the request timeout
+
+Requests time out after 30 seconds by default.
+Pass the `timeout` option, in milliseconds, to override this:
+
+```ts
+const seam = new Seam({
+  apiKey: 'your-api-key',
+  timeout: 60000,
+})
+```
+
+Set `timeout` to `0` to disable the timeout entirely.
+A request that times out rejects with an Axios `ETIMEDOUT` error.
+Timed-out idempotent requests are retried according to the retry options, with
+the timeout reset for each attempt. Non-idempotent requests are not retried by
+default.
+
 #### 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.
 
+By default, the SDK makes up to three attempts: the initial request and two
+retries. Retries are limited to `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE`
+requests that fail because of a transport error, timeout, HTTP 429 response, or
+HTTP 5xx response. `POST` and `PATCH` requests are not retried.
+
+Retries use exponential backoff with jitter: approximately 200–240 ms before
+the first retry and 400–480 ms before the second. A longer `Retry-After` header
+is honored. The request timeout is reset for each attempt.
+
 [axiosOptions]: https://axios-http.com/docs/config_defaults
 [axiosRetryOptions]: https://github.com/softonic/axios-retry
 
@@ -550,11 +586,69 @@ console.log(`${request.method} ${request.url}`, JSON.stringify(request.body))
 const devices = await request.execute()
 ```
 
+#### Serializing URL search params
+
+The Seam API parses URL search params as complex types.
+If you call it with your own HTTP client, use `serializeUrlSearchParams`:
+
+```ts
+import axios from 'axios'
+import { serializeUrlSearchParams } from 'seam'
+
+await axios.get('https://connect.getseam.com/devices/list', {
+  params: { device_ids: ['device1', 'device2'] },
+  paramsSerializer: serializeUrlSearchParams,
+  headers: { Authorization: 'Bearer your-api-key' },
+})
+```
+
+or `updateUrlSearchParams`:
+
+```ts
+import { updateUrlSearchParams } from 'seam'
+
+const searchParams = new URLSearchParams()
+updateUrlSearchParams(searchParams, { device_ids: ['device1', 'device2'] })
+
+Array.from(searchParams)
+// => [['device_ids', 'device1'], ['device_ids', 'device2'], ['_strict', 'true']]
+
+searchParams.toString()
+// => 'device_ids=device1&device_ids=device2&_strict=true'
+```
+
+The helpers wrap the [reference implementation].
+The serialization defines the name and string value of each search param.
+[`URLSearchParams`][URLSearchParams] holds those pairs and renders the query string:
+The `_strict=true` parameter is added to any non-empty query so the Seam API uses
+strict, schema-aware parsing.
+A query with no serializable params remains empty.
+
+A param set to `undefined` is omitted, while a param set to `null` is serialized
+to an empty value, which the Seam API reads as null.
+A param that cannot be represented raises an `UnserializableParamError`.
+The Seam API parses these params with the corresponding [parser].
+
+[URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+[reference implementation]: https://github.com/seamapi/url-search-params-serializer
+[parser]: https://github.com/seamapi/url-search-params-parser
+
 ### Command Line Interface
 
-Every `seam` command is interactive and will prompt you for any missing
-required properties with helpful suggestions. To avoid automatic behavior,
-pass `-y`.
+Every `seam` command makes its request as soon as every required property is
+given. When something is missing, the CLI prompts you for it with helpful
+suggestions.
+
+Pass `--interactive` (or `-i`) to always be prompted to review and edit
+properties before the request is made. The prompt is prefilled with whatever
+you passed as arguments or piped in as JSON, and each property you open is
+prefilled with the value it has, ready to edit rather than retype. This is the
+way to add optional properties, or to check a request before making it.
+
+For scripts and CI, pass `--non-interactive` (or `-y`) to never be prompted.
+The command must then be complete: if the command itself is ambiguous, or any
+required property is missing, the CLI exits with an error naming what is
+missing instead of asking for it.
 
 To take a project from zero to a working Seam integration, run the
 [Seam Wizard] from the project's root:
@@ -581,7 +675,19 @@ seam connect-webviews create
 # List devices in your workspace
 seam devices list
 
-MY_DOOR=$(seam devices get --name "Front Door" --id-only)
+# Review and edit filters before listing devices
+seam devices list --interactive
+
+# List devices, failing instead of prompting
+seam devices list --non-interactive
+
+# Fails with: Missing required parameter for /locks/unlock_door: --device-id
+seam locks unlock-door --non-interactive
+
+# Fails with: Unknown parameter for /devices/list: --limitt
+seam devices list --limitt 5
+
+MY_DOOR=$(seam devices get --name "Front Door" | jq -r '.device.device_id')
 
 # Unlock a lock
 seam locks unlock-door --device-id $MY_DOOR
@@ -593,6 +699,163 @@ seam access-codes create --code "1234" --name "My Code"
 seam access-codes list --device-id $MY_DOOR
 ```
 
+### Output
+
+Only the response is written to stdout, so any command may be piped or
+redirected. Prompts, progress, and other information are written to stderr.
+
+The response is trimmed to the response key and pagination: no other top level
+fields are reported.
+
+```bash
+# The response, and nothing else, ends up in the file
+seam devices list > devices.json
+
+# Prompts and progress still show up in the terminal
+seam devices list | jq '.devices[].device_id'
+```
+
+### Pagination
+
+Every command that paginates accepts `--page-cursor` to select a page of
+results, alongside `--limit` for the size of that page. Each response reports
+its `pagination`, whose `next_page_cursor` is the cursor for the page after it.
+
+```bash
+# The first page, and the cursor for the next one
+seam devices list --limit 2 | jq '.pagination.next_page_cursor'
+
+# The page after it
+seam devices list --limit 2 --page-cursor "$CURSOR"
+```
+
+A cursor is opaque: pass it back exactly as it was reported, and do not build
+one yourself. Run `seam <command> --help` to see whether a command paginates.
+
+### JSON
+
+Request params may be piped or redirected in as a JSON object, or passed
+inline with `--raw`. Params given as arguments win over raw or stdin params.
+
+An argument the command does not accept is an error, so a typo is reported
+rather than sent. Params read from stdin are passed through as given, so
+anything the API itself accepts may be sent that way.
+
+```bash
+# Read params from a file
+seam locks unlock-door < params.json
+
+# Or from another program
+echo '{"device_id": "'"$MY_DOOR"'"}' | seam locks unlock-door
+
+# Pass request params inline as JSON
+seam devices list --raw '{"search":"bar"}'
+
+# --device-id wins over any device_id in params.json
+seam devices list --limit 5 < params.json
+```
+
+Pass `--json` to write the response as JSON. It is enabled automatically
+whenever stdout is not a terminal, so piping and redirecting produce JSON
+without passing anything. Pass `--no-json` to opt out and get the pretty
+format instead.
+
+```bash
+# Both write JSON
+seam devices list --json
+seam devices list | jq
+
+# Pretty printed, even though it is piped
+seam devices list --no-json | less
+```
+
+Without a terminal to prompt on, the CLI behaves as though
+`--non-interactive` was given: rather than waiting for an answer nobody can
+give, it exits with an error naming what is missing.
+
+```bash
+$ echo '{}' | seam locks unlock-door
+Missing required parameter for /locks/unlock_door: --device-id
+```
+
+An error exits non-zero. A request that fails reports its `error` on stdout,
+so it can be inspected from a pipe; anything else is written to stderr only.
+
+### Selecting an endpoint and a workspace
+
+Two settings say where commands go, and one command each stores them:
+
+```bash
+# Every later command runs against this endpoint
+seam select endpoint https://connect.getseam.com
+
+# ...and this workspace
+seam select workspace $MY_WORKSPACE
+```
+
+Run either without a value to pick one interactively.
+
+To send a single command somewhere else, pass `--endpoint` or
+`--workspace-id` to that command. They override what is selected for that one
+invocation and store nothing:
+
+```bash
+# List devices in another workspace, without switching to it
+seam devices list --workspace-id $OTHER_WORKSPACE
+
+# Run one command against a local Seam Connect instance
+seam devices list --endpoint http://localhost:3020
+
+# Log in to another endpoint: the token is stored for that endpoint,
+# and the selected one is left alone
+seam login --endpoint http://localhost:3020 --token $LOCAL_KEY
+```
+
+Because the two flags never store anything, they are refused on the commands
+that do: `seam select endpoint --endpoint <url>` is an error, and the value
+belongs after the command instead.
+
+### Environment variables
+
+Everything `seam login`, `seam select workspace`, and `seam select endpoint`
+store may be given in the environment instead:
+
+- `SEAM_CLI_TOKEN`: a Personal Access Token or API Key,
+- `SEAM_CLI_WORKSPACE_ID`: the workspace requests are made against,
+- `SEAM_CLI_ENDPOINT`: the Seam API endpoint requests are made to.
+
+Any of them, all of them, or none of them may be set. Each one wins over the
+corresponding stored value and is in turn overridden by `--endpoint` or
+`--workspace-id`, which makes them useful for CI or for working against
+another workspace for a whole shell.
+
+```bash
+# One command against another workspace
+SEAM_CLI_WORKSPACE_ID=$OTHER_WORKSPACE seam devices list
+
+# No login needed: authenticate from the environment
+export SEAM_CLI_TOKEN=$SEAM_API_KEY
+seam devices list
+
+# Work against a local Seam Connect instance
+SEAM_CLI_ENDPOINT=http://localhost:3020 seam devices list
+```
+
+An API Key is scoped to a single workspace, so it needs no workspace id. A
+Personal Access Token works across workspaces, so it needs one from
+`--workspace-id`, `SEAM_CLI_WORKSPACE_ID`, or `seam select workspace`.
+
+The command that would store an overridden value fails rather than storing
+something the environment ignores: `seam login` and `seam logout` while
+`SEAM_CLI_TOKEN` is set, `seam select workspace` while
+`SEAM_CLI_WORKSPACE_ID` is set, and `seam select endpoint` while
+`SEAM_CLI_ENDPOINT` is set. Unset the variable to use those commands.
+
+```bash
+$ SEAM_CLI_TOKEN=$SEAM_API_KEY seam login
+Cannot log in while SEAM_CLI_TOKEN is set: it overrides what would be stored. Unset SEAM_CLI_TOKEN to log in.
+```
+
 ### Receiving Webhooks
 
 The Seam API implements webhooks using [Svix](https://www.svix.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seam",
-  "version": "1.232.0",
+  "version": "1.233.0",
   "description": "JavaScript SDK for the Seam API written in TypeScript.",
   "type": "module",
   "main": "index.js",
@@ -73,9 +73,10 @@
       "version": "^11.0.0 || ^10.0.0"
     }
   },
+  "packageManager": "npm@11.19.0",
   "dependencies": {
-    "@seamapi/cli": "0.24.1",
-    "@seamapi/http": "2.3.1",
+    "@seamapi/cli": "0.28.0",
+    "@seamapi/http": "2.11.2",
     "@seamapi/webhook": "1.4.1"
   },
   "devDependencies": {