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