@hubbyesim/sdk 2.1.0 → 2.2.0

package/dist/index.js

@@ -1012,6 +1012,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" },
@@ -1121,8 +1130,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 = {
@@ -1368,7 +1377,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)
       })
     );
   }
@@ -1550,6 +1574,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 {

package/llms.txt

@@ -38,10 +38,12 @@ const issued = await hubby.issuePackage('ORDER-4471', item.id, {
 });
 // A key replays its first answer for 24 hours (Idempotent-Replayed: true); after a terminate it answers 409 idempotency_key_spent: issue again with a new key.
 // state 'redeemed': show issued.data.esim.install_links, or issued.data.esim.lpa as a QR code.
+// state and every other response enum is its known values or any other string (a minor can add one): switch with a default branch.
 // issued.data (also getPackage): id (the id in getEsim's packages), state, bundle_id, issued_at, installed_at, activated_at, expires_at, terminated_at, esim { iccid, installed_at, install_links { ios, android }, lpa, smdp_address, matching_id }.
 
 await hubby.terminatePackage('ORDER-4471', item.id, { reason: 'changed_plans' }); // resolves undefined (204)
 const esim = await hubby.getEsim(issued.data.esim.iccid, { refresh: true });
+// Each of esim.data.packages carries its destination { id, name, type, iso2, iso3 }.
 // issued.data and each of esim.data.packages carry valid_until: when the data stops working, null until activation. expires_at is only the latest moment the package can still be activated.
 ```
 
@@ -55,12 +57,23 @@ const { countries, regions } = await hubby.getDestinations();
 const plans = await hubby.getDestinationBundles('ES');
 ```
 
-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, so skip the install screen. There is no `topUp()` call; this is it. The Hubby apps offer a top-up only for a destination the traveller already holds, and 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`: take a package's destination from its booking's item, or from your own record of what you sold.
+Show usage: `getEsimUsage(iccid)` answers `data`, one entry per destination, newest first; show one card per entry, with the figures the Hubby apps show. Days left: from `remaining_seconds`, set even before a date is known. Add "until <date>" when `valid_until` is set; null does not mean unused, because an older package in the entry can already be in use. `remaining_bytes === 0`: used up. Anything else: `remaining_bytes` of `total_bytes` left. On `is_unlimited`, `total_bytes` and `remaining_bytes` are null and `used_bytes` is still set. A destination can appear twice (one data entry, one unlimited entry), and packages the traveller bought in the Hubby app count too. `refresh: true` shares `getEsim`'s rate limit.
 
 ```ts
+const usage = await hubby.getEsimUsage(iccid);
+// Each entry: destination { id, name, type, iso2, iso3 }, is_unlimited, total_bytes, used_bytes, remaining_bytes, valid_until, remaining_seconds, package_ids (ids in getEsim's packages), synced_at.
+// total_bytes is always used_bytes + remaining_bytes: data an ended package did not use counts as used.
+const daysLeft = Math.ceil(usage.data[0].remaining_seconds / 86_400);
+```
+
+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, so skip the install screen. There is no `topUp()` call; this is it. The Hubby apps offer a top-up only for a destination the traveller already holds, and any other destination is a purchase from the shop; the Partner API does not enforce this, so your app must. To top up a usage entry, take the destination from the entry. Each of `getEsim`'s `packages` also carries its `destination`, the same object.
+
+```ts
+const plans = await hubby.getDestinationBundles(entry.destination.id); // entry: from getEsimUsage
 const topUp = await hubby.createBooking({
     external_reference: 'ORDER-5120',
-    package_specifications: [{ destination: 'ES', package_type: 'data-limited', size: '3GB', external_user_id: 'user-88213' }],
+    package_specifications: [{ bundle_id: plans.data[0].id, external_user_id: 'user-88213' }],
+    // With a package_strategy (no bundle_id): { destination: entry.destination.iso2 ?? entry.destination.name, ... }; a region has no iso2.
 });
 const added = await hubby.issuePackage('ORDER-5120', topUp.data.items![0].id, {
     idempotencyKey: crypto.randomUUID(), // stored with your purchase record first
@@ -71,7 +84,7 @@ const added = await hubby.issuePackage('ORDER-5120', topUp.data.items![0].id, {
 
 ## Docs
 
-- [README](https://www.npmjs.com/package/@hubbyesim/sdk): client options, retries, the full book, issue, install, terminate and read flow, what to show per state, every method, errors, per-call options, webhook verification, signing without the client
+- [README](https://www.npmjs.com/package/@hubbyesim/sdk): client options, retries, the full book, issue, install, terminate and read flow, what to show per state, show usage, every method, errors, per-call options, webhook verification, signing without the client
 - [Partner API guide](https://docs.hubbyesim.com/guides/native-api): every call, field, refusal code and webhook event
 
 ## Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubbyesim/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Official TypeScript SDK for the Hubby Partner API: signed requests, idempotent retries, webhook verification and typed operations.",
   "keywords": [
     "hubby",