@seamapi/http 2.24.1 → 2.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +37 -0
  2. package/lib/error-interceptor.js +2 -2
  3. package/lib/error-interceptor.js.map +1 -1
  4. package/lib/resolve-action-attempt.d.ts +4 -4
  5. package/lib/resources/access-grant.d.ts +1 -1
  6. package/lib/resources/action-attempt.d.ts +871 -139
  7. package/lib/resources/event.d.ts +9 -4
  8. package/lib/routes/access-codes/access-codes.js +1 -1
  9. package/lib/routes/access-codes/access-codes.js.map +1 -1
  10. package/lib/routes/access-grants/access-grants.d.ts +25 -25
  11. package/lib/routes/access-methods/access-methods.d.ts +5 -5
  12. package/lib/routes/access-methods/access-methods.js +1 -1
  13. package/lib/routes/access-methods/access-methods.js.map +1 -1
  14. package/lib/routes/acs/encoders/simulate/simulate.d.ts +5 -5
  15. package/lib/routes/customers/customers.d.ts +185 -185
  16. package/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.js +1 -1
  17. package/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.js.map +1 -1
  18. package/lib/routes/thermostats/simulate/simulate.d.ts +8 -8
  19. package/lib/routes/thermostats/thermostats.d.ts +5 -5
  20. package/lib/routes/user-identities/user-identities.d.ts +5 -5
  21. package/lib/routes/user-identities/user-identities.js +1 -1
  22. package/lib/routes/user-identities/user-identities.js.map +1 -1
  23. package/lib/routes/workspaces/workspaces.d.ts +1 -1
  24. package/lib/seam-http-error.d.ts +16 -3
  25. package/lib/seam-http-error.js +18 -6
  26. package/lib/seam-http-error.js.map +1 -1
  27. package/lib/version.d.ts +1 -1
  28. package/lib/version.js +1 -1
  29. package/package.json +3 -3
  30. package/src/lib/error-interceptor.ts +6 -2
  31. package/src/lib/resolve-action-attempt.ts +8 -6
  32. package/src/lib/resources/access-grant.ts +1 -1
  33. package/src/lib/resources/action-attempt.ts +1101 -201
  34. package/src/lib/resources/event.ts +10 -5
  35. package/src/lib/routes/access-codes/access-codes.ts +1 -1
  36. package/src/lib/routes/access-grants/access-grants.ts +27 -27
  37. package/src/lib/routes/access-methods/access-methods.ts +6 -6
  38. package/src/lib/routes/acs/encoders/simulate/simulate.ts +5 -6
  39. package/src/lib/routes/customers/customers.ts +235 -236
  40. package/src/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.ts +1 -1
  41. package/src/lib/routes/thermostats/simulate/simulate.ts +9 -10
  42. package/src/lib/routes/thermostats/thermostats.ts +7 -7
  43. package/src/lib/routes/user-identities/user-identities.ts +6 -6
  44. package/src/lib/routes/workspaces/workspaces.ts +1 -1
  45. package/src/lib/seam-http-error.ts +43 -6
  46. package/src/lib/version.ts +1 -1
package/README.md CHANGED
@@ -371,6 +371,43 @@ const pages = seam.createPaginator(
371
371
  const devices = await pages.flattenToArray()
372
372
  ```
373
373
 
374
+ ### Error Handling
375
+
376
+ Requests rejected by the Seam API throw a `SeamHttpApiError` subclass
377
+ carrying the `statusCode`, the API error `code`, and the `requestId`.
378
+ The originating Axios error is retained as the standard `cause`.
379
+
380
+ #### Validation errors
381
+
382
+ When the API rejects a request because a parameter is invalid,
383
+ it throws a `SeamHttpInvalidInputError`.
384
+
385
+ Look up the messages for a parameter you are already rendering,
386
+ for example a field in a form:
387
+
388
+ ```ts
389
+ import { isSeamHttpInvalidInputError } from '@seamapi/http'
390
+
391
+ try {
392
+ await seam.devices.list({ device_ids: ['not-a-uuid'] })
393
+ } catch (err) {
394
+ if (isSeamHttpInvalidInputError(err)) {
395
+ console.log(err.getValidationErrorMessages('device_ids'))
396
+ }
397
+ }
398
+ ```
399
+
400
+ Or read every parameter that failed validation,
401
+ for example to show a summary of what went wrong:
402
+
403
+ ```ts
404
+ if (isSeamHttpInvalidInputError(err)) {
405
+ for (const { parameterName, errorMessages } of err.validationErrors) {
406
+ console.log(`${parameterName}: ${errorMessages.join(', ')}`)
407
+ }
408
+ }
409
+ ```
410
+
374
411
  ### Requests without a Workspace in scope
375
412
 
376
413
  Some Seam API endpoints do not require a workspace in scope.
@@ -9,12 +9,12 @@ export const errorInterceptor = async (err) => {
9
9
  if (status == null)
10
10
  throw err;
11
11
  if (status === 401) {
12
- throw new SeamHttpUnauthorizedError(requestId);
12
+ throw new SeamHttpUnauthorizedError(requestId, isApiErrorResponse(response) ? response.data.error : undefined, { cause: err });
13
13
  }
14
14
  if (!isApiErrorResponse(response))
15
15
  throw err;
16
16
  const { type } = response.data.error;
17
- const args = [response.data.error, status, requestId];
17
+ const args = [response.data.error, status, requestId, { cause: err }];
18
18
  if (type === 'invalid_input')
19
19
  throw new SeamHttpInvalidInputError(...args);
20
20
  throw new SeamHttpApiError(...args);
@@ -1 +1 @@
1
- {"version":3,"file":"error-interceptor.js","sourceRoot":"","sources":["../src/lib/error-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,YAAY,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAA;AAE7B,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,GAAY,EAAiB,EAAE;IACpE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC;QAAE,MAAM,GAAG,CAAA;IAEjC,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAA;IACxB,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAA;IAE/B,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAEnC,IAAI,MAAM,IAAI,IAAI;QAAE,MAAM,GAAG,CAAA;IAE7B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAA;IAChD,CAAC;IAED,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QAAE,MAAM,GAAG,CAAA;IAE5C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAA;IAEpC,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAA;IAE9D,IAAI,IAAI,KAAK,eAAe;QAAE,MAAM,IAAI,yBAAyB,CAAC,GAAG,IAAI,CAAC,CAAA;IAC1E,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAA;AACrC,CAAC,CAAA;AAED,MAAM,kBAAkB,GAAG,CACzB,QAAgC,EACmC,EAAE;IACrE,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAClC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAA;IAElC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAEjC,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC3C,IACE,OAAO,WAAW,KAAK,QAAQ;QAC/B,CAAC,WAAW,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAC3C,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QAC7C,OAAO,CACL,OAAO,IAAI,IAAI;YACf,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAC9B,IAAI,CAAC,KAAK,IAAI,IAAI;YAClB,MAAM,IAAI,IAAI,CAAC,KAAK;YACpB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YACnC,SAAS,IAAI,IAAI,CAAC,KAAK;YACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ,CACvC,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,CAAC,GAAe,EAAU,EAAE;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAA;IACrC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC5C,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAChC,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA"}
1
+ {"version":3,"file":"error-interceptor.js","sourceRoot":"","sources":["../src/lib/error-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,YAAY,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAA;AAE7B,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,GAAY,EAAiB,EAAE;IACpE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC;QAAE,MAAM,GAAG,CAAA;IAEjC,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAA;IACxB,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAA;IAE/B,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAEnC,IAAI,MAAM,IAAI,IAAI;QAAE,MAAM,GAAG,CAAA;IAE7B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CACjC,SAAS,EACT,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAC9D,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;IACH,CAAC;IAED,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QAAE,MAAM,GAAG,CAAA;IAE5C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAA;IAEpC,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAU,CAAA;IAE9E,IAAI,IAAI,KAAK,eAAe;QAAE,MAAM,IAAI,yBAAyB,CAAC,GAAG,IAAI,CAAC,CAAA;IAC1E,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAA;AACrC,CAAC,CAAA;AAED,MAAM,kBAAkB,GAAG,CACzB,QAAgC,EACmC,EAAE;IACrE,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAClC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAA;IAElC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAEjC,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC3C,IACE,OAAO,WAAW,KAAK,QAAQ;QAC/B,CAAC,WAAW,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAC3C,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QAC7C,OAAO,CACL,OAAO,IAAI,IAAI;YACf,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAC9B,IAAI,CAAC,KAAK,IAAI,IAAI;YAClB,MAAM,IAAI,IAAI,CAAC,KAAK;YACpB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YACnC,SAAS,IAAI,IAAI,CAAC,KAAK;YACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ,CACvC,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,CAAC,GAAe,EAAU,EAAE;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAA;IACrC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC5C,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAChC,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA"}
@@ -69,12 +69,12 @@ export declare class SeamActionAttemptTimeoutError<T extends ActionAttempt> exte
69
69
  /**
70
70
  * An action attempt that has succeeded.
71
71
  */
72
- export type SucceededActionAttempt<T extends ActionAttempt> = T & {
72
+ export type SucceededActionAttempt<T extends ActionAttempt> = Extract<T, {
73
73
  status: 'success';
74
- };
74
+ }>;
75
75
  /**
76
76
  * An action attempt that has failed.
77
77
  */
78
- export type FailedActionAttempt<T extends ActionAttempt> = T & {
78
+ export type FailedActionAttempt<T extends ActionAttempt> = Extract<T, {
79
79
  status: 'error';
80
- };
80
+ }>;
@@ -31,7 +31,7 @@ export type AccessGrant = {
31
31
  */
32
32
  display_name: string;
33
33
  /**
34
- * Human-readable sentence answering whether the user can currently get in, for example `Awaiting encoding` on an access method or `Upcoming` here. For display only. The wording is not stable and is not an enumeration — it may change at any time, so never compare against or branch on it. To make decisions, read `starts_at`, `ends_at`, `errors`, and the access methods' own fields.
34
+ * Human-readable sentence answering whether the user can currently get in, for example `Active`, `Awaiting issuance`, or `Upcoming`. For display only. The wording is not stable and is not an enumeration — it may change at any time, so never compare against or branch on it. To make decisions, read `starts_at`, `ends_at`, `errors`, and the access methods' own fields.
35
35
  */
36
36
  display_status: string;
37
37
  /**