@hubbyesim/sdk 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-17
+
+### Added
+
+- `getEsimUsage(iccid, { refresh })` (`GET /v1/esims/{iccid}/usage`): what the traveller can still use on the eSIM, one `DestinationUsage` entry per destination, newest first, with `total_bytes`, `used_bytes`, `remaining_bytes`, `valid_until`, `remaining_seconds`, `package_ids` and `synced_at`. The figures are the ones the Hubby apps show: `total_bytes` is always `used_bytes + remaining_bytes`, and `remaining_seconds` is the time left, set even while `valid_until` is null. Packages for the same destination add up into one entry; data and unlimited packages for one destination are two entries. Packages the traveller bought in the Hubby app count too. `refresh: true` shares `getEsim`'s rate limit. Its response type is `EsimUsageResponse`.
+- The `DestinationUsage` type.
+- The `DestinationSummary` type: the destination object a usage entry, an eSIM package and a bundle carry. Its `type` is the new open response enum `DestinationKind` (`country` or `region`, or any other string).
+- `destination` on `EsimPackage` (`getEsim`'s `packages`): the package's destination, with `id`, `name`, `type`, `iso2` and `iso3`.
+- `name` and `type` on a `Bundle`'s `destination` (`getBundles`, `getDestinationBundles`): the same destination object a usage entry and an eSIM package carry.
+
+### Changed
+
+- The SDK now speaks Partner API 5.14.0 (`SUPPORTED_API_VERSION`), after 5.13.0.
+- Response enums are open: every enum in a response or resource type (`PackageLifecycleState`, `PackageQueueStatus`, `PackageType`, `BookingSource`, `EndCustomerChannel`, `FairUseThrottleReset`, and the enums inside `Bundle`, `AnalyticsMeta` and the other response types) accepts its known values or any other string, so a value a later Partner API minor adds still type-checks. Editors still complete the known values. Request enums (`CommunicationChannel`, `PartnerTerminateReason`, `SupportedLocale`, query filters) stay closed. Migration: add a `default` branch where you branch on a response enum. An exhaustive `switch` that ends in a `never` check stops compiling until it has one. Nothing changes at runtime.
+
+### Documentation
+
+- README and `llms.txt`: a new "Show usage" section: one card per `getEsimUsage` entry; days left come from `remaining_seconds`, with "until <date>" when `valid_until` is set; `remaining_bytes === 0` reads "used up", anything else is the data left; `total_bytes` and `remaining_bytes` are null on unlimited. A destination can appear twice (data and unlimited), and packages bought in the Hubby app count.
+- README and `llms.txt`: "Add a package to a traveller's eSIM" takes the destination from a usage entry and books one of its plans by `bundle_id` (by dimensions under a `package_strategy`). A package's destination is now `destination` on the package, not its booking's item.
+- README: the version line names SDK 2.2.0 and Partner API 5.14.0.
+
 ## [2.1.0] - 2026-10-17
 
 It includes everything prepared for 2.0.1, which was never published.

package/README.md

@@ -13,7 +13,7 @@ The SDK:
 - 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.
+SDK 2.2.0 speaks Partner API **5.14.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.
 
@@ -158,26 +158,67 @@ An item (in `createBooking`, `getBooking` and `getBookings`) and a package (in `
 | `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`. |
+| `activated` | Usage: the data left and the days left from `getEsimUsage` (see "Show usage"). |
 | `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. |
 
+Every enum in a response (`state`, `status`, `source`, `package_type` and the others) is typed as its known values or any other string, because the Partner API can add a value in a minor release. Handle an unknown value in a `default` branch.
+
 An item with no package has no package to read: see `item_has_no_package` under "Errors".
 
+### Show usage
+
+`getEsimUsage(iccid)` answers what the traveller can still use on the eSIM, one entry per destination, newest first. Show one card per entry. The figures are the ones the Hubby apps show for the same eSIM.
+
+```ts
+const usage = await hubby.getEsimUsage(iccid);
+
+const cards = usage.data.map((entry) => {
+    const daysLeft = Math.ceil(entry.remaining_seconds / 86_400);
+
+    return {
+        title: entry.destination.name,
+        data: entry.is_unlimited
+            ? 'Unlimited'
+            : entry.remaining_bytes === 0
+              ? 'Used up'
+              : `${entry.remaining_bytes} of ${entry.total_bytes} bytes left`,
+        time:
+            entry.valid_until === null
+                ? `${daysLeft} days left`
+                : `${daysLeft} days left, until ${entry.valid_until}`,
+    };
+});
+```
+
+Read each entry as:
+
+- Days left: from `remaining_seconds`. It is set even before a date is known, because a package that has not started counts its whole validity.
+- `valid_until` set: add "until <date>". Null means the time that counts has not started yet. It does not mean the entry is unused: an older package in it can already be in use.
+- `remaining_bytes === 0`: used up, even when time is still left. A top-up adds to it.
+- Anything else: the data left, `remaining_bytes` of `total_bytes`.
+- `is_unlimited`: `total_bytes` and `remaining_bytes` are null; `used_bytes` is still set.
+
+Every package for the same destination adds up into one entry, so two Spain packages are one Spain card. A destination can appear twice: one entry for its data packages and one for its unlimited packages. A country and a region that covers it are two entries. Packages the traveller bought in the Hubby app count too. `package_ids` names the packages an entry adds up, the same `id`s as in `getEsim`'s `packages`. An empty `data` means nothing on the eSIM can still be used.
+
+`total_bytes` counts the whole allowance of every package in the entry, ended packages included, and is always `used_bytes + remaining_bytes`: data an ended package did not use counts as used. Draw a gauge from `remaining_bytes` against `total_bytes`. `synced_at` is when the figures were last read from the network; `refresh: true` reads them now, under the same rate limit as `getEsim`.
+
 ### 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.
 
+To top up a usage entry, take the destination from the entry: list its plans and book one by `bundle_id`.
+
 ```ts
+// entry: the usage entry the traveller tops up (see "Show usage").
+const plans = await hubby.getDestinationBundles(entry.destination.id);
 const topUp = await hubby.createBooking({
     external_reference: 'PARTNER-LOC-5120',
     package_specifications: [
         {
-            destination: 'ES',
-            package_type: 'data-limited',
-            size: '3GB',
+            bundle_id: plans.data[0].id, // the plan the traveller picks
             external_user_id: 'partner-user-88213', // the same traveller
         },
     ],
@@ -190,7 +231,9 @@ const added = await hubby.issuePackage('PARTNER-LOC-5120', topUp.data.items![0].
 // 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.
+When your Partner has a `package_strategy` (no `bundle_id`), book by dimensions instead: `destination: entry.destination.iso2 ?? entry.destination.name` (a region has no `iso2`).
+
+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. Each package in `getEsim`'s `packages` carries its `destination` (`id`, `name`, `type`, `iso2`, `iso3`), the same object a usage entry and a catalogue bundle carry.
 
 ### Every call
 
@@ -209,6 +252,7 @@ The Hubby apps offer a top-up only for a destination the traveller already holds
 | `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 |
+| `getEsimUsage(iccid, input?)` | `GET /v1/esims/{iccid}/usage` | what the traveller can still use, one `DestinationUsage` per destination (see "Show usage") |
 | `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 |
@@ -223,7 +267,7 @@ The Hubby apps offer a top-up only for a destination the traveller already holds
 
 `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.
+`getEsim(iccid, { refresh: true })` and `getEsimUsage(iccid, { refresh: true })` read the network now, and are rate-limited per Partner, per minute, together. 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:
 

package/dist/index.cjs

@@ -1045,6 +1045,15 @@ var partnerApiV1EsimsShow = (options) => (options.client ?? client).get({
   url: "/v1/esims/{iccid}",
   ...options
 });
+var partnerApiV1EsimsUsage = (options) => (options.client ?? client).get({
+  security: [
+    { name: "X-Api-Key", type: "apiKey" },
+    { name: "X-Signature", type: "apiKey" },
+    { name: "X-Timestamp", type: "apiKey" }
+  ],
+  url: "/v1/esims/{iccid}/usage",
+  ...options
+});
 var partnerApiV1EsimsInstructions = (options) => (options.client ?? client).get({
   security: [
     { name: "X-Api-Key", type: "apiKey" },
@@ -1154,8 +1163,8 @@ async function signRequest(secret, request) {
 }
 
 // lib/version.ts
-var SUPPORTED_API_VERSION = "5.13.0";
-var SDK_VERSION = "2.1.0";
+var SUPPORTED_API_VERSION = "5.14.0";
+var SDK_VERSION = "2.2.0";
 
 // lib/transport.ts
 var DEFAULT_RETRY = {
@@ -1401,7 +1410,22 @@ var Hubby = class {
         client: this.#client,
         ...options,
         path: { iccid },
-        query: input.refresh === void 0 ? void 0 : { refresh: `${input.refresh}` }
+        query: refreshQuery(input)
+      })
+    );
+  }
+  /**
+   * `GET /v1/esims/{iccid}/usage`: what the traveller can still use on the
+   * eSIM, one entry per destination, newest first. `refresh: true` reads
+   * the network now; it shares `getEsim`'s per-Partner rate limit.
+   */
+  async getEsimUsage(iccid, input = {}, options = {}) {
+    return unwrap(
+      await partnerApiV1EsimsUsage({
+        client: this.#client,
+        ...options,
+        path: { iccid },
+        query: refreshQuery(input)
       })
     );
   }
@@ -1583,6 +1607,9 @@ function unwrap(result) {
   }
   return result.data;
 }
+function refreshQuery(input) {
+  return input.refresh === void 0 ? void 0 : { refresh: `${input.refresh}` };
+}
 
 // lib/webhooks.ts
 var WebhookVerificationError = class extends Error {