@isnap/sdk 2.2.0 → 2.3.0-next.233

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.
package/CHANGELOG.md CHANGED
@@ -33,11 +33,14 @@ All notable changes to `@isnap/sdk` will be documented in this file. The format
33
33
  - `client.preOrders.create({ …, metadata })`: a pre-order takes your metadata, read back on `PreOrder.metadata` and echoed on every `pre_order.*` webhook. It is not copied onto the line the pre-order produces; `preOrders.update` (below) changes it after creation.
34
34
  - Metadata on every resource that takes it (lines, messages, BYOD pairing, pre-orders, macOS sessions, trials) is now capped at 20 keys and 8192 bytes serialized; a request over the cap is a `BadRequestError` (400), and a PATCH whose merged result breaks it is `400 metadata_too_large`.
35
35
  - `client.preOrders.update(id, { metadata })` (`PATCH /v1/pre-orders/{id}`, WHA-3684, additive, MINOR — `2.2.0`): change a pre-order's tags after creation, for example when it is re-assigned to another of your customers before delivery, or to backfill a pre-order placed before you tagged. `update` merges like `macosSessions.update` and `trial.update`: a key you send overwrites, a key sent as `null` is deleted, every other key is kept. It is accepted in every status, `fulfilled` and `cancelled` included, and resolves with the same `PreOrder` that `get` returns. Every `pre_order.*` webhook emitted afterwards carries the new tags as `data.metadata`, and an event already emitted keeps its original tags on every retry and replay. The tags are still not copied onto the line the pre-order produces. A pre-order placed by another account is a `NotFoundError` (404). The body type is exported as `PatchPreOrderBody`. `MIN_API_VERSION` rises from `2.0.0` to `2.24.0`, the API version that added the endpoint.
36
+ - `client.lines.createInvite(id, { exclude? })` (`POST /v1/lines/{id}/invites`, WHA-3999, additive, MINOR — `2.3.0`): pick a phone number for one visitor of an inbound-first line and issue the 7-character code the visitor's text must carry (at least 2 digits, valid only on that number, never expiring, usable more than once). Resolves with a `LineInvite` (`{ id, line_id, phone_number, code, created_at }`, `phone_number` in E.164); the body type is exported as `CreateLineInviteBody`. `exclude` lists up to 50 E.164 numbers the pick must avoid. Show the number only together with its code. The call is not idempotent by design: every call issues a new invite. It is not retried by default (`maxRetries: 0`, overridable per call with `opts.maxRetries`): it sits in a page render, a `line_pool_exhausted` does not clear within the backoff, and a retry after a lost response would issue a second invite. Refusals: `ServiceUnavailableError` (503 `line_pool_exhausted` when no number can take an invite now, `quota_state_unavailable`, `invite_code_unavailable`), `ConflictError` (409 `not_inbound_first_line`, `line_not_active`), `NotFoundError` (404) for a line of another account, `PermissionDeniedError` (403) for a line-scoped key outside its list. `MIN_API_VERSION` rises from `2.24.0` to `2.47.0`, the API version that added the endpoint.
36
37
 
37
38
  ### Removed
38
39
  - **`verifyWebhook` verifies the Standard Webhooks headers only** (`webhook-id` / `webhook-timestamp` / `webhook-signature`, WHA-3658) — breaking, MAJOR (`2.0.0`). The fallback to the `X-iSnap-Signature` / `X-iSnap-Timestamp` pair is removed, because iSnap no longer sends those headers: a request that carries only them is now rejected with `WebhookSignatureError` (`Missing webhook-id header`). The key derivation no longer strips a `whs_` prefix either; only `whsec_` secrets, the only kind iSnap mints, verify. Unchanged: the `[newSecret, oldSecret]` rotation array, the `tolerance` option and its 300 s default, case-insensitive header reads, and the return value. A caller that already receives iSnap deliveries needs no code change, since every delivery since `1.4.0` carries the standard headers.
39
40
 
40
41
  ### Changed
42
+ - **An owned test line is billed like a rental line** (WHA-3701, API `2.27.0`). `lines.convertToTest()` no longer stops billing: the test line stays on the wholesale partner's end-of-month invoice as the outbound product whatever its platform, on the same billing dates (`anniversary_at` and `billing_anchor_at` are kept), and `Line.monthly_price` reads that price (27500) instead of `0`. `lines.convertFromTest()` therefore leaves the bill unchanged. `lines.convertToTest()` now refuses an inbound line (`ConflictError`, 409 `test_line_not_inbound_only`: move it to outbound with `setVariant` first) and a line with a pending cancellation (409 `line_cancellation_pending`: `uncancel` first). `lines.terminate()` of a test line leaves the instant it ended as the line's `cancel_at`, and a line transferred to a wholesale partner carries the transfer instant as `activated_at`. No SDK code changes: the generated types and the JSDoc of `convertToTest`, `convertFromTest`, `cancel` and `transferOwnership` carry the new wording.
43
+ - **`lines.assign()`, `lines.convertToTest()` and `lines.convertFromTest()` are wholesale-partner only** (WHA-3692, API `2.26.0`). A direct (non-wholesale) account is rejected with `PaymentRequiredError` (402 `checkout_required`) and nothing is reserved or converted. `assign()` refuses a direct account with or without `as_test_line`. `lines.transferOwnership()` of a line that is not billed per line (an owned test line, another pool line, a virtual shared line) to a non-wholesale recipient is a `ConflictError` (409 `line_recipient_not_wholesale`). `lines.terminate()` now ends an owned test line once no live trial rides it, which is otherwise a `ConflictError` (409 `test_line_in_use`). No SDK code changes: the existing error classes surface these refusals.
41
44
  - `src/generated/openapi.d.ts` is now generated from the **published** contract. `packages/backend/openapi.json` carries only the partner-facing `/v1/*` surface, so the internal operator routes (`/admin`, `/va`, `/farm-ops`, `/kam`, `/auth`, …) and the bridge-only `/v1/device/*` contract — plus every schema reachable only from them — are no longer emitted into the SDK types. Those routes are the dashboard, the ops back-office and the device bridge; none of them is part of the partner contract this SDK wraps, and no `ISnapClient` method referenced their types, so no documented method changes shape.
42
45
  - **`AppDownloadEntry.version` is now `string | null`** (API `1.15.0`, WHA-2538) — source-breaking for a consumer that renders `apps.manifest()`'s `version` without narrowing, which is the point. The field used to be a per-deployment configured string tied to no artifact: staging advertised `0.1.0-staging` for both platforms while the Mac ran `0.0.209` and the update channel published `0.0.x`, so the number could not be installed and the two platforms agreed only because both read one env value. It is now read from the release feed beside the artifact the download URL resolves to, and is `null` when that feed publishes nothing. Render the absence; do not substitute a number, and do not treat `null` as an error. It is also no longer the same string `byod.pair` returns as `bridge_version`.
43
46
 
package/README.md CHANGED
@@ -182,16 +182,20 @@ if (health.status !== 'ok') {
182
182
 
183
183
  ## Wholesale + test lines
184
184
 
185
- Wholesale partners mint their own billable shared lines and can park a line in a non-billable test state:
185
+ Wholesale partners mint their own billable shared lines and can set a rental line aside as a test line for their own customers' trials:
186
186
 
187
187
  ```ts
188
188
  const line = await client.lines.mintShared() // POST /v1/lines/shared — a NEW billable line every call
189
- await client.lines.convertToTest(line.id) // stop billing — park as a test line
190
- await client.lines.convertFromTest(line.id) // resume billing
189
+ await client.lines.convertToTest(rentalLineId) // set a rental line aside as a test line
190
+ await client.lines.convertFromTest(rentalLineId) // turn it back into a rental line
191
191
  ```
192
192
 
193
193
  `mintShared()` is wholesale-partner only in v1: a direct (non-wholesale) customer is rejected with `PaymentRequiredError` (402) and a scoped API key with `PermissionDeniedError` (403). Each call mints a distinct line — the SDK's auto `Idempotency-Key` only dedupes that one call's internal retries, so a caller-level retry must reuse the same `opts.idempotencyKey` to avoid minting twice.
194
194
 
195
+ A test line is **billed like a rental line**: it stays on your end-of-month invoice as the outbound product, on the same billing dates, so `convertToTest()` then `convertFromTest()` leaves your bill unchanged. Its `monthly_price` reads that price. `convertToTest()` refuses an inbound line (move it to outbound first) and a line with a pending cancellation (uncancel it first); end a test line with `client.lines.terminate(id)`.
196
+
197
+ `convertToTest()` and `convertFromTest()` are wholesale-partner only too, like `lines.assign()`: a direct account is rejected with `PaymentRequiredError` (402 `checkout_required`), and runs its trials on the global pool with `client.trial.init()`.
198
+
195
199
  ## Errors
196
200
 
197
201
  All API errors extend `APIError` and carry `status`, `code`, `message`, `traceId`, `requestId`. Subclasses match the §6 contract codes: