@seamapi/http 0.7.0 → 0.8.0

package/README.md

@@ -1,4 +1,4 @@
-# Seam HTTP client.
+# Seam HTTP Client
 
 [![npm](https://img.shields.io/npm/v/@seamapi/http.svg)](https://www.npmjs.com/package/@seamapi/http)
 [![GitHub Actions](https://github.com/seamapi/javascript-http/actions/workflows/check.yml/badge.svg)](https://github.com/seamapi/javascript-http/actions/workflows/check.yml)
@@ -59,27 +59,17 @@ or with the more ergonomic static factory methods.
 An API key is scoped to a single workspace and should only be used on the server.
 Obtain one from the Seam Console.
 
-##### Set the `SEAM_API_KEY` environment variable
-
 ```ts
+// Set the `SEAM_API_KEY` environment variable
 const seam = new SeamHttp()
-```
-
-##### Pass as the first argument to the constructor
 
-```ts
+// Pass as the first argument to the constructor
 const seam = new SeamHttp('your-api-key')
-```
 
-##### Pass as an option the constructor
-
-```ts
+// Pass as an option the constructor
 const seam = new SeamHttp({ apiKey: 'your-api-key' })
-```
 
-##### Use the factory method
-
-```ts
+// Use the factory method
 const seam = SeamHttp.fromApiKey('your-api-key')
 ```
 
@@ -87,15 +77,11 @@ const seam = SeamHttp.fromApiKey('your-api-key')
 
 A Client Session Token is scoped to a client session and should only be used on the client.
 
-##### Pass as an option the constructor
-
 ```ts
+// Pass as an option the constructor
 const seam = new SeamHttp({ clientSessionToken: 'some-client-session-token' })
-```
-
-##### Use the factory method
 
-```ts
+// Use the factory method
 const seam = SeamHttp.fromClientSessionToken('some-client-session-token')
 ```
 
@@ -123,18 +109,15 @@ 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.
 
-##### Pass as an option the constructor
-
 ```ts
+// Pass as an option the constructor
+
 const seam = new SeamHttp({
   personalAccessToken: 'your-personal-access-token',
   workspaceId: 'your-workspace-id',
 })
-```
-
-##### Use the factory method
 
-```ts
+// Use the factory method
 const seam = SeamHttp.fromPersonalAccessToken(
   'some-console-session-token',
   'your-workspace-id',
@@ -148,24 +131,87 @@ 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.
 
-##### Pass as an option the constructor
-
 ```ts
+// Pass as an option the constructor
 const seam = new SeamHttp({
   consoleSessionToken: 'some-console-session-token',
   workspaceId: 'your-workspace-id',
 })
-```
-
-##### Use the factory method
 
-```ts
+// Use the factory method
 const seam = SeamHttp.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:
+
+```ts
+await seam.locks.unlockDoor(
+  { device_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 {
+  SeamHttp,
+  isSeamActionAttemptFailedError,
+  isSeamActionAttemptTimeoutError,
+} from '@seamapi/http/connect'
+
+const seam = new SeamHttp('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
+
 ### Advanced Usage
 
 In addition the various authentication options,

package/dist/connect.cjs

@@ -260,7 +260,7 @@ var getAuthHeadersForConsoleSessionToken = ({
   }
   return {
     authorization: `Bearer ${consoleSessionToken}`,
-    ...workspaceId != null ? { "seam-workspace-id": workspaceId } : {}
+    ...workspaceId != null ? { "seam-workspace": workspaceId } : {}
   };
 };
 var getAuthHeadersForPersonalAccessToken = ({
@@ -290,7 +290,7 @@ var getAuthHeadersForPersonalAccessToken = ({
   }
   return {
     authorization: `Bearer ${personalAccessToken}`,
-    ...workspaceId != null ? { "seam-workspace-id": workspaceId } : {}
+    ...workspaceId != null ? { "seam-workspace": workspaceId } : {}
   };
 };
 var getAuthHeadersForPublishableKey = (publishableKey) => {
@@ -431,6 +431,81 @@ var isApiErrorResponse = (response) => {
   return false;
 };
 
+// src/lib/seam/connect/resolve-action-attempt.ts
+var resolveActionAttempt = async (actionAttempt, actionAttempts, { timeout = 5e3, pollingInterval = 500 }) => {
+  let timeoutRef;
+  const timeoutPromise = new Promise(
+    (_resolve, reject) => {
+      timeoutRef = globalThis.setTimeout(() => {
+        reject(new SeamActionAttemptTimeoutError(actionAttempt, timeout));
+      }, timeout);
+    }
+  );
+  try {
+    return await Promise.race([
+      pollActionAttempt(actionAttempt, actionAttempts, { pollingInterval }),
+      timeoutPromise
+    ]);
+  } finally {
+    if (timeoutRef != null)
+      globalThis.clearTimeout(timeoutRef);
+  }
+};
+var pollActionAttempt = async (actionAttempt, actionAttempts, options) => {
+  if (isSuccessfulActionAttempt(actionAttempt)) {
+    return actionAttempt;
+  }
+  if (isFailedActionAttempt(actionAttempt)) {
+    throw new SeamActionAttemptFailedError(actionAttempt);
+  }
+  await new Promise((resolve) => setTimeout(resolve, options.pollingInterval));
+  const nextActionAttempt = await actionAttempts.get({
+    action_attempt_id: actionAttempt.action_attempt_id
+  });
+  return await pollActionAttempt(
+    nextActionAttempt,
+    actionAttempts,
+    options
+  );
+};
+var isSeamActionAttemptError = (error) => {
+  return error instanceof SeamActionAttemptError;
+};
+var SeamActionAttemptError = class extends Error {
+  constructor(message, actionAttempt) {
+    super(message);
+    this.name = this.constructor.name;
+    this.actionAttempt = actionAttempt;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var isSeamActionAttemptFailedError = (error) => {
+  return error instanceof SeamActionAttemptFailedError;
+};
+var SeamActionAttemptFailedError = class extends SeamActionAttemptError {
+  constructor(actionAttempt) {
+    super(actionAttempt.error.message, actionAttempt);
+    this.name = this.constructor.name;
+    this.code = actionAttempt.error.type;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var isSeamActionAttemptTimeoutError = (error) => {
+  return error instanceof SeamActionAttemptTimeoutError;
+};
+var SeamActionAttemptTimeoutError = class extends SeamActionAttemptError {
+  constructor(actionAttempt, timeout) {
+    super(
+      `Timed out waiting for action action attempt after ${timeout}ms`,
+      actionAttempt
+    );
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var isSuccessfulActionAttempt = (actionAttempt) => actionAttempt.status === "success";
+var isFailedActionAttempt = (actionAttempt) => actionAttempt.status === "error";
+
 // src/lib/params-serializer.ts
 var paramsSerializer = (params) => {
   const searchParams = new URLSearchParams();
@@ -1398,12 +1473,21 @@ var SeamHttpActionAttempts = class _SeamHttpActionAttempts {
     }
     return new _SeamHttpActionAttempts(constructorOptions);
   }
-  async get(body) {
+  async get(body, {
+    waitForActionAttempt = false
+  } = {}) {
     const { data } = await this.client.request({
       url: "/action_attempts/get",
       method: "post",
       data: body
     });
+    if (waitForActionAttempt != null && waitForActionAttempt !== false) {
+      return await resolveActionAttempt(
+        data.action_attempt,
+        _SeamHttpActionAttempts.fromClient(this.client),
+        typeof waitForActionAttempt === "boolean" ? {} : waitForActionAttempt
+      );
+    }
     return data.action_attempt;
   }
   async list(body) {
@@ -1913,20 +1997,38 @@ var SeamHttpLocks = class _SeamHttpLocks {
     });
     return data.devices;
   }
-  async lockDoor(body) {
+  async lockDoor(body, {
+    waitForActionAttempt = false
+  } = {}) {
     const { data } = await this.client.request({
       url: "/locks/lock_door",
       method: "post",
       data: body
     });
+    if (waitForActionAttempt != null && waitForActionAttempt !== false) {
+      return await resolveActionAttempt(
+        data.action_attempt,
+        SeamHttpActionAttempts.fromClient(this.client),
+        typeof waitForActionAttempt === "boolean" ? {} : waitForActionAttempt
+      );
+    }
     return data.action_attempt;
   }
-  async unlockDoor(body) {
+  async unlockDoor(body, {
+    waitForActionAttempt = false
+  } = {}) {
     const { data } = await this.client.request({
       url: "/locks/unlock_door",
       method: "post",
       data: body
     });
+    if (waitForActionAttempt != null && waitForActionAttempt !== false) {
+      return await resolveActionAttempt(
+        data.action_attempt,
+        SeamHttpActionAttempts.fromClient(this.client),
+        typeof waitForActionAttempt === "boolean" ? {} : waitForActionAttempt
+      );
+    }
     return data.action_attempt;
   }
 };
@@ -2736,6 +2838,9 @@ var SeamHttpMultiWorkspace = class _SeamHttpMultiWorkspace {
   }
 };
 
+exports.SeamActionAttemptError = SeamActionAttemptError;
+exports.SeamActionAttemptFailedError = SeamActionAttemptFailedError;
+exports.SeamActionAttemptTimeoutError = SeamActionAttemptTimeoutError;
 exports.SeamHttp = SeamHttp;
 exports.SeamHttpAccessCodes = SeamHttpAccessCodes;
 exports.SeamHttpAccessCodesUnmanaged = SeamHttpAccessCodesUnmanaged;
@@ -2768,6 +2873,9 @@ exports.SeamHttpWebhooks = SeamHttpWebhooks;
 exports.SeamHttpWorkspaces = SeamHttpWorkspaces;
 exports.UnserializableParamError = UnserializableParamError;
 exports.errorInterceptor = errorInterceptor;
+exports.isSeamActionAttemptError = isSeamActionAttemptError;
+exports.isSeamActionAttemptFailedError = isSeamActionAttemptFailedError;
+exports.isSeamActionAttemptTimeoutError = isSeamActionAttemptTimeoutError;
 exports.isSeamHttpApiError = isSeamHttpApiError;
 exports.isSeamHttpInvalidInputError = isSeamHttpInvalidInputError;
 exports.isSeamHttpMultiWorkspaceOptionsWithClient = isSeamHttpMultiWorkspaceOptionsWithClient;