@hubbyesim/sdk 2.1.0

package/llms.txt

@@ -0,0 +1,80 @@
+# @hubbyesim/sdk
+
+> Official TypeScript SDK for the Hubby Partner API v1. Use it on your server to sell Hubby eSIMs in your own booking flow or app: list the catalogue, book, issue the eSIM, show the install screen, terminate, and read status and usage. It signs every request with the Partner API HMAC scheme, adds an Idempotency-Key to every POST and reuses it on retries, retries 429 answers and network errors, verifies webhook signatures, and gives one `Hubby` class with a named method per Partner API operation. Requires Node.js 24 or later, or any runtime with fetch and Web Crypto. No runtime dependencies. Never send the API secret to a browser or a mobile app.
+
+Install:
+
+```bash
+npm install @hubbyesim/sdk
+```
+
+Primary entry point: `import { Hubby } from '@hubbyesim/sdk'`. Build `new Hubby({ apiKey, apiSecret })` once (production by default; `baseUrl: 'https://core-staging.hubbyesim.com/api'` for staging) and call its methods. A method takes path identifiers first, then one object with the request fields, then optional `{ signal, headers }`. It resolves with the response body and rejects with `HubbyApiError` (`status`, `code`, `message`, `errors`, `body`, `response`) on a non-2xx answer.
+
+```ts
+import { Hubby, HubbyApiError } from '@hubbyesim/sdk';
+
+const hubby = new Hubby({
+    apiKey: process.env.HUBBY_API_KEY!,
+    apiSecret: process.env.HUBBY_API_SECRET!,
+});
+
+const catalogue = await hubby.getBundles();
+const booked = await hubby.createBooking({
+    external_reference: 'ORDER-4471',
+    depart_at: '2026-11-02T00:00:00Z',
+    return_at: '2026-11-09T00:00:00Z',
+    locale: 'en',
+    package_specifications: [{ bundle_id: '<bundle id>', external_user_id: 'user-88213' }],
+    // Or by dimensions, which books the closest bundle: { destination: 'ES', package_type: 'data-limited', size: '3GB' }. The type is also accepted as 'data_limited', the spelling answers use.
+});
+const item = booked.data.items![0];
+
+// Create the key once per issue attempt and store it with your own purchase record before the call.
+// Do not derive it from the item id: after a terminate, the next issue needs a new key.
+const idempotencyKey = crypto.randomUUID();
+const issued = await hubby.issuePackage('ORDER-4471', item.id, {
+    idempotencyKey,
+    external_user_id: 'user-88213',
+});
+// 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.
+// 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 });
+// 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.
+```
+
+Shop: list destinations with `getDestinations()` and the plans of one with `getDestinationBundles(destination)`. Do not load `getBundles()` per screen: it is the whole catalogue, for a periodic sync revalidated with its `ETag` (send it back as `If-None-Match` in the call's `headers`; an unchanged catalogue answers `304`, which rejects with `HubbyApiError` `status: 304`).
+
+```ts
+// 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();
+// destination: a ULID, an ISO alpha-2 or alpha-3 code, or the English name; exact, any letter case. Anything else answers 404 not_found.
+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.
+
+```ts
+const topUp = await hubby.createBooking({
+    external_reference: 'ORDER-5120',
+    package_specifications: [{ destination: 'ES', package_type: 'data-limited', size: '3GB', external_user_id: 'user-88213' }],
+});
+const added = await hubby.issuePackage('ORDER-5120', topUp.data.items![0].id, {
+    idempotencyKey: crypto.randomUUID(), // stored with your purchase record first
+    external_user_id: 'user-88213',
+});
+// added.data.state 'installed': the eSIM is already on the phone.
+```
+
+## 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
+- [Partner API guide](https://docs.hubbyesim.com/guides/native-api): every call, field, refusal code and webhook event
+
+## Optional
+
+- `CHANGELOG.md`, shipped in this package: what changed between versions
+- Security contact: tech@hubbyesim.com (report a security problem there, not in a public issue)

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@hubbyesim/sdk",
+  "version": "2.1.0",
+  "description": "Official TypeScript SDK for the Hubby Partner API: signed requests, idempotent retries, webhook verification and typed operations.",
+  "keywords": [
+    "hubby",
+    "esim",
+    "e-sim",
+    "travel",
+    "partner-api",
+    "sdk",
+    "typescript"
+  ],
+  "author": "Hubby",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hubbyesim/core.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/hubbyesim/core/issues"
+  },
+  "homepage": "https://github.com/hubbyesim/core/tree/main/packages/sdk#readme",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./signing-vectors.json": "./signing-vectors.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "signing-vectors.json",
+    "LICENSE",
+    "CHANGELOG.md",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "generate": "openapi-ts",
+    "check:api-version": "node scripts/check-api-version.mjs openapi/partner.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.test.json",
+    "build": "tsup",
+    "prepublishOnly": "npm run check:api-version && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@types/node": "^24.19.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/signing-vectors.json

@@ -0,0 +1,87 @@
+{
+  "description": "Known-answer vectors for the Hubby Partner API signing schemes. Read by the @hubbyesim/sdk vitest suite and by core (tests/Unit/Auth/Hmac/V1SchemeTest.php, tests/Unit/Integrations/PartnerWebhook/WebhookSignerTest.php), so the two implementations cannot drift. requests: HUBBY-HMAC-SHA256-v1 X-Signature over the six-line canonical string. webhooks: x-hubby-signature, sha256= plus hex HMAC-SHA256 of {timestamp}.{raw body}. Never change an expected signature to make a test pass; a mismatch is a signing change that breaks every Partner.",
+  "requests": [
+    {
+      "name": "a GET with no body",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "GET",
+      "url": "https://core.hubbyesim.com/api/v1/me",
+      "host": "core.hubbyesim.com",
+      "request_uri": "/api/v1/me",
+      "timestamp": "1760000000",
+      "body": "",
+      "signature": "56c1d5b088ca50d70300627eab84f0fdb58fbca7b40898ce3e75ce1ca7452f85"
+    },
+    {
+      "name": "a GET with a query string",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "GET",
+      "url": "https://core.hubbyesim.com/api/v1/bookings?cursor=eyJpZCI6MX0&per_page=10",
+      "host": "core.hubbyesim.com",
+      "request_uri": "/api/v1/bookings?cursor=eyJpZCI6MX0&per_page=10",
+      "timestamp": "1760000000",
+      "body": "",
+      "signature": "779fc32db2d38930c899fba3a6c3ccfdc834ad2c0be95c2c6b35a1177811cff3"
+    },
+    {
+      "name": "a GET on an explicit port",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "GET",
+      "url": "http://localhost:8000/api/v1/esims/8944000000000000001?refresh=true",
+      "host": "localhost:8000",
+      "request_uri": "/api/v1/esims/8944000000000000001?refresh=true",
+      "timestamp": "1760000000",
+      "body": "",
+      "signature": "8c1f3948ffe666eab9c428d04fe13cd75f53a828cd5b12f2a5feb3b9c365466d"
+    },
+    {
+      "name": "a POST with a JSON body",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "POST",
+      "url": "https://core-staging.hubbyesim.com/api/v1/bookings",
+      "host": "core-staging.hubbyesim.com",
+      "request_uri": "/api/v1/bookings",
+      "timestamp": "1760000000",
+      "body": "{\"external_reference\":\"PARTNER-LOC-4471\",\"package_specifications\":[{\"bundle_id\":\"01J9X3K2M4N5P6Q7R8S9T0V1W2\",\"external_user_id\":\"partner-user-88213\"}]}",
+      "signature": "768634f85c6b28a93e15e2ca942c3c3b4d031e4caf3fd530aa188194ba430b69"
+    },
+    {
+      "name": "a POST body with a newline and non-ASCII bytes",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "POST",
+      "url": "https://core.hubbyesim.com/api/v1/bookings",
+      "host": "core.hubbyesim.com",
+      "request_uri": "/api/v1/bookings",
+      "timestamp": "1760000000",
+      "body": "{\n  \"first_name\": \"Ana\",\n  \"last_name\": \"García Ωmega\"\n}",
+      "signature": "75ffd5a57ff5d0a7b584824a146a7897f0fb5e0c4278431085bdfd3be77efbfe"
+    },
+    {
+      "name": "a DELETE with a query string and no body",
+      "secret": "hubby-sdk-vector-secret-0f3c9a71",
+      "method": "DELETE",
+      "url": "https://core.hubbyesim.com/api/v1/bookings/PARTNER-LOC-4471/items/01J9X3K2M4N5P6Q7R8S9T0V1W2/package?reason=changed_plans",
+      "host": "core.hubbyesim.com",
+      "request_uri": "/api/v1/bookings/PARTNER-LOC-4471/items/01J9X3K2M4N5P6Q7R8S9T0V1W2/package?reason=changed_plans",
+      "timestamp": "1760000000",
+      "body": "",
+      "signature": "f2202fdc68fbfcced0041d9f9a8d6c75d4fc22639522f619aefde5fb153aa833"
+    }
+  ],
+  "webhooks": [
+    {
+      "name": "a package.activated delivery",
+      "secret": "whsec_hubby_sdk_vector",
+      "timestamp": "1760000000",
+      "body": "{\"event\":\"package.activated\",\"timestamp\":\"2026-11-02T13:40:00.000Z\",\"data\":{\"iccid\":\"8944000000000000001\"},\"event_id\":\"package.activated:01J9X3K2M4N5P6Q7R8S9T0V1W2\",\"delivery_id\":\"01J9X3K2M4N5P6Q7R8S9T0V1W3\"}",
+      "signature": "sha256=c86bede0e3d359c66c57703b7ffb08e4fbe3f445b9bd7c028cc978c48f5a79a3"
+    },
+    {
+      "name": "a body with non-ASCII bytes",
+      "secret": "whsec_hubby_sdk_vector",
+      "timestamp": "1760000000",
+      "body": "{\"event\":\"booking.created\",\"data\":{\"last_name\":\"García\"}}",
+      "signature": "sha256=55252e4ec2ad26b023e5a0a6b2334ae9e4cf777a4c4cf135526ed3b5d4113423"
+    }
+  ]
+}