feat: Add waitForActionAttempt option (#22)

Co-authored-by: Seam Bot <devops@getseam.com>

Author: razor-x

.gitattributes

@@ -0,0 +1 @@
+src/lib/seam/connect/routes/** linguist-generated

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)
@@ -145,6 +145,73 @@ const seam = SeamHttp.fromConsoleSessionToken(
 )
 ```
 
+### 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,

examples/index.ts

@@ -12,6 +12,8 @@ import landlubber, {
 
 import { SeamHttp } from '@seamapi/http/connect'
 
+import * as locks from './locks.js'
+import * as unlock from './unlock.js'
 import * as workspace from './workspace.js'
 
 export type Handler<Options = EmptyOptions> = DefaultHandler<Options, Context>
@@ -22,7 +24,7 @@ interface ClientContext {
   seam: SeamHttp
 }
 
-const commands = [workspace]
+const commands = [locks, unlock, workspace]
 
 const createAppContext: MiddlewareFunction = async (argv) => {
   const apiKey = argv['api-key']

examples/locks.ts

@@ -0,0 +1,17 @@
+import type { Builder, Command, Describe } from 'landlubber'
+
+import type { Handler } from './index.js'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface Options {}
+
+export const command: Command = 'locks'
+
+export const describe: Describe = 'List locks'
+
+export const builder: Builder = {}
+
+export const handler: Handler<Options> = async ({ seam, logger }) => {
+  const devices = await seam.locks.list()
+  logger.info({ devices }, 'locks')
+}

examples/unlock.ts

@@ -0,0 +1,50 @@
+import type { Builder, Command, Describe } from 'landlubber'
+
+import {
+  isSeamActionAttemptFailedError,
+  isSeamActionAttemptTimeoutError,
+  type LocksUnlockDoorResponse,
+} from '@seamapi/http/connect'
+
+import type { Handler } from './index.js'
+
+interface Options {
+  deviceId: string
+}
+
+export const command: Command = 'unlock deviceId'
+
+export const describe: Describe = 'Unlock a door'
+
+export const builder: Builder = {
+  deviceId: {
+    type: 'string',
+    describe: 'Device id of lock to unlock',
+  },
+}
+
+export const handler: Handler<Options> = async ({ deviceId, seam, logger }) => {
+  try {
+    const actionAttempt = await seam.locks.unlockDoor(
+      {
+        device_id: deviceId,
+      },
+      { waitForActionAttempt: true },
+    )
+    logger.info({ actionAttempt }, 'unlocked')
+  } catch (err: unknown) {
+    if (isSeamActionAttemptFailedError<UnlockDoorActionAttempt>(err)) {
+      logger.info({ err }, 'Could not unlock the door')
+      return
+    }
+
+    if (isSeamActionAttemptTimeoutError<UnlockDoorActionAttempt>(err)) {
+      logger.info({ err }, 'Door took too long to unlock')
+      return
+    }
+
+    throw err
+  }
+}
+
+type UnlockDoorActionAttempt = LocksUnlockDoorResponse['action_attempt']

generate-routes.ts

@@ -256,12 +256,21 @@ import {
   type SeamHttpOptionsWithPersonalAccessToken,
 } from 'lib/seam/connect/options.js'
 import { parseOptions } from 'lib/seam/connect/parse-options.js'
+import {
+  resolveActionAttempt,
+  type ResolveActionAttemptOptions,
+} from 'lib/seam/connect/resolve-action-attempt.js'
 
 ${
   namespace === 'client_sessions'
     ? ''
     : "import { SeamHttpClientSessions } from './client-sessions.js'"
 }
+${
+  namespace === 'action_attempts'
+    ? ''
+    : "import { SeamHttpActionAttempts } from './action-attempts.js'"
+}
 ${subresources
   .map((subresource) => renderSubresourceImport(subresource, namespace))
   .join('\n')}
@@ -314,6 +323,7 @@ const renderClassMethod = ({
       name,
       namespace,
     })},
+    ${renderClassMethodOptions({ resource })}
   ): Promise<${
     resource === null
       ? 'void'
@@ -330,10 +340,51 @@ const renderClassMethod = ({
         requestFormat === 'params' ? 'params,' : ''
       } ${requestFormat === 'body' ? 'data: body,' : ''}
     })
+    ${
+      resource === 'action_attempt'
+        ? `if (waitForActionAttempt != null && waitForActionAttempt !== false) {
+            return resolveActionAttempt(
+              data.${resource},
+              SeamHttpActionAttempts.fromClient(this.client),
+              typeof waitForActionAttempt === 'boolean' ? {} : waitForActionAttempt,
+            )
+          }`
+        : ''
+    }
     ${resource === null ? '' : `return data.${resource}`}
   }
   `
 
+const renderClassMethodOptions = ({
+  resource,
+}: Pick<Endpoint, 'resource'>): string => {
+  if (resource === 'action_attempt') {
+    return `{ waitForActionAttempt = false }: ${renderClassMethodOptionsTypeDef(
+      { resource },
+    )} = {},`
+  }
+  return ''
+}
+
+const renderClassMethodOptionsType = ({
+  name,
+  namespace,
+}: Pick<Endpoint, 'name' | 'namespace'>): string =>
+  [pascalCase(namespace), pascalCase(name), 'Options'].join('')
+
+const renderClassMethodOptionsTypeDef = ({
+  resource,
+}: Pick<Endpoint, 'resource'>): string => {
+  if (resource === 'action_attempt') {
+    return `
+      {
+        waitForActionAttempt?: boolean | Partial<ResolveActionAttemptOptions>
+      }
+    `
+  }
+  return 'never'
+}
+
 const renderSubresourceMethod = (
   subresource: string,
   namespace: string,
@@ -354,6 +405,7 @@ const renderEndpointExports = ({
   name,
   path,
   namespace,
+  resource,
   requestFormat,
 }: Endpoint): string => `
 export type ${renderRequestType({
@@ -364,6 +416,11 @@ export type ${renderRequestType({
 export type ${renderResponseType({ name, namespace })}= SetNonNullable<
   Required<RouteResponse<'${path}'>>
 >
+
+export type ${renderClassMethodOptionsType({
+  name,
+  namespace,
+})} = ${renderClassMethodOptionsTypeDef({ resource })}
   `
 
 const renderRequestType = ({

src/lib/seam/connect/action-attempt-types.ts

@@ -0,0 +1,22 @@
+// UPSTREAM: These types should be provided by @seamapi/types/connect.
+
+export interface ActionAttempt {
+  action_attempt_id: string
+  status: 'pending' | 'error' | 'success'
+}
+
+export type SuccessfulActionAttempt<T extends ActionAttempt> = T & {
+  status: 'success'
+}
+
+export type PendingActionAttempt<T extends ActionAttempt> = T & {
+  status: 'pending'
+}
+
+export type FailedActionAttempt<T extends ActionAttempt> = T & {
+  status: 'error'
+  error: {
+    type: string
+    message: string
+  }
+}

src/lib/seam/connect/index.ts

@@ -1,6 +1,14 @@
 export { SeamHttpInvalidTokenError } from './auth.js'
 export * from './error-interceptor.js'
 export * from './options.js'
+export {
+  isSeamActionAttemptError,
+  isSeamActionAttemptFailedError,
+  isSeamActionAttemptTimeoutError,
+  SeamActionAttemptError,
+  SeamActionAttemptFailedError,
+  SeamActionAttemptTimeoutError,
+} from './resolve-action-attempt.js'
 export * from './routes/index.js'
 export * from './seam-http.js'
 export * from './seam-http-error.js'