@isnap/sdk 2.3.0 → 2.3.1

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 (86) hide show
  1. package/CHANGELOG.md +65 -40
  2. package/README.md +360 -167
  3. package/dist/client.d.ts +35 -49
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +44 -58
  6. package/dist/client.js.map +1 -1
  7. package/dist/config.d.ts +6 -6
  8. package/dist/config.js +6 -6
  9. package/dist/generated/openapi.d.ts +403 -14
  10. package/dist/internal/sleep.d.ts +2 -2
  11. package/dist/internal/sleep.js +5 -5
  12. package/dist/internal/sleep.js.map +1 -1
  13. package/dist/resources/apps.d.ts +11 -18
  14. package/dist/resources/apps.d.ts.map +1 -1
  15. package/dist/resources/apps.js +11 -18
  16. package/dist/resources/apps.js.map +1 -1
  17. package/dist/resources/area-codes.d.ts +5 -6
  18. package/dist/resources/area-codes.d.ts.map +1 -1
  19. package/dist/resources/area-codes.js +5 -6
  20. package/dist/resources/area-codes.js.map +1 -1
  21. package/dist/resources/attachments.d.ts +51 -17
  22. package/dist/resources/attachments.d.ts.map +1 -1
  23. package/dist/resources/attachments.js +42 -22
  24. package/dist/resources/attachments.js.map +1 -1
  25. package/dist/resources/byod.d.ts +14 -4
  26. package/dist/resources/byod.d.ts.map +1 -1
  27. package/dist/resources/byod.js +14 -4
  28. package/dist/resources/byod.js.map +1 -1
  29. package/dist/resources/chats.d.ts +30 -22
  30. package/dist/resources/chats.d.ts.map +1 -1
  31. package/dist/resources/chats.js +29 -21
  32. package/dist/resources/chats.js.map +1 -1
  33. package/dist/resources/lines.d.ts +240 -266
  34. package/dist/resources/lines.d.ts.map +1 -1
  35. package/dist/resources/lines.js +240 -266
  36. package/dist/resources/lines.js.map +1 -1
  37. package/dist/resources/lookup.d.ts +10 -13
  38. package/dist/resources/lookup.d.ts.map +1 -1
  39. package/dist/resources/lookup.js +10 -13
  40. package/dist/resources/lookup.js.map +1 -1
  41. package/dist/resources/macos-sessions.d.ts +42 -36
  42. package/dist/resources/macos-sessions.d.ts.map +1 -1
  43. package/dist/resources/macos-sessions.js +24 -22
  44. package/dist/resources/macos-sessions.js.map +1 -1
  45. package/dist/resources/messages.d.ts +35 -25
  46. package/dist/resources/messages.d.ts.map +1 -1
  47. package/dist/resources/messages.js +30 -19
  48. package/dist/resources/messages.js.map +1 -1
  49. package/dist/resources/preorders.d.ts +42 -47
  50. package/dist/resources/preorders.d.ts.map +1 -1
  51. package/dist/resources/preorders.js +42 -47
  52. package/dist/resources/preorders.js.map +1 -1
  53. package/dist/resources/trial.d.ts +30 -21
  54. package/dist/resources/trial.d.ts.map +1 -1
  55. package/dist/resources/trial.js +30 -21
  56. package/dist/resources/trial.js.map +1 -1
  57. package/dist/resources/webhooks.d.ts +39 -22
  58. package/dist/resources/webhooks.d.ts.map +1 -1
  59. package/dist/resources/webhooks.js +39 -22
  60. package/dist/resources/webhooks.js.map +1 -1
  61. package/dist/retry.d.ts +9 -10
  62. package/dist/retry.d.ts.map +1 -1
  63. package/dist/retry.js +11 -12
  64. package/dist/retry.js.map +1 -1
  65. package/dist/types.d.ts +10 -0
  66. package/dist/types.d.ts.map +1 -1
  67. package/dist/version.d.ts +1 -1
  68. package/dist/version.d.ts.map +1 -1
  69. package/dist/version.js +13 -37
  70. package/dist/version.js.map +1 -1
  71. package/dist/webhooks/parse.d.ts +10 -9
  72. package/dist/webhooks/parse.d.ts.map +1 -1
  73. package/dist/webhooks/parse.js +14 -13
  74. package/dist/webhooks/parse.js.map +1 -1
  75. package/dist/webhooks/types.d.ts +74 -110
  76. package/dist/webhooks/types.d.ts.map +1 -1
  77. package/dist/webhooks/types.js.map +1 -1
  78. package/dist/webhooks/verify.d.ts +27 -29
  79. package/dist/webhooks/verify.d.ts.map +1 -1
  80. package/dist/webhooks/verify.js +29 -35
  81. package/dist/webhooks/verify.js.map +1 -1
  82. package/examples/handle-webhook.ts +146 -0
  83. package/examples/paginate-messages.ts +54 -0
  84. package/examples/send-message.ts +37 -0
  85. package/examples/upload-attachment.ts +91 -0
  86. package/package.json +4 -8
@@ -1,62 +1,79 @@
1
1
  import { paginate } from '../pagination.js';
2
2
  import { BaseResource } from './base.js';
3
3
  export class WebhooksResource extends BaseResource {
4
- /** `GET /v1/webhooks` — list all webhook subscriptions for the calling account. */
4
+ /** `GET /v1/webhooks`: every webhook subscription of your account, in one response. */
5
5
  list(opts) {
6
6
  return this.client.request('GET', '/v1/webhooks', undefined, opts);
7
7
  }
8
8
  /**
9
- * `POST /v1/webhooks` — create a subscription. Plaintext `secret` is
10
- * returned ONCE in the create response; persist it then. Subsequent
11
- * GETs do not include it.
9
+ * `POST /v1/webhooks`: create a webhook subscription. The signing `secret`
10
+ * is in this result: store it. Apart from `rotateSecret`, no other operation
11
+ * returns it.
12
+ *
13
+ * The API does not deduplicate this call: a retry after a lost response
14
+ * creates a second subscription.
12
15
  */
13
16
  create(body, opts) {
14
17
  return this.client.request('POST', '/v1/webhooks', body, opts);
15
18
  }
16
- /** `GET /v1/webhooks/{id}` — fetch a single webhook subscription. */
19
+ /** `GET /v1/webhooks/{id}`: one webhook subscription. */
17
20
  get(id, opts) {
18
21
  return this.client.request('GET', `/v1/webhooks/${encodeURIComponent(id)}`, undefined, opts);
19
22
  }
20
- /** `PATCH /v1/webhooks/{id}` — partial update of url / events / line_ids / active flag. */
23
+ /** `PATCH /v1/webhooks/{id}`: change the `url`, `events`, `line_ids` or `active` of a subscription. */
21
24
  update(id, body, opts) {
22
25
  return this.client.request('PATCH', `/v1/webhooks/${encodeURIComponent(id)}`, body, opts);
23
26
  }
24
- /** `DELETE /v1/webhooks/{id}` — delete a subscription. Returns 204. */
27
+ /**
28
+ * `DELETE /v1/webhooks/{id}`: delete a subscription, with its secret and its
29
+ * delivery records. Resolves with `undefined`.
30
+ */
25
31
  delete(id, opts) {
26
32
  return this.client.request('DELETE', `/v1/webhooks/${encodeURIComponent(id)}`, undefined, opts);
27
33
  }
28
34
  /**
29
- * `POST /v1/webhooks/{id}/rotate-secret` — mint a new `whsec_*` secret.
30
- * Old secret stays valid for 5 minutes (`old_secret_expires_at`) so the
31
- * caller can roll their verification code without dropping events.
32
- * Plaintext secret is returned ONCE.
35
+ * `POST /v1/webhooks/{id}/rotate-secret`: replace the signing secret.
36
+ * Resolves with `{ id, secret, old_secret_expires_at }`: store the new
37
+ * `secret`, which no later call returns.
38
+ *
39
+ * The rotation takes effect immediately. Every request iSnap sends after it,
40
+ * retries and replays included, is signed with the new secret only.
41
+ * `old_secret_expires_at` has no effect on what iSnap sends.
42
+ *
43
+ * The API does not deduplicate this call: when it runs twice, the secret is
44
+ * replaced twice and the last result holds the secret in force.
33
45
  */
34
46
  rotateSecret(id, opts) {
35
47
  return this.client.request('POST', `/v1/webhooks/${encodeURIComponent(id)}/rotate-secret`, undefined, opts);
36
48
  }
37
49
  /**
38
- * `GET /v1/webhooks/{id}/deliveries` — cursor-paginated AsyncIterable
39
- * over delivery attempts for a subscription. Filters: status (pending/
40
- * success/failed), event type, since/until timestamps.
50
+ * `GET /v1/webhooks/{id}/deliveries`: the delivery records of a
51
+ * subscription, as an `AsyncIterable`. Filter with `status` (`pending`,
52
+ * `success` or `failed`), `event`, `since` and `until`.
41
53
  */
42
54
  deliveries(id, filters = {}, opts) {
43
55
  return paginate((cursor) => this.client.request('GET', `/v1/webhooks/${encodeURIComponent(id)}/deliveries`, undefined, { ...opts, query: { ...filters, cursor } }), { signal: opts?.signal });
44
56
  }
45
57
  /**
46
- * `POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay` — re-fire a
47
- * past delivery. Server preserves the original `event_id` so consumers
48
- * still dedupe.
58
+ * `POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay`: replay one
59
+ * delivery. It takes a subscription id and a delivery id, not an event id.
60
+ * The replay is a new delivery with the same `event_id`, so a receiver that
61
+ * deduplicates on `event_id` recognizes it. Only a delivery whose `status`
62
+ * is `success` or `failed` can be replayed.
63
+ *
64
+ * The API does not deduplicate this call: a retry after a lost response
65
+ * creates a second replay.
49
66
  */
50
67
  replay(webhookId, deliveryId, opts) {
51
68
  return this.client.request('POST', `/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries/${encodeURIComponent(deliveryId)}/replay`, undefined, opts);
52
69
  }
53
70
  /**
54
- * `GET /v1/webhooks/events` — cursor-paginated reconciliation pull.
55
- * Returns events that would have been delivered to the caller's
56
- * subscriptions within the 72h retention window. Used to recover from
57
- * webhook outages without missing signal.
71
+ * `GET /v1/webhooks/events`: the events recorded for your account in a time
72
+ * window, newest first, as an `AsyncIterable`. The feed covers the last 72
73
+ * hours. An event is in the feed only if, when it occurred, it matched at
74
+ * least one of your subscriptions that was active and not suspended.
58
75
  *
59
- * `since` is required by the contract.
76
+ * `since` is required.
60
77
  */
61
78
  events(filters, opts) {
62
79
  return paginate((cursor) => this.client.request('GET', '/v1/webhooks/events', undefined, { ...opts, query: { ...filters, cursor } }), { signal: opts?.signal });
@@ -1 +1 @@
1
- {"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAoBxC,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,mFAAmF;IACnF,IAAI,CAAC,IAAqB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;IACjF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAuB,EAAE,IAAqB;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAU,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACzE,CAAC;IAED,qEAAqE;IACrE,GAAG,CAAC,EAAU,EAAE,IAAqB;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,KAAK,EACL,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,IAAqB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,OAAO,EACP,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,IAAI,EACJ,IAAI,CACL,CAAA;IACH,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,EAAU,EAAE,IAAqB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,QAAQ,EACR,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,EAAU,EAAE,IAAqB;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,gBAAgB,EACtD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,UAAU,CACR,EAAU,EACV,UAA+C,EAAE,EACjD,IAAqB;QAErB,OAAO,QAAQ,CACb,CAAC,MAAM,EAAE,EAAE,CACT,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,KAAK,EACL,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,aAAa,EACnD,SAAS,EACT,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAC3C,EACH,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CACzB,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CACJ,SAAiB,EACjB,UAAkB,EAClB,IAAqB;QAErB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,eAAe,kBAAkB,CAAC,UAAU,CAAC,SAAS,EACnG,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CACJ,OAAqD,EACrD,IAAqB;QAErB,OAAO,QAAQ,CACb,CAAC,MAAM,EAAE,EAAE,CACT,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,KAAK,EACL,qBAAqB,EACrB,SAAS,EACT,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAC3C,EACH,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CACzB,CAAA;IACH,CAAC;CACF"}
1
+ {"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAoBxC,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,uFAAuF;IACvF,IAAI,CAAC,IAAqB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;IACjF,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAuB,EAAE,IAAqB;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAU,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACzE,CAAC;IAED,yDAAyD;IACzD,GAAG,CAAC,EAAU,EAAE,IAAqB;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,KAAK,EACL,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED,uGAAuG;IACvG,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,IAAqB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,OAAO,EACP,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,IAAI,EACJ,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,EAAU,EAAE,IAAqB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,QAAQ,EACR,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAU,EAAE,IAAqB;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,gBAAgB,EACtD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,UAAU,CACR,EAAU,EACV,UAA+C,EAAE,EACjD,IAAqB;QAErB,OAAO,QAAQ,CACb,CAAC,MAAM,EAAE,EAAE,CACT,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,KAAK,EACL,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,aAAa,EACnD,SAAS,EACT,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAC3C,EACH,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CACzB,CAAA;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CACJ,SAAiB,EACjB,UAAkB,EAClB,IAAqB;QAErB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,eAAe,kBAAkB,CAAC,UAAU,CAAC,SAAS,EACnG,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CACJ,OAAqD,EACrD,IAAqB;QAErB,OAAO,QAAQ,CACb,CAAC,MAAM,EAAE,EAAE,CACT,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,KAAK,EACL,qBAAqB,EACrB,SAAS,EACT,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAC3C,EACH,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CACzB,CAAA;IACH,CAAC;CACF"}
package/dist/retry.d.ts CHANGED
@@ -10,16 +10,15 @@ export interface RetryConfig {
10
10
  signal?: AbortSignal;
11
11
  }
12
12
  /**
13
- * Ceiling on how long a single retry may sleep, in milliseconds.
13
+ * Default of `maxRetryDelayMs`: the longest wait the SDK accepts before one
14
+ * retry, in milliseconds.
14
15
  *
15
- * A server-sent `retry_after` is honored verbatim, and the backend emits
16
- * day-scale values on purpose — the trial rebind cap returns
17
- * `retry_after ≈ 86400` (24h) as a *retryable* 429. Without a ceiling one
18
- * `await client.trial.revoke(...)` would sit in an uninterruptible sleep for
19
- * a day (three of them, at the default `maxRetries: 3`), which an integrator
20
- * experiences as a hang rather than as a rate limit. 60s covers every
21
- * limiter window the API actually uses; anything beyond it is something the
22
- * caller should schedule itself, not something the SDK should sleep through.
16
+ * On a `429` the SDK waits the `retry_after` the API states. Some refusals
17
+ * state a long one: `hourly_limit_exceeded` states 3,600 seconds, and
18
+ * `rebind_cap_reached` on `trial.revoke` states the time until a rebind is
19
+ * allowed again. The SDK does not wait through a delay above this value: it
20
+ * throws the `RateLimitError` immediately, with `retryAfter` set, so the
21
+ * caller schedules the wait itself.
23
22
  */
24
23
  export declare const DEFAULT_MAX_RETRY_DELAY_MS = 60000;
25
24
  export declare function isRetryable(err: unknown): boolean;
@@ -28,7 +27,7 @@ export declare function isRetryable(err: unknown): boolean;
28
27
  *
29
28
  * A honored `retry_after` is returned **raw and unclamped** on purpose: the
30
29
  * caller needs the true figure for the `onRetry` diagnostic and for the
31
- * error path. Enforcing the ceiling is `withRetries`' job — it rethrows
30
+ * error path. Enforcing the ceiling is the job of `withRetries`: it rethrows
32
31
  * rather than sleeping when the raw value overshoots, so the two branches
33
32
  * stay distinguishable (`> maxDelayMs` means "don't wait", not "wait
34
33
  * `maxDelayMs`"). Only the exponential fallback is clamped here, since it
@@ -1 +1 @@
1
- {"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACnC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAKD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAEhD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,OAAO,EACZ,UAAU,GAAE,MAAmC,GAC9C,MAAM,CAKR;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CA+B1F"}
1
+ {"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACnC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAKD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAEhD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,OAAO,EACZ,UAAU,GAAE,MAAmC,GAC9C,MAAM,CAKR;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CA+B1F"}
package/dist/retry.js CHANGED
@@ -3,16 +3,15 @@ import { sleep } from './internal/sleep.js';
3
3
  const BASE_DELAY_MS = 250;
4
4
  const JITTER_MS = 100;
5
5
  /**
6
- * Ceiling on how long a single retry may sleep, in milliseconds.
6
+ * Default of `maxRetryDelayMs`: the longest wait the SDK accepts before one
7
+ * retry, in milliseconds.
7
8
  *
8
- * A server-sent `retry_after` is honored verbatim, and the backend emits
9
- * day-scale values on purpose — the trial rebind cap returns
10
- * `retry_after ≈ 86400` (24h) as a *retryable* 429. Without a ceiling one
11
- * `await client.trial.revoke(...)` would sit in an uninterruptible sleep for
12
- * a day (three of them, at the default `maxRetries: 3`), which an integrator
13
- * experiences as a hang rather than as a rate limit. 60s covers every
14
- * limiter window the API actually uses; anything beyond it is something the
15
- * caller should schedule itself, not something the SDK should sleep through.
9
+ * On a `429` the SDK waits the `retry_after` the API states. Some refusals
10
+ * state a long one: `hourly_limit_exceeded` states 3,600 seconds, and
11
+ * `rebind_cap_reached` on `trial.revoke` states the time until a rebind is
12
+ * allowed again. The SDK does not wait through a delay above this value: it
13
+ * throws the `RateLimitError` immediately, with `retryAfter` set, so the
14
+ * caller schedules the wait itself.
16
15
  */
17
16
  export const DEFAULT_MAX_RETRY_DELAY_MS = 60_000;
18
17
  export function isRetryable(err) {
@@ -33,7 +32,7 @@ export function isRetryable(err) {
33
32
  *
34
33
  * A honored `retry_after` is returned **raw and unclamped** on purpose: the
35
34
  * caller needs the true figure for the `onRetry` diagnostic and for the
36
- * error path. Enforcing the ceiling is `withRetries`' job — it rethrows
35
+ * error path. Enforcing the ceiling is the job of `withRetries`: it rethrows
37
36
  * rather than sleeping when the raw value overshoots, so the two branches
38
37
  * stay distinguishable (`> maxDelayMs` means "don't wait", not "wait
39
38
  * `maxDelayMs`"). Only the exponential fallback is clamped here, since it
@@ -68,9 +67,9 @@ export async function withRetries(fn, config) {
68
67
  // fail-closed (`!(x <= cap)` rather than `x > cap`) so a `retry_after`
69
68
  // that lands on `NaN` or overflows to `Infinity` through the seconds →
70
69
  // ms conversion rethrows too, instead of slipping past a `>` test.
71
- // Rethrowing the ORIGINAL error keeps `instanceof`, `status`, `code`,
70
+ // Rethrowing the original error keeps `instanceof`, `status`, `code`,
72
71
  // `retryAfter`, `traceId` and `requestId` intact so the caller can
73
- // schedule the long wait itself. Ordered before `onRetry` — the hook
72
+ // schedule the long wait itself. Ordered before `onRetry`: the hook
74
73
  // must not announce a retry that never happens.
75
74
  if (!(nextDelayMs <= maxDelayMs))
76
75
  throw err;
package/dist/retry.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAe3C,MAAM,aAAa,GAAG,GAAG,CAAA;AACzB,MAAM,SAAS,GAAG,GAAG,CAAA;AAErB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAA;AAEhD,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,kBAAkB;QAAE,OAAO,KAAK,CAAA;IACnD,IAAI,GAAG,YAAY,kBAAkB;QAAE,OAAO,IAAI,CAAA;IAClD,IAAI,GAAG,YAAY,mBAAmB;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,GAAG,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAA;IACvD,IAAI,GAAG,YAAY,cAAc;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,GAAY,EACZ,aAAqB,0BAA0B;IAE/C,IAAI,GAAG,YAAY,cAAc,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAC9F,OAAO,GAAG,CAAC,UAAU,GAAG,IAAI,CAAA;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,SAAS,EAAE,UAAU,CAAC,CAAA;AAC/F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,EAAoB,EAAE,MAAmB;IAC5E,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,IAAI,0BAA0B,CAAA;IACvE,IAAI,SAAkB,CAAA;IACtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC9D,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,kBAAkB,CAAC,gCAAgC,EAAE;gBAC7D,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;aAC5B,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAA;YACf,MAAM,MAAM,GAAG,OAAO,KAAK,MAAM,CAAC,UAAU,CAAA;YAC5C,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAA;YAC1C,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,CAAA;YAC5D,mEAAmE;YACnE,mEAAmE;YACnE,uEAAuE;YACvE,uEAAuE;YACvE,mEAAmE;YACnE,sEAAsE;YACtE,mEAAmE;YACnE,qEAAqE;YACrE,gDAAgD;YAChD,IAAI,CAAC,CAAC,WAAW,IAAI,UAAU,CAAC;gBAAE,MAAM,GAAG,CAAA;YAC3C,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;YACtD,MAAM,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,sCAAsC,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAA;AACjB,CAAC"}
1
+ {"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAe3C,MAAM,aAAa,GAAG,GAAG,CAAA;AACzB,MAAM,SAAS,GAAG,GAAG,CAAA;AAErB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAA;AAEhD,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,kBAAkB;QAAE,OAAO,KAAK,CAAA;IACnD,IAAI,GAAG,YAAY,kBAAkB;QAAE,OAAO,IAAI,CAAA;IAClD,IAAI,GAAG,YAAY,mBAAmB;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,GAAG,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAA;IACvD,IAAI,GAAG,YAAY,cAAc;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,GAAY,EACZ,aAAqB,0BAA0B;IAE/C,IAAI,GAAG,YAAY,cAAc,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAC9F,OAAO,GAAG,CAAC,UAAU,GAAG,IAAI,CAAA;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,SAAS,EAAE,UAAU,CAAC,CAAA;AAC/F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,EAAoB,EAAE,MAAmB;IAC5E,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,IAAI,0BAA0B,CAAA;IACvE,IAAI,SAAkB,CAAA;IACtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC9D,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,kBAAkB,CAAC,gCAAgC,EAAE;gBAC7D,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;aAC5B,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAA;YACf,MAAM,MAAM,GAAG,OAAO,KAAK,MAAM,CAAC,UAAU,CAAA;YAC5C,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAA;YAC1C,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,CAAA;YAC5D,mEAAmE;YACnE,mEAAmE;YACnE,uEAAuE;YACvE,uEAAuE;YACvE,mEAAmE;YACnE,sEAAsE;YACtE,mEAAmE;YACnE,oEAAoE;YACpE,gDAAgD;YAChD,IAAI,CAAC,CAAC,WAAW,IAAI,UAAU,CAAC;gBAAE,MAAM,GAAG,CAAA;YAC3C,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;YACtD,MAAM,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,sCAAsC,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAA;AACjB,CAAC"}
package/dist/types.d.ts CHANGED
@@ -1,4 +1,14 @@
1
1
  export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
2
+ /**
3
+ * One entry of `APIError.issues`, set on a `400 validation_failed` and on the
4
+ * other refusals that name a field, such as `400 webhook_url_not_allowed` and
5
+ * `422 limit_out_of_bounds`.
6
+ *
7
+ * At run time `path` is an array of strings and numbers that locates the
8
+ * field, although this type declares a string. Read it as `unknown` and check
9
+ * it before use. The entry of a `422 limit_out_of_bounds` also carries `min`
10
+ * and `max`, which this type does not declare.
11
+ */
2
12
  export interface ErrorIssue {
3
13
  path: string;
4
14
  message: string;
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;AAEpE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;IACpE;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;AAEpE;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;IACpE;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB"}
package/dist/version.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- export declare const SDK_VERSION = "2.3.0";
1
+ export declare const SDK_VERSION = "2.3.1";
2
2
  export declare const MIN_API_VERSION = "2.47.0";
3
3
  //# sourceMappingURL=version.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,WAAW,UAAU,CAAA;AAgClC,eAAO,MAAM,eAAe,WAAW,CAAA"}
1
+ {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,UAAU,CAAA;AASlC,eAAO,MAAM,eAAe,WAAW,CAAA"}
package/dist/version.js CHANGED
@@ -1,39 +1,15 @@
1
- // SDK version. Bumped INDEPENDENTLY of the API contract version per
2
- // industry standard (Stripe, Twilio, OpenAI, AWS): SDK semver tracks SDK
3
- // changes (new methods, retry logic, type fixes), API semver tracks the
4
- // contract surface. Hand-maintained: no build or publish step derives this
5
- // from `package.json`, so it MUST be bumped in the same commit as the
6
- // `version` field there. `src/version.test.ts` fails CI when they disagree.
7
- export const SDK_VERSION = '2.3.0';
8
- // Minimum API version the SDK considers compatible. Reference-only
9
- // today: the client exposes `client.version()` to read `/v1/version` on
10
- // demand, but does NOT call it automatically at first request as a
11
- // compatibility precheck, and there is no `IncompatibleApiVersionError`
12
- // thrown on a lower backend. The automatic precheck (and the corresponding
13
- // error type) is a follow-up — until it ships, this constant is
14
- // documentation that downstream tooling can read but the client itself
15
- // does not enforce.
16
- //
17
- // Bump this when the SDK starts using a feature that requires a specific
18
- // backend version (e.g. a new endpoint added in API minor X.Y.0 — the
19
- // SDK that wraps it sets MIN_API_VERSION to X.Y.0). Within a major
20
- // version, the API stays additive (oasdiff `--deprecation-days-stable 30`
21
- // enforced in CI), so an SDK keeps working against any backend of the same
22
- // major without raising the floor.
23
- //
24
- // WHA-2644 — raised from `1.0.0` to `2.0.0`. The premise the old value rested
25
- // on ("within 1.x the API stays additive") is precisely what the pre-order
26
- // strip broke: `PreOrder` lost `amount`, `billing_tier` and
27
- // `stripe_payment_intent_id`, so the generated types in this package no longer
28
- // describe ANY 1.x backend. Leaving the floor at `1.0.0` would have been the
29
- // same class of defect the change removes — a field that says something the
30
- // code does not do.
31
- //
32
- // WHA-3684 — raised to `2.24.0`, the API minor that added
33
- // `PATCH /v1/pre-orders/{id}`, which `preOrders.update` wraps: the rule above,
34
- // applied. Against an older backend that method answers 404, not a version error.
35
- //
36
- // WHA-3999 — raised to `2.47.0`, the API minor that added
37
- // `POST /v1/lines/{id}/invites`, which `lines.createInvite` wraps.
1
+ // The version of this package. It follows Semantic Versioning for the SDK's
2
+ // own surface and moves independently of the API version. Hand-maintained:
3
+ // no build or publish step derives it from `package.json`, so it must be
4
+ // bumped in the same commit as the `version` field there.
5
+ // `src/version.test.ts` fails when the two disagree.
6
+ export const SDK_VERSION = '2.3.1';
7
+ // The API version that added the most recent operation this SDK wraps:
8
+ // `POST /v1/lines/{id}/invites`, wrapped by `lines.createInvite`. Informational:
9
+ // the client does not check it and sends no API version. `client.version()`
10
+ // returns the version of the API the client talks to.
11
+ //
12
+ // Raise it when the SDK starts to wrap an operation, or to rely on a field,
13
+ // that a later API version adds.
38
14
  export const MIN_API_VERSION = '2.47.0';
39
15
  //# sourceMappingURL=version.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,yEAAyE;AACzE,wEAAwE;AACxE,2EAA2E;AAC3E,sEAAsE;AACtE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA;AAElC,mEAAmE;AACnE,wEAAwE;AACxE,mEAAmE;AACnE,wEAAwE;AACxE,2EAA2E;AAC3E,gEAAgE;AAChE,uEAAuE;AACvE,oBAAoB;AACpB,EAAE;AACF,yEAAyE;AACzE,sEAAsE;AACtE,mEAAmE;AACnE,0EAA0E;AAC1E,2EAA2E;AAC3E,mCAAmC;AACnC,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4DAA4D;AAC5D,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,oBAAoB;AACpB,EAAE;AACF,0DAA0D;AAC1D,+EAA+E;AAC/E,kFAAkF;AAClF,EAAE;AACF,0DAA0D;AAC1D,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAA"}
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,0DAA0D;AAC1D,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA;AAElC,uEAAuE;AACvE,iFAAiF;AACjF,4EAA4E;AAC5E,sDAAsD;AACtD,EAAE;AACF,4EAA4E;AAC5E,iCAAiC;AACjC,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAA"}
@@ -1,15 +1,16 @@
1
1
  import type { WebhookEventBase } from './types.js';
2
2
  /**
3
- * Parse a raw webhook delivery body into a typed envelope. Throws
4
- * `WebhookSignatureError` if the body is not valid JSON or doesn't carry
5
- * the §4.1 envelope shape (`event_id`, `event_type`, `data`). Use
6
- * `verifyWebhook` for the full HMAC + replay-window verification — this
7
- * is the parsing-only half for cases where verification happened
8
- * out-of-band (e.g. behind a trusted gateway).
3
+ * Parse a delivery body into an event, without verifying a signature. Throws
4
+ * `WebhookSignatureError` when the body is not valid JSON, is not a JSON
5
+ * object, or lacks a non-empty string `api_version`, `event_id`, `event_type`
6
+ * or `created_at`, or an object `data`. An event type the SDK does not know is
7
+ * accepted and returned.
9
8
  *
10
- * **Consumers MUST dedupe by `event.event_id`** — webhook delivery is
11
- * at-least-once, so retries replay the same envelope. Without dedup,
12
- * processing the same event twice produces duplicate side-effects.
9
+ * `verifyWebhook` checks the signature and the timestamp, then applies these
10
+ * same checks. Call this function only on a body that was verified by other
11
+ * means.
12
+ *
13
+ * Deduplicate on `event_id`: a retry or a replay carries the same `event_id`.
13
14
  */
14
15
  export declare function parseWebhookEvent(rawBody: string): WebhookEventBase;
15
16
  //# sourceMappingURL=parse.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/webhooks/parse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAiCnE"}
1
+ {"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/webhooks/parse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAiCnE"}
@@ -1,15 +1,16 @@
1
1
  import { WebhookSignatureError } from '../errors.js';
2
2
  /**
3
- * Parse a raw webhook delivery body into a typed envelope. Throws
4
- * `WebhookSignatureError` if the body is not valid JSON or doesn't carry
5
- * the §4.1 envelope shape (`event_id`, `event_type`, `data`). Use
6
- * `verifyWebhook` for the full HMAC + replay-window verification — this
7
- * is the parsing-only half for cases where verification happened
8
- * out-of-band (e.g. behind a trusted gateway).
3
+ * Parse a delivery body into an event, without verifying a signature. Throws
4
+ * `WebhookSignatureError` when the body is not valid JSON, is not a JSON
5
+ * object, or lacks a non-empty string `api_version`, `event_id`, `event_type`
6
+ * or `created_at`, or an object `data`. An event type the SDK does not know is
7
+ * accepted and returned.
9
8
  *
10
- * **Consumers MUST dedupe by `event.event_id`** — webhook delivery is
11
- * at-least-once, so retries replay the same envelope. Without dedup,
12
- * processing the same event twice produces duplicate side-effects.
9
+ * `verifyWebhook` checks the signature and the timestamp, then applies these
10
+ * same checks. Call this function only on a body that was verified by other
11
+ * means.
12
+ *
13
+ * Deduplicate on `event_id`: a retry or a replay carries the same `event_id`.
13
14
  */
14
15
  export function parseWebhookEvent(rawBody) {
15
16
  let parsed;
@@ -35,10 +36,10 @@ export function parseWebhookEvent(rawBody) {
35
36
  if (typeof obj.created_at !== 'string' || obj.created_at.length === 0) {
36
37
  throw new WebhookSignatureError('Webhook envelope missing created_at');
37
38
  }
38
- // `data` must be a plain object — arrays satisfy `typeof === 'object'`
39
- // but the contract §4.1 envelope is `{ ...fields, data: { message: ... } }`,
40
- // never an array. Rejecting at the boundary keeps the
41
- // `Record<string, unknown>` declared type aligned with runtime.
39
+ // `data` must be a plain object: an array also satisfies
40
+ // `typeof === 'object'`, and the `data` of an event is never an array.
41
+ // Refusing it here keeps the declared `Record<string, unknown>` type true
42
+ // at run time.
42
43
  if (typeof obj.data !== 'object' || obj.data === null || Array.isArray(obj.data)) {
43
44
  throw new WebhookSignatureError('Webhook envelope missing data');
44
45
  }
@@ -1 +1 @@
1
- {"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/webhooks/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAC7B,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtF,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAA;IACvE,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAA;IAC7C,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,qBAAqB,CAAC,sCAAsC,CAAC,CAAA;IACzE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAqB,CAAC,mCAAmC,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,uEAAuE;IACvE,6EAA6E;IAC7E,sDAAsD;IACtD,gEAAgE;IAChE,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,qBAAqB,CAAC,+BAA+B,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,GAAkC,CAAA;AAC3C,CAAC"}
1
+ {"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/webhooks/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAGpD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAC7B,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtF,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAA;IACvE,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAA;IAC7C,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,qBAAqB,CAAC,sCAAsC,CAAC,CAAA;IACzE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAqB,CAAC,mCAAmC,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,yDAAyD;IACzD,uEAAuE;IACvE,0EAA0E;IAC1E,eAAe;IACf,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,qBAAqB,CAAC,+BAA+B,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,GAAkC,CAAA;AAC3C,CAAC"}