@isnap/sdk 2.3.0 → 2.3.1-next.43435188216.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,10 +1,10 @@
1
1
  import { BaseResource } from './base.js';
2
2
  export class LinesResource extends BaseResource {
3
3
  /**
4
- * `GET /v1/lines` — page/limit-paginated list of lines visible to the
5
- * caller. Returns the wire-format envelope contents (`{lines, total,
6
- * page, limit}`); not cursor-paginated like messages because the
7
- * marketplace UI shows real "page X of Y" pagination.
4
+ * `GET /v1/lines`: the lines available to take, one page at a time. Resolves
5
+ * with `{ lines, total, page, limit }`: select a page with `page` (from 1)
6
+ * and `limit` (1 to 100, default 20). This method is not an iterator. Phone
7
+ * numbers are masked. The operation needs no credential.
8
8
  */
9
9
  list(query = {}, opts) {
10
10
  return this.client.request('GET', '/v1/lines', undefined, {
@@ -12,362 +12,321 @@ export class LinesResource extends BaseResource {
12
12
  query: { ...opts?.query, ...query }
13
13
  });
14
14
  }
15
- /** `GET /v1/lines/my` — list of lines owned by the calling account. */
15
+ /**
16
+ * `GET /v1/lines/my`: your lines whose `status` is `active` or `reserved`,
17
+ * in one response.
18
+ */
16
19
  listMine(opts) {
17
20
  return this.client.request('GET', '/v1/lines/my', undefined, opts);
18
21
  }
19
- /** `GET /v1/lines/{id}` — fetch a single line by ID or `line_<base62>` public ID. */
22
+ /**
23
+ * `GET /v1/lines/{id}`: one rented or BYOD line. `phone_number` is masked
24
+ * unless the client's key belongs to the line's owner. A shared line or a
25
+ * test line returns `404`, for its owner too: read it with `listMine()`.
26
+ */
20
27
  get(id, opts) {
21
28
  return this.client.request('GET', `/v1/lines/${encodeURIComponent(id)}`, undefined, opts);
22
29
  }
23
30
  /**
24
- * `POST /v1/lines/assign` — atomically find an available line matching
25
- * the requested billing tier (and optional area code), reserve it, and
26
- * activate it on the calling account in a single round-trip.
27
- *
28
- * **Wholesale partners only**, `as_test_line` included: the line carries no
29
- * per-line subscription and is billed on the end-of-month count. A direct
30
- * (non-wholesale) account is rejected with `PaymentRequiredError` (402
31
- * `checkout_required`) and nothing is reserved; it buys a line through
32
- * `POST /v1/billing/checkout` and runs trials with `client.trial.init()`.
33
- * A line-scoped API key is rejected first, with `PermissionDeniedError` (403).
31
+ * `POST /v1/lines/assign`: take one available line that matches
32
+ * `billing_tier` (and `area_code` when given) and make it yours, `active`,
33
+ * in one call. With no matching line the call is a `ConflictError` (409
34
+ * `no_matching_line`).
35
+ *
36
+ * Wholesale partners only, `as_test_line` included: the call takes no
37
+ * payment. Any other account is a `PaymentRequiredError` (402
38
+ * `checkout_required`) and nothing is taken: it reserves a line and pays for
39
+ * it in the iSnap dashboard, and it runs trials with `client.trial.init()`.
40
+ * A line-scoped API key is a `PermissionDeniedError` (403).
41
+ *
42
+ * The API honors the idempotency key on this operation, and remembers a key
43
+ * for 24 hours. A call that does not carry the key of an earlier call takes
44
+ * one more billable line, and so does a call that carries it more than 24
45
+ * hours later. With `as_test_line`, a call that fails after the line was
46
+ * assigned releases the key, and a retry, an automatic one included, assigns
47
+ * a second line: pass `{ maxRetries: 0 }`, or read your lines with
48
+ * `listMine()` before you retry.
34
49
  */
35
50
  assign(body, opts) {
36
51
  return this.client.request('POST', '/v1/lines/assign', body, opts);
37
52
  }
38
53
  /**
39
- * `POST /v1/lines/shared` — mint a fresh **billable** virtual wholesale
40
- * line on the calling account. Wholesale-partner only in v1: a direct
41
- * (non-wholesale) customer is rejected with `PaymentRequiredError` (402),
42
- * and a scoped API key is rejected with `PermissionDeniedError` (403).
43
- *
44
- * Every call mints a NEW billable line. The auto `Idempotency-Key`
45
- * (`config.idempotencyKey: 'auto'`) only dedupes THIS call's internal
46
- * retries — it is generated per call, so two separate `mintShared()` calls
47
- * produce two keys and two billable lines. A caller-level retry MUST reuse
48
- * the same `opts.idempotencyKey`; under `idempotencyKey: 'manual'` no key is
49
- * sent at all and the caller owns it entirely.
50
- *
51
- * `body` defaults to `{}` (not `undefined`) so the request always carries
52
- * `Content-Type: application/json`; the route's body is optional and the
53
- * handler treats a missing body as `{}`.
54
+ * `POST /v1/lines/shared`: create one shared line on your account, `active`
55
+ * and billable. Wholesale partners only: any other account is a
56
+ * `PaymentRequiredError` (402 `payment_required`), and a line-scoped API key
57
+ * is a `PermissionDeniedError` (403).
58
+ *
59
+ * Every call creates a new billable line. The API honors the idempotency key
60
+ * on this operation, and the SDK generates one key per call: two separate
61
+ * `mintShared()` calls create two lines. To retry a call yourself, pass the
62
+ * `opts.idempotencyKey` of the first attempt within 24 hours, the time the
63
+ * API remembers a key on this operation. With `idempotencyKey: 'manual'` the
64
+ * SDK sends a key only when you pass one.
65
+ *
66
+ * `body` defaults to `{}`, so the request always carries a JSON body.
54
67
  */
55
68
  mintShared(body = {}, opts) {
56
69
  return this.client.request('POST', '/v1/lines/shared', body, opts);
57
70
  }
58
- /** `POST /v1/lines/{id}/reserve` — soft-hold a marketplace line for 15 minutes. */
71
+ /**
72
+ * `POST /v1/lines/{id}/reserve`: hold an available line for your account for
73
+ * 15 minutes. Resolves with the line, `status: reserved` and `expires_at`
74
+ * set. A line that cannot be taken is a `ConflictError` (409).
75
+ */
59
76
  reserve(id, opts) {
60
77
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/reserve`, undefined, opts);
61
78
  }
62
79
  /**
63
- * `POST /v1/lines/{id}/activate` — commit a reserved line to `active`.
64
- * **Wholesale partners only**: the second phase of reserve→activate (no
65
- * Stripe checkout, EOM-metered), which may pick the inbound-only rental
66
- * variant via `body.inbound_only`. Direct customers get `402
67
- * checkout_required` — their line activates when the Stripe Checkout session
68
- * from `billing.checkout()` is paid, and their `inbound_only` comes from the
69
- * price they paid.
70
- *
71
- * `body.billing_anchor_at` states the date the customer who pays for this
72
- * line is billed on — every line that customer holds then moves together: one
73
- * full month at each occurrence, with a credit at the first occurrence for
74
- * the days the activation month had already paid for past it. Omit it and the
75
- * line is billed on its activation instant.
80
+ * `POST /v1/lines/{id}/activate`: turn a line you reserved into an `active`
81
+ * line, before its reservation ends. Wholesale partners only: the call takes
82
+ * no payment. Any other account is a `PaymentRequiredError` (402
83
+ * `checkout_required`): it pays for the reserved line in the iSnap
84
+ * dashboard, and the payment activates the line.
85
+ *
86
+ * `body.inbound_only` (rented lines only) selects an inbound-only line.
87
+ * `body.billing_anchor_at` states the line's billing anchor. Without it, the
88
+ * line's billing dates follow its activation date.
76
89
  */
77
90
  activate(id, body = {}, opts) {
78
91
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/activate`, body, opts);
79
92
  }
80
93
  /**
81
- * `POST /v1/lines/{id}/release` — give back a line you reserved; it returns
82
- * to `available`. While the first payment of a subscription of yours for the
83
- * line has been submitted, or has succeeded within the last hour, and the line
84
- * is not `active` yet, the call fails with `409 purchase_payment_in_progress`
85
- * and releases nothing.
94
+ * `POST /v1/lines/{id}/release`: give back a line you hold `reserved`. The
95
+ * line returns to `available` immediately. While the first payment of a
96
+ * subscription of yours for the line has been submitted, or has succeeded
97
+ * within the last hour, and the line is not `active` yet, the call is a
98
+ * `ConflictError` (409 `purchase_payment_in_progress`) and releases nothing.
99
+ * Any other line, an `active` line included, returns `404`. A line-scoped
100
+ * API key that does not cover the line is a `PermissionDeniedError` (403).
86
101
  */
87
102
  release(id, opts) {
88
103
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/release`, undefined, opts);
89
104
  }
90
105
  /**
91
- * `POST /v1/lines/{id}/terminate` — permanently END a line you own. The
92
- * self-serve counterpart to the admin terminate, and the verb to call when
93
- * your own customer cancels: `release()` only returns a *reserved*
94
- * marketplace line to the shelf, while this ends a live `rental` line or a
95
- * virtual `shared` line for good.
96
- *
97
- * The line comes back at the terminal `cancelled` status, keeping its owner.
98
- * Queued messages fail, shared-fleet bindings release, device sessions are
99
- * revoked, and `line.disconnected` fires with `reason: "customer_initiated"`.
100
- * Billing stops in both shapes — a per-line Stripe subscription is cancelled
101
- * immediately, and a wholesale partner's end-of-month active-line count drops
102
- * the line in the same breath.
103
- *
104
- * **Idempotent.** Terminating an already-terminated line resolves with the
105
- * unchanged line (200), never a `ConflictError` — so a retry after a timeout
106
- * is always safe and no `opts.idempotencyKey` is needed for it.
107
- *
108
- * A BYOD line is terminable like any other: its device session is revoked,
109
- * so the bridge or phone stops serving it, and it leaves the billable set.
110
- *
111
- * An owned test line is terminable too, once no live trial rides it
112
- * (`ConflictError`, 409 `test_line_in_use`, until then).
113
- *
114
- * Refusals: `PermissionDeniedError` (403 `pool_line_not_terminable`) — any
115
- * other pool line; `NotFoundError` (404) — a line that does not exist, or one
116
- * you do not own (the same code for both, so nothing leaks).
117
- *
118
- * `body` defaults to `{}` (not `undefined`) so the request always carries
119
- * `Content-Type: application/json`; the route's body is optional and the
120
- * handler treats a missing body as `{}`.
106
+ * `POST /v1/lines/{id}/terminate`: end a line you own, immediately and for
107
+ * good. It applies to an `active` or `suspended` line, whether rented, BYOD,
108
+ * shared or test. `release()` only gives back a reserved line.
109
+ *
110
+ * The line becomes `cancelled` and keeps its owner. Its queued and held
111
+ * messages fail, its device sessions are revoked, and `line.terminated` then
112
+ * `line.disconnected` are sent. The line is no longer billed.
113
+ *
114
+ * Terminating a line that is already `cancelled` resolves with the unchanged
115
+ * line, so a retry is safe.
116
+ *
117
+ * Refusals: `ConflictError` (409 `line_not_customer_terminable`) on a
118
+ * `reserved` or `provisioning` line; `ConflictError` (409 `test_line_in_use`)
119
+ * on a test line that a trial still uses; `PermissionDeniedError` (403
120
+ * `pool_line_not_terminable`) on a `shared_pool` line that is not a test
121
+ * line; `PermissionDeniedError` (403) when a line-scoped API key does not
122
+ * cover the line; `NotFoundError` (404) on a line that does not exist or
123
+ * that you do not own.
124
+ *
125
+ * `body` defaults to `{}`, so the request always carries a JSON body.
121
126
  */
122
127
  terminate(id, body = {}, opts) {
123
128
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/terminate`, body, opts);
124
129
  }
125
130
  /**
126
- * `POST /v1/lines/{id}/cancel` — schedule the END of a line you own for its
127
- * next billing anniversary, and keep using it until then.
128
- *
129
- * This is the verb for "my own customer cancelled". The month is already paid
130
- * for and iSnap never prorates, so `terminate()` — which ends the line on the
131
- * spot — throws away days you have bought. The line stays fully `active` and
132
- * bills exactly as before; iSnap ends it itself when `cancel_at` arrives and
133
- * fires `line.terminated` with `origin: "scheduled_cancellation"`.
134
- *
135
- * The resolved line carries `cancel_at`: the next occurrence of its
136
- * `anniversary_at` strictly after now, clamped to the last day of a shorter
137
- * month (a line taken on the 31st renews on the 28th in February and on the
138
- * 31st again in March — the clamp never sticks).
139
- *
140
- * **Idempotent, and in the way that matters here.** Cancelling an
141
- * already-cancelled line resolves with the SAME `cancel_at`, never a
142
- * recomputed one — so a retry that happens to land after the stored date has
143
- * passed cannot push your own cancellation a month into the future.
144
- *
145
- * Refusals: `ConflictError` (409 `line_has_no_anniversary`) — the line has no
146
- * anniversary to cancel at; state it with `setAnniversary()`, or end the line
147
- * now with `terminate()`. `ConflictError` (409
148
- * `line_not_customer_cancellable`) — only an `active` or `suspended` line can
149
- * be cancelled. `PermissionDeniedError` (403 `pool_line_not_cancellable`) — an
150
- * owned test line's end is not scheduled here: end it with `terminate()`, or
151
- * convert it back with `convertFromTest()` and cancel the rental line. Rental,
152
- * shared and BYOD lines are all cancellable. `NotFoundError` (404) — a line that does not exist,
153
- * or one you do not own (the same code for both, so nothing leaks).
131
+ * `POST /v1/lines/{id}/cancel`: schedule the end of a line you own for its
132
+ * next anniversary. The line keeps working and is billed as before until
133
+ * `cancel_at`. iSnap then ends it and sends `line.terminated` with
134
+ * `origin: "scheduled_cancellation"`. `terminate()` ends a line immediately.
135
+ *
136
+ * `cancel_at` is the next occurrence of `anniversary_at` strictly after the
137
+ * call, in UTC: the same day of the month, moved to the last day of a shorter
138
+ * month. Canceling a line that already has a `cancel_at` resolves with the
139
+ * same `cancel_at`.
140
+ *
141
+ * Wholesale partners only. Refusals: `ConflictError` (409
142
+ * `line_not_wholesale_metered`) when the owner is not a wholesale partner;
143
+ * `ConflictError` (409 `line_has_no_anniversary`) when `anniversary_at` is
144
+ * `null`: state it with `setAnniversary()`, or end the line with
145
+ * `terminate()`; `ConflictError` (409 `line_not_customer_cancellable`) when
146
+ * the line is not `active` or `suspended`; `PermissionDeniedError` (403
147
+ * `pool_line_not_cancellable`) on a test line: end it with `terminate()`;
148
+ * `PermissionDeniedError` (403) when a line-scoped API key does not cover
149
+ * the line; `NotFoundError` (404) on a line that does not exist or that you
150
+ * do not own.
154
151
  */
155
152
  cancel(id, opts) {
156
153
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/cancel`, undefined, opts);
157
154
  }
158
155
  /**
159
- * `POST /v1/lines/{id}/uncancel` — undo a scheduled cancellation. `cancel_at`
160
- * goes back to `null` and the line resumes renewing at its anniversary.
161
- *
162
- * **A no-op on a line that is not cancelled**: resolves 200 with the line and
163
- * `cancel_at: null`, never an error — so a reconciliation loop that asserts
164
- * "this line must not be cancelled" can run unconditionally.
165
- *
166
- * Refusal: `ConflictError` (409 `line_already_terminated`) once the
167
- * anniversary has passed and iSnap has ended the line. That cannot be undone.
156
+ * `POST /v1/lines/{id}/uncancel`: withdraw a scheduled cancellation.
157
+ * `cancel_at` returns to `null`. On a line with no `cancel_at` the call
158
+ * resolves with the line and changes nothing. On a line that has ended it is
159
+ * a `ConflictError` (409 `line_already_terminated`).
168
160
  */
169
161
  uncancel(id, opts) {
170
162
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/uncancel`, undefined, opts);
171
163
  }
172
164
  /**
173
- * `POST /v1/lines/{id}/anniversary` — state the instant you took this line,
174
- * which becomes the day of the month it renews on and the date `cancel()`
175
- * waits for.
176
- *
177
- * **For lines migrated from your own system**, whose real start date iSnap
178
- * cannot know. A line taken through the iSnap API is stamped automatically at
179
- * activation and needs no call.
180
- *
181
- * Refusal: `ConflictError` (409 `line_cancellation_pending`) while a
182
- * cancellation is scheduled — that `cancel_at` was computed from the
183
- * anniversary you are replacing, so uncancel, set the date, and cancel again.
165
+ * `POST /v1/lines/{id}/anniversary`: record `anniversary_at`, the date
166
+ * `cancel()` counts from. It replaces any earlier value.
167
+ *
168
+ * A line that becomes a wholesale partner's through the API gets its
169
+ * anniversary automatically. Use this call for a line that has none.
170
+ *
171
+ * Refusals: `BadRequestError` (400 `anniversary_in_the_future`);
172
+ * `ConflictError` (409 `line_cancellation_pending`) while `cancel_at` is set:
173
+ * call `uncancel()`, set the date, then `cancel()` again; `ConflictError`
174
+ * (409 `line_not_wholesale_metered`) when the owner is not a wholesale
175
+ * partner; `PermissionDeniedError` (403 `pool_line_not_cancellable`) on a
176
+ * test line; `PermissionDeniedError` (403) when a line-scoped API key does
177
+ * not cover the line; `NotFoundError` (404) on a line that does not exist or
178
+ * that you do not own.
184
179
  */
185
180
  setAnniversary(id, body, opts) {
186
181
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/anniversary`, body, opts);
187
182
  }
188
183
  /**
189
- * `POST /v1/lines/{id}/transfer-ownership` — reassign a line to a
190
- * different end-user account without re-pairing the underlying device.
191
- * A line with no subscription of its own (an owned test line, another pool
192
- * line, a virtual shared line) can only go to a wholesale partner: any other
184
+ * `POST /v1/lines/{id}/transfer-ownership`: move a line to another iSnap
185
+ * account (`to_user_id`). The transfer takes effect immediately, and the
186
+ * receiving account is not asked to accept. By default the line's device
187
+ * stays connected.
188
+ *
189
+ * A shared line or a test line can only go to a wholesale partner: any other
193
190
  * recipient is a `ConflictError` (409 `line_recipient_not_wholesale`).
194
191
  */
195
192
  transferOwnership(id, body, opts) {
196
193
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/transfer-ownership`, body, opts);
197
194
  }
198
195
  /**
199
- * `POST /v1/lines/{id}/convert-to-test` — convert a line into a test line.
200
- * Billing does not stop: a test line is billed on your end-of-month invoice
201
- * like a rental line, as the outbound product, on the same billing dates
202
- * (`anniversary_at` and `billing_anchor_at` are kept). End a test line with
203
- * `terminate()`.
204
- * Wholesale partners only: a direct account is rejected with
205
- * `PaymentRequiredError` (402 `checkout_required`). Rejected with
206
- * `ConflictError` (409) for byod lines, a line you do not own, a line with
207
- * an active subscription, an inbound line (`test_line_not_inbound_only`:
208
- * move it to outbound with `setVariant` first) and a line with a pending
209
- * cancellation (`line_cancellation_pending`: `uncancel` first); a line the
210
- * caller cannot see is a masked `NotFoundError` (404).
196
+ * `POST /v1/lines/{id}/convert-to-test`: turn an `active`, two-way rented
197
+ * line into a test line. A test line is billed like the rented line it was,
198
+ * on the same dates: `anniversary_at` and `billing_anchor_at` are kept. End a
199
+ * test line with `terminate()`.
200
+ *
201
+ * Wholesale partners only: any other account is a `PaymentRequiredError`
202
+ * (402 `checkout_required`). Refusals, as `ConflictError` (409):
203
+ * `already_test_line`, `line_not_rental`, `line_not_active`,
204
+ * `line_has_subscription`, `test_line_not_inbound_only` (an inbound-only
205
+ * line: make it two-way with `setVariant` first) and
206
+ * `line_cancellation_pending` (call `uncancel` first).
211
207
  */
212
208
  convertToTest(id, opts) {
213
209
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/convert-to-test`, undefined, opts);
214
210
  }
215
211
  /**
216
- * `POST /v1/lines/{id}/convert-from-test` — convert a test line back to a
217
- * normal line. The bill does not change: the test line was already billed as
218
- * an outbound rental on the same dates. Wholesale partners only: a direct
219
- * account is rejected with
220
- * `PaymentRequiredError` (402 `checkout_required`). Rejected with
221
- * `ConflictError` (409) while the test line still hosts live trials; a line
222
- * the caller cannot see is a masked `NotFoundError` (404).
212
+ * `POST /v1/lines/{id}/convert-from-test`: turn an `active` test line back
213
+ * into a rented line. The bill does not change: the test line was billed
214
+ * like a rented line, on the same dates. Wholesale partners only: any other
215
+ * account is a `PaymentRequiredError` (402 `checkout_required`). Refusals, as
216
+ * `ConflictError` (409): `not_a_test_line`, `line_not_active`, and
217
+ * `test_line_in_use` while a trial that is not revoked uses the line.
223
218
  */
224
219
  convertFromTest(id, opts) {
225
220
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/convert-from-test`, undefined, opts);
226
221
  }
227
222
  /**
228
- * `POST /v1/lines/{id}/variant` — move a rental line you own between the
229
- * INBOUND product (`inbound_only: true`) and the TWO-WAY product, **keeping
230
- * the same phone number**, the same hardware and the same device session.
231
- *
232
- * `inbound_only` is not "receive-only": the line converses normally, it
233
- * simply cannot OPEN a conversation. It may message only a handle that has
234
- * messaged it first, and once that handle has, the exchange is unrestricted
235
- * in both directions for good. A send that breaks the rule is a
236
- * `PermissionDeniedError` (403 `outbound_first_forbidden`).
237
- *
238
- * **Idempotent on the value.** Asking for the variant the line already has
239
- * resolves with the line and writes nothing — no audit row, no
240
- * `line.variant_changed` event — so a retry after a timeout is safe and is
241
- * not a second change. It is not a toggle: state the value you want.
242
- *
243
- * `body.effective` says WHEN, and defaults to `'now'` — the only behaviour
244
- * before the field existed, so an existing call is unchanged.
245
- *
246
- * - `'now'`: as above. Use it for an UPGRADE, which the customer has just
247
- * paid for and which must apply to the very next send.
248
- * - `'next_anchor'`: store the change against the line's next billing
249
- * anchor. Nothing moves today — `inbound_only` keeps its current value and
250
- * the line keeps serving the product it is being billed for — and the
251
- * resolved line carries `pending_variant: { inbound_only, effective_at }`.
252
- * Use it for a DOWNGRADE, so the customer keeps the two-way product
253
- * through the month they have already bought. iSnap applies it at the
254
- * anchor and fires `line.variant_changed` with `data.scheduled: true`;
255
- * cancel it beforehand with {@link LinesResource.cancelVariantChange}.
256
- *
257
- * `body.not_before` (ISO instant, `'next_anchor'` only, defaults to now) is
258
- * the earliest instant the change may take effect. iSnap resolves it to the
259
- * FIRST anchor occurrence at or after it, applying the anchor's own
260
- * day-of-month clamp — so state your customer's paid-period end and let
261
- * iSnap pick the occurrence rather than computing one yourself. A monthly
262
- * customer needs nothing here; a QUARTERLY or ANNUAL customer does, because
263
- * without it the change would land on the next anchor and take back
264
- * capability they have already paid for. The resolved instant comes back as
265
- * `pending_variant.effective_at`. An instant in the past is a
266
- * `BadRequestError` (400 `not_before_in_the_past`) — it is refused rather
267
- * than clamped, because for a long-period customer the silent repair and the
268
- * correct answer differ by months of the product they bought.
269
- *
270
- * Scheduling is idempotent on the PENDING value the same way an immediate
271
- * change is on the live one: re-scheduling the change already pending
272
- * resolves with the line and the date it was already given, and writes
273
- * nothing. A DIFFERENT pending change is a `ConflictError` (409
274
- * `variant_change_already_pending`) — cancel it first, because there is no
275
- * honest way to merge two answers to "what is this line at the anchor".
276
- *
277
- * **A scheduled call can legitimately resolve with `pending_variant: null`,
278
- * and that is not a failure.** Scheduling the variant the line ALREADY
279
- * carries writes nothing, because nothing is pending — the line will still
280
- * be on that variant at the anchor. Do not retry it. Tell it apart from a
281
- * silently-dropped `effective` (see the deploy-order warning below) by
282
- * reading the top-level `inbound_only`: equal to what you asked for means
283
- * already-at-target; different means the field never reached the server and
284
- * the change was applied immediately.
285
- *
286
- * ⚠️ **Adopt `effective` and `not_before` only against a deployment that has
287
- * them.** iSnap STRIPS unknown request properties rather than rejecting
288
- * them, so an early call gets no 400 — it gets the field dropped and an
289
- * ordinary immediate flip, applying a downgrade on the spot. Check
290
- * `client.version()` before sending either field.
291
- *
292
- * An immediate change does NOT cancel a scheduled one: they are separate
293
- * acts, and a partner who needs an urgent upgrade must not have their
294
- * standing downgrade withdrawn by it. Use `cancelVariantChange` for that.
295
- *
296
- * Refusals: `ConflictError` (409) — `not_a_rental_line` (byod / pool /
297
- * shared have no variant), `line_not_active` (the line must be in service),
298
- * `variant_bound_to_stripe_price` (the line carries an iSnap Stripe
299
- * subscription, whose price IS its variant; change the subscription
300
- * instead). A line the caller does not own is a masked `NotFoundError`
301
- * (404), like every other per-line verb.
223
+ * `POST /v1/lines/{id}/variant`: move a rented line between inbound-only
224
+ * (`inbound_only: true`) and two-way, on the same phone number.
225
+ *
226
+ * An inbound-only line can message a contact only after that contact wrote
227
+ * to it. A send that breaks the rule is a `PermissionDeniedError` (403
228
+ * `outbound_first_forbidden`).
229
+ *
230
+ * `body.effective` says when the change applies:
231
+ *
232
+ * - `'now'` (the default): immediately. The next send obeys the new value.
233
+ * Asking for the value the line already has resolves with the line and
234
+ * changes nothing, so a retry is safe.
235
+ * - `'next_anchor'`: at the line's next billing anchor, or at a later one
236
+ * when `body.not_before` says so. `inbound_only` does not move, and the
237
+ * resolved line carries
238
+ * `pending_variant: { inbound_only, effective_at }`. iSnap applies the
239
+ * change after `effective_at` and sends `line.variant_changed` with
240
+ * `data.scheduled: true`. Withdraw it with
241
+ * {@link LinesResource.cancelVariantChange}.
242
+ *
243
+ * `body.not_before` (ISO 8601, with `'next_anchor'` only, default: the time
244
+ * of the call) is the earliest time the change may apply: `effective_at` is
245
+ * the first billing anchor occurrence at or after it. A time in the past is
246
+ * a `BadRequestError` (400 `not_before_in_the_past`).
247
+ *
248
+ * Scheduling the change that is already pending resolves with the line
249
+ * unchanged. A different change while one is pending is a `ConflictError`
250
+ * (409 `variant_change_already_pending`). With no change pending,
251
+ * scheduling the value the line already has stores nothing and resolves with
252
+ * `pending_variant: null`. An immediate change does not clear a pending one.
253
+ *
254
+ * At `effective_at`, a scheduled change is discarded without an event when
255
+ * the line is not `active`, is no longer a rented line, has a subscription
256
+ * of its own, or already has the scheduled value. Read the line to know.
257
+ *
258
+ * Refusals, as `ConflictError` (409): `not_a_rental_line`, `line_not_active`
259
+ * and `variant_bound_to_stripe_price` (the line has a subscription of its
260
+ * own). A line you do not own is a `NotFoundError` (404), and a line-scoped
261
+ * API key that does not cover the line is a `PermissionDeniedError` (403).
302
262
  */
303
263
  setVariant(id, body, opts) {
304
264
  return this.client.request('POST', `/v1/lines/${encodeURIComponent(id)}/variant`, body, opts);
305
265
  }
306
266
  /**
307
- * `DELETE /v1/lines/{id}/variant` — call off the variant change scheduled
308
- * for this line's next billing anchor.
309
- *
310
- * The line's live `inbound_only` is never touched: the scheduling did not
311
- * move it either, so the only effect is that `pending_variant` becomes
312
- * `null` and nothing happens at the anchor.
313
- *
314
- * A line with no pending change is a `NotFoundError` (404
315
- * `no_pending_variant_change`), which includes a change the anchor has
316
- * already applied — there is nothing left to cancel, and the line's own
317
- * `inbound_only` now carries the answer. A change applied while this request
318
- * was in flight is a `ConflictError` (409 `variant_change_already_applied`),
319
- * so the two outcomes are distinguishable from the code alone.
320
- *
321
- * Succeeds on a suspended or cancelled line: withdrawing an instruction must
322
- * never be blocked by the state that made it moot.
267
+ * `DELETE /v1/lines/{id}/variant`: withdraw the line's scheduled variant
268
+ * change. `pending_variant` becomes `null`, and `inbound_only` is not
269
+ * touched. Resolves with `undefined`.
270
+ *
271
+ * With no pending change the call is a `NotFoundError` (404
272
+ * `no_pending_variant_change`), which includes a change that was already
273
+ * applied. A change applied during the call is a `ConflictError` (409
274
+ * `variant_change_already_applied`). The call works on a line in any status.
323
275
  */
324
276
  cancelVariantChange(id, opts) {
325
277
  return this.client.request('DELETE', `/v1/lines/${encodeURIComponent(id)}/variant`, undefined, opts);
326
278
  }
327
279
  /**
328
- * `PATCH /v1/lines/{id}` — update the line's free-form metadata object, its
329
- * billing anchor, or both.
280
+ * `PATCH /v1/lines/{id}`: update the line's `metadata`, its billing anchor,
281
+ * or both.
330
282
  *
331
- * `metadata` is a MERGE: null-valued keys delete those keys from the stored
332
- * object. `billing_anchor_at` is the date the customer who pays for this line
333
- * is billed on — a change takes effect at the NEXT occurrence and never
334
- * rewrites a period already billed, and `null` clears it so the line falls
335
- * back to its activation instant. Send at least one of the two; a body that
336
- * states neither is refused with `no_fields_to_patch`.
283
+ * `metadata` is merged: a key with a value is set, a key with `null` is
284
+ * removed, keys not sent are kept. `billing_anchor_at` states the line's
285
+ * billing anchor, and `null` clears it. Send at least one of the two: a body
286
+ * with neither is a `BadRequestError` (400 `no_fields_to_patch`).
287
+ *
288
+ * Line `metadata` is returned to anyone who reads the line: do not put
289
+ * personal data or secrets in it.
337
290
  */
338
291
  patch(id, body, opts) {
339
292
  return this.client.request('PATCH', `/v1/lines/${encodeURIComponent(id)}`, body, opts);
340
293
  }
341
- /** `GET /v1/lines/{id}/quota` — the line's current 5-bucket quota snapshot. */
294
+ /** `GET /v1/lines/{id}/quota`: the line's sending limits, with how much of each is used. */
342
295
  quota(id, opts) {
343
296
  return this.client.request('GET', `/v1/lines/${encodeURIComponent(id)}/quota`, undefined, opts);
344
297
  }
345
- /** `GET /v1/lines/{id}/queue` — pending scheduled / queued messages for the line. */
298
+ /**
299
+ * `GET /v1/lines/{id}/queue`: the line's outbound messages that wait to
300
+ * leave or were handed to the line's device. Each item's `status` is
301
+ * `queued`, `scheduled` or `delivered_to_device`, ordered by `scheduled_for`,
302
+ * earliest first.
303
+ */
346
304
  queue(id, query = {}, opts) {
347
305
  return this.client.request('GET', `/v1/lines/${encodeURIComponent(id)}/queue`, undefined, { ...opts, query: { ...opts?.query, ...query } });
348
306
  }
349
307
  /**
350
- * `GET /v1/lines/{id}/health` — BYOD-only line health snapshot. Throws
351
- * `PermissionDeniedError` (`rental_health_not_exposed`) for rental
352
- * tiers per contract §2.13.
308
+ * `GET /v1/lines/{id}/health`: the health of one BYOD line. For a rented,
309
+ * shared or test line the call is a `PermissionDeniedError` (403
310
+ * `rental_health_not_exposed`).
353
311
  *
354
- * This is the PER-LINE health probe. For the global backend/system health
355
- * use `client.health()` (`GET /v1/health`) — a different endpoint on the
356
- * client itself, not on a line.
312
+ * For the health of the API as a whole, call `client.health()`
313
+ * (`GET /v1/health`).
357
314
  */
358
315
  health(id, opts) {
359
316
  return this.client.request('GET', `/v1/lines/${encodeURIComponent(id)}/health`, undefined, opts);
360
317
  }
361
318
  /**
362
- * `POST /v1/lines/{id}/invites` — pick a phone number for one visitor of an
319
+ * `POST /v1/lines/{id}/invites`: pick a phone number for one visitor of an
363
320
  * inbound-first line and issue the code the visitor's text must carry. Show
364
321
  * the number only with its code: a text without it does not reach the line.
322
+ * The code has 7 uppercase letters and digits, at least 2 of them digits. It
323
+ * is valid only on that number, never expires and can be used more than once.
365
324
  *
366
325
  * Not idempotent, by design: every call issues a new invite with a new code.
367
- * `body.exclude` lists numbers the pick must avoid. `ServiceUnavailableError`
368
- * (503 `line_pool_exhausted`) when no number can take an invite now;
369
- * `ConflictError` (409 `not_inbound_first_line` or `line_not_active`) on a
370
- * line that cannot take invites.
326
+ * `body.exclude` lists up to 50 numbers, in E.164, that the pick must avoid.
327
+ * `ServiceUnavailableError` (503 `line_pool_exhausted`) when no number can
328
+ * take an invite now; `ConflictError` (409 `not_inbound_first_line` or
329
+ * `line_not_active`) on a line that cannot take invites.
371
330
  *
372
331
  * **Not retried by default** (`maxRetries: 0`, overridable via
373
332
  * `opts.maxRetries`), unlike other writes: the call sits in a page render, a
@@ -384,14 +343,29 @@ export class LinesResource extends BaseResource {
384
343
  // must not bring the client's 3 retries back.
385
344
  { ...opts, maxRetries: opts?.maxRetries ?? 0 });
386
345
  }
387
- /** `GET /v1/lines/{id}/config` — effective per-line config (system defaults + overrides). */
346
+ /**
347
+ * `GET /v1/lines/{id}/config`: the line's configuration: the value in effect
348
+ * for every key, the keys the line overrides, and, in `knobs`, the default
349
+ * and the bounds of the five message limits and the three reply keys.
350
+ */
388
351
  getConfig(id, opts) {
389
352
  return this.client.request('GET', `/v1/lines/${encodeURIComponent(id)}/config`, undefined, opts);
390
353
  }
391
354
  /**
392
- * `PATCH /v1/lines/{id}/config` — partial override of the line's
393
- * config. BYOD callers can only lower limits / raise delays per
394
- * contract §2.13.
355
+ * `PATCH /v1/lines/{id}/config`: override configuration keys of the line. A
356
+ * limit can only be lowered below its default: raising it is a
357
+ * `PermissionDeniedError` (403 `cannot_increase_limit`). A delay can only be
358
+ * raised above its default: lowering it is a `PermissionDeniedError` (403
359
+ * `cannot_decrease_delay`). On a BYOD line, the five message limits can also
360
+ * be raised, up to `knobs.<key>.max`.
361
+ *
362
+ * A value outside `knobs.<key>.min` to `knobs.<key>.max` is refused on any
363
+ * line, before the two rules above apply: as an `UnprocessableEntityError`
364
+ * (422 `limit_out_of_bounds`), or as a `BadRequestError` (400
365
+ * `validation_failed`) when the value is also outside the range the OpenAPI
366
+ * document gives for the key.
367
+ *
368
+ * Sending a key with its default value removes the override.
395
369
  */
396
370
  updateConfig(id, body, opts) {
397
371
  return this.client.request('PATCH', `/v1/lines/${encodeURIComponent(id)}/config`, body, opts);