@hubbyesim/sdk 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to `@hubbyesim/sdk` are recorded in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The SDK version is separate from the Partner API version it speaks (`SUPPORTED_API_VERSION`).
+
+## [Unreleased]
+
+## [2.1.0] - 2026-10-17
+
+It includes everything prepared for 2.0.1, which was never published.
+
+### Added
+
+- `valid_until` on `IssuedPackage` (`issuePackage`, `getPackage`) and on `EsimPackage` (`getEsim`'s `packages`): when the package's validity ends and its data stops working, activation plus its time allowance. Null until the package activates.
+
+### Changed
+
+- The SDK now speaks Partner API 5.13.0 (`SUPPORTED_API_VERSION`), after 5.12.0: every refusal has a `code`, and a terminate spends the issue key.
+- `getDestination` and `getDestinationBundles` take a destination as a ULID, an ISO 3166-1 alpha-2 or alpha-3 code, or its English name (exact, any letter case). The parameter is renamed from `code` to `destination`; it is positional, so your calls do not change. A value that names no destination you can sell answers `404` `not_found`.
+- `expires_at` is described as what it is: the latest moment the package can still be activated, not when its validity ends. Use `valid_until` for that.
+- A package that is `terminated` or `expired` answers `data_remaining_bytes: 0` (still `null` on unlimited). `data_used_bytes` stays what was used.
+- A `404` with `code: not_found` answers the message `Not found.`. Branch on `code`, not on the message.
+- The public surface does not change. The types change only by `valid_until`.
+
+### Documentation
+
+- README and `llms.txt`: "Build a shop": list destinations with `getDestinations()`, which answers `{ countries, regions }` with no `data`, and the fields of an entry; the plans of one with `getDestinationBundles()`. `getBundles()` is for a periodic sync, revalidated with its `ETag`.
+- README and `llms.txt`: "Add a package to a traveller's eSIM": each traveller has one Universal eSIM; book again for the same `external_user_id`, then issue; the answer is `installed` once the eSIM is on the phone. There is no `topUp()` call. The Hubby apps offer a top-up only for a destination the traveller already holds, which the Partner API does not enforce, and where to find a package's destination.
+- README: "What an issue answers" lists `valid_until` and says how it differs from `expires_at`.
+
+- The README no longer carries Hubby's internal build and release steps, and no longer links to `AGENTS.md`, which the package does not ship. A test now fails when a shipped document links to a file the package does not ship.
+- README and `llms.txt`: the booking example also specifies a package by destination, type and size. A new "Specify a package" section says what `bundle_id` books, the `destination` and `size` formats, the `package_type` values and both spellings, that an item specified by dimensions answers `bundle_id: null` until it is issued, the `package_strategy` refusal, and which bundle fields to pick by (sizes in binary units).
+- README and `llms.txt`: a new "What an issue answers" section lists the fields of `issuePackage` and `getPackage`, says the package `id` is the one in `getEsim`'s `packages`, and that a second issue for the same traveller lands on the same eSIM. "What to show per `state`" says which states an item and a package answer, that an item is `queued` at once after your terminate, and that `getPackage` answers `404` `item_has_no_package` for an item with no package. The issue example says a key replays for 24 hours with `Idempotent-Replayed: true`, and is spent (`409` `idempotency_key_spent`, not retried) after a terminate.
+- README, "Every call": which identifiers `{booking}` and `id` take, why `cancelBooking` answers `403` and how `Booking.is_cancellable` tells you first, the per-Partner rate limit on `getEsim(iccid, { refresh: true })`, and how the response and input types are named. "Errors": every refusal now has a `code` (Partner API 5.12.0), with a table of the codes you meet while integrating.
+
+## [2.0.0] - 2026-10-16
+
+A clean break: the generated operations are no longer the public API. Partner API 5.11.0, as before.
+
+### Removed
+
+- The generated `partnerApiV1*` functions. Call the matching `Hubby` method.
+- `createHubbyClient` and its options type `HubbyClientOptions`. Use `new Hubby({ apiKey, apiSecret })`.
+- The generated `Client` type.
+- `orderStep` and its types. The README's "What to show per `state`" table replaces it.
+
+### Added
+
+- `Hubby`: built once from the credentials, with one method per Partner API operation, named in the Partner guide's words (`getBundles`, `createBooking`, `issuePackage`, `getPackage`, `terminatePackage`, `getEsim` and the rest). Path identifiers come first, the request fields in one object. A method resolves with the response body; `cancelBooking` and `terminatePackage` resolve `undefined`.
+- `HubbyApiError`, thrown on every non-`2xx` answer, with `status`, `code`, `message`, `errors`, `body` and `response`.
+- A type for every input and response, by name (`CreateBookingInput`, `IssuePackageInput`, `BookingResponse`, `PackageResponse` and the rest), and the resource types.
+- Per-call `signal` and `headers` on every method.
+- Production (`https://core.hubbyesim.com/api`) is the default `baseUrl`.
+
+## [1.0.1] - 2026-10-16 (unpublished)
+
+### Changed
+
+- Staged from GitHub Actions through npm trusted publishing and approved on npm by a maintainer with 2FA.
+- The README examples and the signing vectors use neutral sample names. The two request vectors with new inputs have new expected signatures. The signing scheme does not change.
+- The code and the API are the same as in 1.0.0.
+
+## [1.0.0] - 2026-10-16 (unpublished)
+
+### Added
+
+- First release, for Partner API 5.11.0.
+- `createHubbyClient`: signs every request with the Partner API v1 HMAC scheme, adds an `Idempotency-Key` to every POST and reuses it on each retry, and retries `429` answers and network errors, waiting out `Retry-After`.
+- `createHubbyClient` throws at construction, naming the option, for an empty `apiKey` or `apiSecret` or a `baseUrl` that is not an absolute URL.
+- Every request sends `User-Agent: hubbyesim-sdk/<version>` unless the caller sets one.
+- An abort during a retry wait rejects at once, and no further attempt is sent.
+- A typed function for every Partner API operation, generated from its OpenAPI document.
+- `signRequest` for sending with your own HTTP client, and `signing-vectors.json` with known-answer vectors.
+- `verifyWebhook` for webhook signatures and timestamps.
+- `orderStep`, which maps an item's `state` to the screen to show.
+- `LICENSE` (MIT), this changelog, npm metadata (keywords, author, bug tracker, homepage), and a `./package.json` export.
+- A security contact in the README.
+- `llms.txt`, shipped in the package: a summary, one flow and the links a coding agent needs to integrate the SDK.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hubby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# @hubbyesim/sdk
+
+[![npm](https://img.shields.io/npm/v/@hubbyesim/sdk.svg)](https://www.npmjs.com/package/@hubbyesim/sdk)
+
+The official TypeScript SDK for the **Hubby Partner API**. Use it to sell Hubby eSIMs in your own booking flow or app: book, issue the eSIM, show the install screen, terminate, and read status and usage, with no Hubby app in front of the traveller.
+
+The SDK:
+
+- gives you one `Hubby` object, built from your credentials once, with a method for every Partner API operation, named in the Partner guide's words;
+- returns the response body the guide documents, and throws a `HubbyApiError` on a refusal;
+- signs every request with the Partner API v1 HMAC scheme, so you never build the canonical string;
+- adds an `Idempotency-Key` to every POST and reuses it on each retry, so a retry after a timeout never books or issues twice;
+- retries `429` answers and network errors, waiting out `Retry-After`;
+- verifies webhook signatures and timestamps.
+
+SDK 2.0.0 speaks Partner API **5.11.0** (`SUPPORTED_API_VERSION`). The SDK has its own version number. A new Partner API minor is additive, so this SDK keeps working against it.
+
+Requires Node.js 24 or later (or any runtime with `fetch` and Web Crypto: Bun, Deno, edge workers). Use it on your server only. Your API secret must never reach a browser or a mobile app.
+
+## Install
+
+```bash
+npm install @hubbyesim/sdk
+```
+
+## Create a client
+
+```ts
+import { Hubby } from '@hubbyesim/sdk';
+
+const hubby = new Hubby({
+    apiKey: process.env.HUBBY_API_KEY!, // your public key id
+    apiSecret: process.env.HUBBY_API_SECRET!,
+    // baseUrl: 'https://core-staging.hubbyesim.com/api', // staging
+});
+```
+
+Each method takes the path identifiers first, then one object with the request fields, then the per-call options. It resolves with the response body as the Partner guide documents it, and rejects with a `HubbyApiError` on a non-`2xx` answer (see "Errors").
+
+Options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `baseUrl` | `https://core.hubbyesim.com/api` | The Partner API to call. Staging is `https://core-staging.hubbyesim.com/api`. A trailing slash is ignored. |
+| `retry` | `{ maxAttempts: 3, maxDelayMs: 30000, baseDelayMs: 500 }` | Attempts per request, the first included. A `Retry-After` longer than `maxDelayMs` is returned to you rather than waited out. `false` sends each request once. |
+| `fetch` | global `fetch` | The `fetch` to send with, for example one with a proxy or a timeout. |
+
+`new Hubby(...)` throws at once, naming the option, when `apiKey` or `apiSecret` is empty or `baseUrl` is not an absolute URL. Every request sends `User-Agent: hubbyesim-sdk/<version>` unless you set your own `User-Agent` header on the call.
+
+What is retried:
+
+- `429` on any method, after `Retry-After` (else an exponential backoff from `baseDelayMs`).
+- `409` with `code: idempotency_key_in_use`: the first attempt of the same request is still running on our side.
+- A network error on `GET` and `POST`. A `PATCH` or `DELETE` is not repeated after a network error: a repeated terminate answers `404`, which would hide that the first one succeeded. Read the item back instead.
+- Nothing after an abort: aborting the call's `signal` during a retry wait rejects at once with the signal's reason, and no further attempt is sent.
+
+Every attempt is signed again, so a retry after a wait is still inside the 300-second timestamp window.
+
+## Book, issue, install, terminate, read
+
+```ts
+// 1. The catalogue: every bundle you can sell, with retail and net prices.
+//    Pick by destination.iso2, type, size_bytes and duration_days (see "Specify a package").
+const catalogue = await hubby.getBundles();
+
+// 2. Book. The SDK adds the Idempotency-Key.
+const booked = await hubby.createBooking({
+    external_reference: 'PARTNER-LOC-4471',
+    depart_at: '2026-11-02T00:00:00Z',
+    return_at: '2026-11-09T00:00:00Z',
+    locale: 'es',
+    package_specifications: [
+        // A bundle from the catalogue: books exactly that bundle.
+        { bundle_id: '01J…', external_user_id: 'partner-user-88213' },
+        // Or by destination, type and size: books the closest bundle.
+        {
+            destination: 'ES',
+            package_type: 'data-limited',
+            size: '3GB',
+            external_user_id: 'partner-user-88213',
+        },
+    ],
+});
+const item = booked.data.items![0];
+
+// 3. Issue the eSIM. The key is required on this call: create it once per issue
+//    attempt and store it with your own purchase record before the call, so a retry after a
+//    crash replays the same issue instead of being refused. Do not derive it from
+//    the item id: after a terminate, the next issue of the same item needs a new key.
+//    A key replays its first answer for 24 hours, with the header Idempotent-Replayed: true.
+//    After a terminate, the key is spent: see idempotency_key_spent under "Errors".
+const idempotencyKey = await keyStoredWithThePurchase(); // for example crypto.randomUUID(), saved first
+const issued = await hubby.issuePackage('PARTNER-LOC-4471', item.id, {
+    idempotencyKey,
+    external_user_id: 'partner-user-88213',
+});
+
+// 4. Decide what to show from issued.data.state: see the table below.
+//    issued.data.esim.install_links.ios / .android: one-tap install on the phone itself.
+//    issued.data.esim.lpa: render as a QR code for a second device.
+//    issued.data.esim.smdp_address + matching_id: manual entry.
+
+// 5. Terminate before the first network attach (withdrawal, changed plans).
+//    Resolves with nothing once the Partner API answers 204.
+await hubby.terminatePackage('PARTNER-LOC-4471', item.id, {
+    reason: 'changed_plans',
+});
+
+// 6. Status and remaining data. `refresh: true` reads the network now.
+const esim = await hubby.getEsim(issued.data.esim.iccid, { refresh: true });
+```
+
+### Build a shop
+
+```ts
+// The shop's list. The answer is { countries, regions }, with no `data` around it.
+// Each entry: id, name, type, iso2, iso3, iso3s, i18n_name; a region also has slug and country_names.
+const { countries, regions } = await hubby.getDestinations();
+
+// The plans of the destination the traveller opens, for example 'ES'.
+const plans = await hubby.getDestinationBundles(opened);
+```
+
+`getDestination` and `getDestinationBundles` take a destination as a ULID (its `id`), an ISO 3166-1 alpha-2 or alpha-3 code (`ES`, `ESP`), or its English name (`Spain`). A code or a name must match exactly, in any letter case; a translated name does not resolve. A value that names no destination you can sell answers `404` `not_found`.
+
+Do not load `getBundles()` per screen: it answers your whole catalogue. Use it for a periodic sync, for example once a day. Its answer carries an `ETag`. Send that value back as `If-None-Match` in the call's `headers`; an unchanged catalogue answers `304` with no body, which rejects with a `HubbyApiError` whose `status` is `304`. The method resolves with the body only, so read the `ETag` in the `fetch` you pass to `new Hubby` (see "Create a client").
+
+### Specify a package
+
+A package specification names its package in one of two ways:
+
+- **By `bundle_id`**, from `getBundles()`. It books exactly that bundle. `destination`, `package_type`, `size` and `package_duration` are read from the bundle and ignored when you send them. A bundle outside your catalogue answers `422`.
+- **By dimensions**: `destination`, `package_type` (`data-limited`, `starter` or `unlimited`) and, for `data-limited`, `size` (`'512MB'`, `'1GB'`, `'3GB'`, …). It books the closest bundle. The item answers `bundle_id: null` until it is issued; its `size_bytes` shows the size it will get.
+
+`destination` is a country or a region: an ISO 3166-1 alpha-2 or alpha-3 code (`ES`, `ESP`), a region's code (for example `EU`), or the destination's English name (`Spain`, `Europe`), in any letter case. The `iso2` or `iso3` of a catalogue bundle's `destination` works as it is.
+
+When `getPartner()` reports a `package_strategy`, the strategy chooses the bundle: omit `bundle_id` (it answers `422`) and the fields the strategy sets.
+
+To pick from the catalogue, read each bundle's `destination.iso2`, `type`, `size_bytes` and `duration_days`. Sizes count in binary units: `1GB` is `1073741824` bytes, `3GB` is `3221225472`.
+
+A specification accepts the type as `data-limited` or `data_limited`; `Bundle.type` and an item's `package_type` answer `data_limited`, so you may copy the catalogue's value into a specification. (Webhooks spell it `data-limited`.)
+
+### What an issue answers
+
+`issuePackage` and `getPackage` answer the package: `id`, `state`, `bundle_id`, `issued_at`, `installed_at`, `activated_at`, `expires_at`, `valid_until`, `terminated_at`, and `esim` with `iccid`, `installed_at`, `install_links` (`ios`, `android`), `lpa`, `smdp_address` and `matching_id`. The package's `id` is the same `id` that `getEsim` lists under `packages`, so the two reads name one package.
+
+`valid_until` is when the package's validity ends and its data stops working: activation plus the package's time allowance. It is null until the package activates (show "starts on first use"). `expires_at` is not that: it is the latest moment the package can still be activated. Each package in `getEsim`'s `packages` carries both too.
+
+A second issue for the same traveller puts the new package on the same eSIM, with the same ICCID. Before the eSIM is on the phone, the answer is `redeemed` with the same install material again; once it is on the phone, `installed`.
+
+### What to show per `state`
+
+An item (in `createBooking`, `getBooking` and `getBookings`) and a package (in `issuePackage`, `getPackage` and `getEsim`'s `packages`) each have a `state`. An item answers its package's `state` once it has one; before that it is `queued`, `unavailable`, `redeemed` or `cancelled`. A package's `state` is one of `redeemed`, `installed`, `activated`, `expired` or `terminated`. Read the one you have and show:
+
+| `state` | Show |
+|---|---|
+| `queued` | Issue: call `issuePackage`. |
+| `unavailable` | Nothing to issue: cancel the booking or book again. |
+| `redeemed` | Install: the one-tap `install_links` on the phone itself, `lpa` as a QR code for a second device, or `smdp_address` plus `matching_id` for manual entry. |
+| `installed` | Ready: the eSIM is already on the phone. Skip the install screen and say the new package is ready. |
+| `activated` | Usage: the remaining data from `getEsim`. |
+| `expired` | Ended: offer a new booking. |
+| `terminated` | The package ended before it attached. After your `terminatePackage`, its item answers `queued` at once. Issue again with a new key (see `idempotency_key_spent` under "Errors"). Or cancel the booking. |
+| `cancelled` | Cancelled. `cancelBooking` cancels every `queued` item of the booking. |
+| a state newer than this SDK | A neutral status. Do not fail. |
+
+An item with no package has no package to read: see `item_has_no_package` under "Errors".
+
+### Add a package to a traveller's eSIM
+
+Each traveller has one Universal eSIM, and every package you issue for them attaches to it. To add a package, book again for the same `external_user_id`, then issue. There is no `topUp()` call; this is it.
+
+```ts
+const topUp = await hubby.createBooking({
+    external_reference: 'PARTNER-LOC-5120',
+    package_specifications: [
+        {
+            destination: 'ES',
+            package_type: 'data-limited',
+            size: '3GB',
+            external_user_id: 'partner-user-88213', // the same traveller
+        },
+    ],
+});
+const added = await hubby.issuePackage('PARTNER-LOC-5120', topUp.data.items![0].id, {
+    idempotencyKey: topUpKey, // a new key, stored first, as in step 3
+    external_user_id: 'partner-user-88213',
+});
+// added.data.esim.iccid is the traveller's eSIM, as before.
+// added.data.state is 'installed' once the eSIM is on the phone: skip the install screen.
+```
+
+The Hubby apps offer a top-up only for a destination the traveller already holds; any other destination is a purchase from the shop. The Partner API does not enforce this, so your app must. `getEsim` names only each package's `bundle_id` and `booking_id`, so take a package's destination from its booking's item (`getBooking`), or from your own record of what you sold.
+
+### Every call
+
+| Method | Partner API | Resolves with |
+|---|---|---|
+| `getPartner()` | `GET /v1/me` | your Partner and its settings |
+| `getBundles()` | `GET /v1/bundles` | the Bundles you sell, for a periodic sync (see "Build a shop") |
+| `getDestinations(filters?)`, `getDestination(destination)`, `getDestinationBundles(destination)` | `GET /v1/destinations…` | `{ countries, regions }` (no `data`), one destination, or its Bundles |
+| `createBooking(input)` | `POST /v1/bookings` | the booking |
+| `getBookings(filters?)`, `getBooking(id)` | `GET /v1/bookings…` | a page of bookings (pass `pagination.nextCursor` back as `cursor`), or one booking |
+| `updateBooking(id, input)` | `PATCH /v1/bookings/{id}` | the booking |
+| `cancelBooking(id)` | `DELETE /v1/bookings/{id}` | nothing (`undefined`): the API answers `200` with a message, which the method drops |
+| `updatePackageSpecification(bookingId, uuid, input)`, `updatePackageSpecifications(bookingId, input)` | `PATCH /v1/bookings/{booking_id}/package-specifications…` | the changed specifications |
+| `presignBookingImport(input)` | `POST /v1/bookings/imports/presign-upload` | an upload URL |
+| `issuePackage(booking, item, input)` | `POST /v1/bookings/{booking}/items/{item}/package` | the package, with its eSIM |
+| `getPackage(booking, item)` | `GET /v1/bookings/{booking}/items/{item}/package` | the package |
+| `terminatePackage(booking, item, input?)` | `DELETE /v1/bookings/{booking}/items/{item}/package` | nothing (`undefined`): the API answers `204` |
+| `getEsim(iccid, input?)`, `getEsimInstructions(iccid, input?)` | `GET /v1/esims/{iccid}…` | the eSIM and its packages, or its install instructions |
+| `getCompatibleDevices()`, `checkDeviceCompatibility(input)` | `/v1/device-compatibility` | the devices that take an eSIM, or the answer for one |
+| `createRedirectToken(input)` | `POST /v1/redirect-tokens` | a redirect token |
+| `getAnalyticsSummary(query?)`, `getAnalyticsFunnel(query?)`, `getAnalyticsTimeseries(query?)`, `getAnalyticsBreakdowns(query?)` | `GET /v1/analytics/…` | the analytics for a date range |
+
+`{booking}` (and `id` on the booking methods) is the booking's `id` or your `external_reference`; when several of your bookings share a reference, the most recently created one answers. `{item}` is the item's `id`.
+
+`cancelBooking` answers `403` with a `code` when the booking cannot be cancelled. The codes are:
+
+- `booking_departed`: the booking's `depart_at` has passed. The API compares that moment with the current time, not the date.
+- `booking_has_redeemed_promo_codes`: an item holds an issued package that is not terminated. Terminate the package first.
+- `booking_has_paid_packages`: a traveller paid for a package on the booking.
+
+`Booking.is_cancellable` tells you before you call.
+
+`getEsim(iccid, { refresh: true })` reads the network now, and is rate-limited per Partner, per minute. A refused refresh answers `429` with `Retry-After`, which the SDK waits out (see "What is retried"). A read without `refresh` is not limited and may be polled.
+
+Every input and response has a type you can import by name:
+
+- A method's response type ends in `Response`. Its `data` is the result. For example, `getPartner()` resolves with `PartnerResponse`, and its `data` is a `Partner`.
+- `createBooking`, `getBooking` and `updateBooking` resolve with `BookingResponse`. Its `data` is a `Booking`.
+- A list resolves with a `…ListResponse`. For example, `getBookings` resolves with `BookingListResponse`, and its `data` is a `Booking[]`.
+- The response name does not always repeat the resource name. `issuePackage` and `getPackage` resolve with `PackageResponse`, and its `data` is an `IssuedPackage`.
+- An input type has the name of the call, for example `CreateBookingInput` and `IssuePackageInput`.
+- A filter or query type has the name of what it holds, for example `BookingListFilters` and `AnalyticsQuery`.
+
+## Errors
+
+A non-`2xx` answer rejects with a `HubbyApiError`:
+
+| Field | Holds |
+|---|---|
+| `status` | The HTTP status, for example `409` or `422`. |
+| `code` | The refusal code, for example `idempotency_key_in_use`. Every Partner API refusal has one. |
+| `message` | The body's message, else `Partner API answered <status>`. |
+| `errors` | The field errors of a `422`, keyed by field. |
+| `body` | The parsed error body: JSON when it parses, else the text. |
+| `response` | The `Response`. |
+
+Branch on `code`, not on `message`. The codes you meet while integrating, on any call:
+
+| `status` | `code` | When |
+|---|---|---|
+| `401` | `unauthenticated` | The key or the signature is wrong, a signing header is missing, or your Partner is not active. |
+| `401` | `timestamp_out_of_window` | The request's timestamp is more than 300 seconds old, or ahead of the server's clock: check your clock. |
+| `404` | `not_found` | The path is wrong (check `baseUrl`), or the booking, item or eSIM does not exist or is not yours. |
+| `404` | `item_has_no_package` | `getPackage` or `terminatePackage` on one of your items that holds no package. For example, the item is `queued`, also right after your `terminatePackage`. Read the item's `state` from `getBooking` instead. |
+| `409` | `idempotency_key_in_use` | A request with the same `Idempotency-Key` is still running. The SDK retries it. |
+| `409` | `idempotency_key_spent` | The `Idempotency-Key` issued a package that you terminated after the issue. The key is spent. The SDK does not retry it. Issue again with a new key. |
+| `422` | `validation_failed` | A field failed validation. `errors` holds the messages, keyed by field, for example `package_specifications.0.size`. |
+| `429` | `rate_limited` | Too many requests. The SDK waits out `Retry-After` (see "What is retried"). |
+
+The refusals of one operation, such as the `cancelBooking` codes above, are listed with it in the Partner guide.
+
+One `catch` covers every call:
+
+```ts
+import { HubbyApiError } from '@hubbyesim/sdk';
+
+try {
+    await hubby.issuePackage(booking, item, { idempotencyKey, external_user_id });
+} catch (error) {
+    if (error instanceof HubbyApiError) {
+        // error.status, error.code, error.errors
+    }
+
+    throw error;
+}
+```
+
+A call that gets no answer is not a `HubbyApiError`: a network error after the retries rejects with the underlying error, and an abort rejects with the signal's reason.
+
+## Per-call options
+
+Every method takes one more, optional, argument:
+
+| Option | Meaning |
+|---|---|
+| `signal` | An `AbortSignal`. Aborting it cancels the call, a retry wait included, and the call rejects with the signal's reason. |
+| `headers` | Extra headers to send. A `User-Agent` here replaces the SDK's. On `issuePackage`, the `idempotencyKey` you pass wins over an `Idempotency-Key` header. |
+
+```ts
+const bundles = await hubby.getBundles({ signal: AbortSignal.timeout(10_000) });
+```
+
+## Verify webhooks
+
+Read the raw body. A parsed and re-serialised body does not verify.
+
+```ts
+import express from 'express';
+import { verifyWebhook, WebhookVerificationError } from '@hubbyesim/sdk';
+
+app.post('/hubby/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
+    try {
+        const event = await verifyWebhook({
+            secret: process.env.HUBBY_WEBHOOK_SECRET!,
+            body: req.body, // a Buffer of the raw bytes
+            headers: req.headers,
+        });
+
+        // Deduplicate on event.event_id: retries repeat it.
+        await handle(event.event, event.data);
+        res.sendStatus(204);
+    } catch (error) {
+        if (error instanceof WebhookVerificationError) {
+            // error.reason: missing_signature | missing_timestamp | stale_timestamp | invalid_signature | invalid_body
+            res.sendStatus(400);
+
+            return;
+        }
+
+        throw error;
+    }
+});
+```
+
+`verifyWebhook` checks that `x-hubby-timestamp` is within `toleranceSeconds` (default 300) of now, in either direction, and that one entry of `x-hubby-signature` equals `sha256=` plus the hex HMAC-SHA256 of `{x-hubby-timestamp}.{raw body}`. The comparison is constant-time. Answer `2xx` within a few seconds; anything else is retried with backoff.
+
+## Signing without the client
+
+`signRequest(secret, { method, url, timestamp, body })` returns the `X-Signature` for one request, if you send with your own HTTP client. `signing-vectors.json` in this package holds known-answer vectors (secret, method, URL, timestamp, body, expected signature) that Hubby's own server tests read too; use them to test a port to another language.
+
+## More
+
+The Partner API guide describes every call, field, refusal `code` and webhook event in full. The OpenAPI document this SDK is generated from is published with each Partner API release.
+
+What changed between versions is in [`CHANGELOG.md`](CHANGELOG.md).
+
+## Using AI agents
+
+[`llms.txt`](llms.txt), shipped in this package, gives a coding agent the entry point, one flow and the links it needs to integrate the SDK.
+
+## Security
+
+Report a security problem to tech@hubbyesim.com, not in a public issue.