@takeal/cusfront-sdk 0.1.0 → 0.2.8

package/CHANGELOG.md

@@ -4,10 +4,36 @@ All notable changes to `@takeal/cusfront-sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.8] — 2026-09-13
+
+The version number now matches the Takeal platform release the SDK was
+checked against, so this release jumps from 0.1.0 to 0.2.8 (platform tag
+`v0.2.8`).
+
+### Changed
+
+- **API paths are versioned.** Every request now goes to `/v1/...`
+  (`/v1/auth/login`, `/v1/me/deposits`, …); the SDK adds the prefix itself,
+  so `baseUrl` stays the bare API origin and resource calls are unchanged.
+  Only `/ready` and `/branding` remain unversioned. The API answers the old
+  unversioned paths with `410 Gone`, so 0.1.0 no longer works against it.
+- The npm page links to the repository with a plain `https://` URL.
 
 ### Added
 
+- `client.auth.register()` creates an account and signs it in. Takes an
+  optional `wallet_currency`.
+- `client.auth.completeTotpSetup()` finishes a `totp_setup_required` login
+  and returns the ten one-time backup codes.
+- `client.auth.changePassword()`. The account's other sessions are signed out.
+- `client.sessions`: `list()`, `revoke(jti)` and `revokeOthers()`.
+- `client.push`: `status()`, `save()`, `remove()`, plus `enable(registration)`
+  and `disable(registration)`, which subscribe or unsubscribe the browser and
+  update the server in one call.
+- Sub-exports `@takeal/cusfront-sdk/wallet`, `/sessions` and `/push`. Auth
+  types (`User`, `LoginResponse`, `Session` and the rest) are exported from
+  the package root.
+
 - `client.blog.list()` / `client.blog.get(slug)` — public posts returned as
   structured blocks (`body_blocks`) plus raw Markdown, so a site renders them
   in its own components instead of fighting server-side HTML.
@@ -31,7 +57,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   billing fields, issuing metrics, branding). `refresh-types` now scrubs
   internal references from doc comments before generating.
 
-## [0.1.0] — first public release
+## [0.1.0] — 2026-08-25 — first public release
 
 Initial release of the typed client for the Takeal end-user API.
 

package/README.md

@@ -1,10 +1,10 @@
 # @takeal/cusfront-sdk
 
-Typed TypeScript client for the **Takeal end-user API** — auth, deposits, cards, balance, and webhook signature verification.
+Typed TypeScript client for the **Takeal end-user API**: sign-up and login, wallet, deposits, cards, sessions, push notifications and webhook signature verification.
 
-The SDK powers any "Cusfront" (consumer front-end) on top of a Takeal deployment: a PWA, a Capacitor-wrapped mobile app, a Telegram Mini App, or anything else that talks to the `/auth/*` + `/me/*` surface. One client, runtime brand swap, zero runtime deps in the core.
+The SDK powers any end-user client app on top of a Takeal deployment: a PWA, a Capacitor-wrapped mobile app, a Telegram Mini App, or anything else that talks to the `/auth/*` + `/me/*` surface. One client, runtime brand swap, zero runtime deps in the core.
 
-> **Status:** 0.x — pre-release scaffold. Auth resource lands first; deposits + cards + balance + webhook verifier ship in subsequent releases.
+> **Versioning:** the SDK version matches the Takeal platform release it was checked against (SDK 0.2.8 goes with API release v0.2.8). Until 1.0, a minor version can break things; read the [changelog](./CHANGELOG.md) before upgrading.
 
 ## Install
 
@@ -42,9 +42,23 @@ if (result.stage === "jwt") {
 } else if (result.stage === "totp_required") {
   // Step-up required. Prompt the user for their TOTP code,
   // then call client.auth.verifyTotp({ challenge_token, code }).
+} else if (result.stage === "totp_setup_required") {
+  // The account has to enrol an authenticator first. Show result.otpauth_url
+  // as a QR code, then call client.auth.completeTotpSetup({ challenge_token, code })
+  // and show the backup_codes it returns. They are never sent again.
 }
 ```
 
+New users sign up with `register`, which also signs them in:
+
+```ts
+await client.auth.register({
+  email: "user@example.com",
+  password: "a-long-Passw0rd",
+  wallet_currency: "EUR", // optional; must be offered by the deployment
+});
+```
+
 ## Telegram Mini App
 
 Run inside a Telegram Mini App? Exchange the Telegram-signed `initData` for a
@@ -96,7 +110,7 @@ you built yourself.
 
 ## Brand config
 
-Whitelabel-friendly by design — the SDK ships no embedded brand. Pass `brand` at runtime and the consumer Cusfront reads it back via `client.brand`:
+Whitelabel-friendly by design — the SDK ships no embedded brand. Pass `brand` at runtime and the client app reads it back via `client.brand`:
 
 ```ts
 type BrandConfig = {
@@ -112,8 +126,9 @@ Switching brands does **not** require forking or re-publishing the SDK.
 
 The deployment also publishes its live brand config at `GET /branding` (public,
 no login needed) — `client.branding.get()` returns `platform_name`,
-`merchant_portal_name`, `logo_url`, `favicon_url` and `wallet_label`, so a
-Cusfront can re-theme itself at runtime and call the balance whatever the
+`merchant_portal_name`, `logo_url`, `favicon_url`, `wallet_label` and the
+`primary_color` / `secondary_color` / `accent_color` hex values, so a
+client app can re-theme itself at runtime and call the balance whatever the
 operator configured. Server values win over the build-time `brand` when both
 are present.
 
@@ -134,6 +149,9 @@ Available now:
 - `@takeal/cusfront-sdk/balance` — `BalanceResource` (per-currency wallet balance).
 - `@takeal/cusfront-sdk/blog` — `BlogResource` (public posts as structured blocks).
 - `@takeal/cusfront-sdk/subscriptions` — `SubscriptionsResource` (announcement channels).
+- `@takeal/cusfront-sdk/wallet` — `WalletResource` (the wallet's currency).
+- `@takeal/cusfront-sdk/sessions` — `SessionsResource` (where the user is signed in).
+- `@takeal/cusfront-sdk/push` — `PushResource` (Web Push subscription).
 - `@takeal/cusfront-sdk/webhooks` — HMAC-SHA256 signature verifier (no network, isomorphic).
 - `@takeal/cusfront-sdk/react` — optional React hooks layer (`ClientProvider` + `useMe` / `useDeposits` / `useCards` / `useBalance`). React is a `peerDependency`, never bundled.
 - `@takeal/cusfront-sdk/telegram` — Telegram Mini App `initData` → authenticated client bridge.
@@ -158,11 +176,10 @@ if (!ok) return res.status(401).end();
 Algorithm: HMAC-SHA256, header `X-Takeal-Signature: sha256=<hex>`, signed over
 the raw body bytes (no timestamp). Comparison is constant-time.
 
-> **Card lifecycle note:** card-data reveal (PAN / CVV) is a separate,
-> security-gated flow with its own re-auth + rate-limit + audit contract, so it
-> is intentionally not part of `client.cards`. The cards resource covers
-> create / get / list / balance plus the ownership-gated freeze / unfreeze /
-> terminate lifecycle actions.
+> **Card details:** `client.cards.reveal()` returns the full card number and
+> CVV. It asks for the user's password again (and a TOTP code if they have one
+> enrolled), and the API rate-limits and logs every call. The rest of
+> `client.cards` is create, get, list, balance, freeze, unfreeze and terminate.
 
 ## React hooks (`@takeal/cusfront-sdk/react`)
 
@@ -274,7 +291,7 @@ pnpm typecheck       # tsc --noEmit
 The OpenAPI snapshot lives at `openapi-snapshot.json` and is committed; refresh it from a running Takeal deployment with:
 
 ```sh
-curl https://api.your-deployment.example.com/api/docs/openapi.json > openapi-snapshot.json
+curl https://api.your-deployment.example.com/docs/openapi.json > openapi-snapshot.json
 pnpm refresh-types
 ```
 

package/dist/{http-BkZZZI8K.d.cts → http-BkCfOCR0.d.cts}

@@ -28,7 +28,10 @@ declare function inMemoryStore(): TokenStore;
  * Internal HTTP client. One per SDK instance; injected into each
  * resource. Responsibilities:
  *
- *  - Construct absolute URLs from `baseUrl` + path.
+ *  - Construct absolute URLs from `baseUrl` + API version + path.
+ *    Resources pass contract paths (`/me/deposits`); the `/v1` prefix is
+ *    added here, in one place. Only the deployment-level endpoints
+ *    (`/ready`, `/branding`, …) stay unversioned.
  *  - Set `Authorization: Bearer <jwt>` from the `TokenStore`.
  *  - Set `Content-Type: application/json` on bodies.
  *  - Parse JSON responses + map non-2xx to `ApiError`.

package/dist/{http-BkZZZI8K.d.ts → http-BkCfOCR0.d.ts}

@@ -28,7 +28,10 @@ declare function inMemoryStore(): TokenStore;
  * Internal HTTP client. One per SDK instance; injected into each
  * resource. Responsibilities:
  *
- *  - Construct absolute URLs from `baseUrl` + path.
+ *  - Construct absolute URLs from `baseUrl` + API version + path.
+ *    Resources pass contract paths (`/me/deposits`); the `/v1` prefix is
+ *    added here, in one place. Only the deployment-level endpoints
+ *    (`/ready`, `/branding`, …) stay unversioned.
  *  - Set `Authorization: Bearer <jwt>` from the `TokenStore`.
  *  - Set `Content-Type: application/json` on bodies.
  *  - Parse JSON responses + map non-2xx to `ApiError`.

package/dist/index.cjs

@@ -27,6 +27,15 @@ function isNetworkError(e) {
 }
 
 // src/http.ts
+var API_VERSION = "/v1";
+var UNVERSIONED = /* @__PURE__ */ new Set(["/health", "/ready", "/branding", "/favicon.ico"]);
+function versionedPath(path) {
+  const p = path.startsWith("/") ? path : `/${path}`;
+  const bare = p.split("?")[0];
+  if (UNVERSIONED.has(bare)) return p;
+  if (bare === API_VERSION || bare.startsWith(`${API_VERSION}/`)) return p;
+  return `${API_VERSION}${p}`;
+}
 var HttpClient = class {
   constructor(baseUrl, tokens, fetchImpl) {
     this.baseUrl = baseUrl;
@@ -83,8 +92,7 @@ var HttpClient = class {
   absolute(path) {
     if (path.startsWith("http://") || path.startsWith("https://")) return path;
     const base = this.baseUrl.replace(/\/+$/, "");
-    const tail = path.startsWith("/") ? path : `/${path}`;
-    return `${base}${tail}`;
+    return `${base}${versionedPath(path)}`;
   }
 };
 async function parseResponse(resp) {
@@ -149,6 +157,40 @@ var AuthResource = class {
     await Promise.resolve(this.tokens.set(resp.access_token));
     return resp;
   }
+  /** Create an end-user account and sign it in. The JWT is stored.
+   *  `wallet_currency` must be one the deployment offers; omit it to take
+   *  the deployment default (it can be switched later via `client.wallet`
+   *  while the wallet is empty).
+   *  Errors: 400 `validation` / `currency_not_allowed`, 409 email taken. */
+  async register(input) {
+    const resp = await this.http.post("/auth/register", {
+      body: input,
+      skipAuth: true
+    });
+    await Promise.resolve(this.tokens.set(resp.access_token));
+    return resp;
+  }
+  /** Finish a `totp_setup_required` login: send the first code from the
+   *  authenticator app. The JWT is stored. The response carries ten
+   *  one-time `backup_codes` that are never returned again, so show them to
+   *  the user right away and don't keep them on the device. */
+  async completeTotpSetup(input) {
+    const resp = await this.http.post("/auth/login/totp-setup", {
+      body: input,
+      skipAuth: true
+    });
+    await Promise.resolve(this.tokens.set(resp.access_token));
+    return resp;
+  }
+  /** Change the signed-in user's password. Every other session of the
+   *  account is signed out; this one stays valid.
+   *  Errors: 400 when the new password fails the policy, 401 when the
+   *  current one is wrong. */
+  async changePassword(input) {
+    return this.http.post("/auth/password", {
+      body: input
+    });
+  }
   /** Swap the 2FA method mid-flow. Resolves to `otp_sent` for
    *  telegram/email; for TOTP it short-circuits back to the challenge. */
   async switchMethod(input) {
@@ -185,10 +227,9 @@ var AuthResource = class {
   async me() {
     return this.http.get("/auth/me");
   }
-  /** Local sign-out. The SDK doesn't currently call a server-side
-   *  endpoint (the Takeal API issues stateless JWTs); clearing the
-   *  store is enough. Server-side session invalidation may land
-   *  with a future session table. */
+  /** Local sign-out: forgets the stored JWT. To end the session on the
+   *  server as well, revoke it first with `client.sessions.revoke(jti)`
+   *  (the current one is marked `current: true` in `client.sessions.list()`). */
   async signOut() {
     await Promise.resolve(this.tokens.clear());
   }
@@ -333,11 +374,12 @@ var BalanceResource = class {
     this.http = http;
   }
   /**
-   * Fetch the user's wallet balance for `currency` (ISO 4217, e.g. `"USD"`).
-   * Required — the ledger holds a separate balance per currency, so there is
-   * no "total" without one.
+   * Fetch the user's wallet balance. Omit `currency` for the wallet's own
+   * currency; pass an ISO 4217 code (e.g. `"USD"`) to read another one —
+   * the ledger holds a separate balance per currency.
    */
   async get(currency) {
+    if (!currency) return this.http.get("/me/balance");
     const q = new URLSearchParams({ currency }).toString();
     return this.http.get(`/me/balance?${q}`);
   }
@@ -354,6 +396,25 @@ var BrandingResource = class {
   }
 };
 
+// src/resources/wallet.ts
+var WalletResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Current wallet currency + the currencies the user may switch to. */
+  async get(opts = {}) {
+    return this.http.get("/me/wallet", { signal: opts.signal });
+  }
+  /**
+   * Switch the wallet currency. Fails with `409 wallet_not_empty` while any
+   * balance is non-zero, and `400 currency_not_allowed` for a currency the
+   * deployment does not offer.
+   */
+  async set(currency, opts = {}) {
+    return this.http.put("/me/wallet", { body: { currency }, signal: opts.signal });
+  }
+};
+
 // src/resources/blog.ts
 var BlogResource = class {
   constructor(http) {
@@ -407,6 +468,82 @@ var SubscriptionsResource = class {
   }
 };
 
+// src/resources/sessions.ts
+var SessionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** All live sessions of the account, this one included. */
+  async list() {
+    return this.http.get("/me/sessions");
+  }
+  /** Sign out one session. Works on the current one too; the stored JWT
+   *  stops working, so follow with `client.auth.signOut()`.
+   *  404 when the session is unknown or already signed out. */
+  async revoke(jti) {
+    await this.http.delete(`/me/sessions/${encodeURIComponent(jti)}`);
+  }
+  /** Sign out every session except this one. */
+  async revokeOthers() {
+    return this.http.post("/me/sessions/terminate-others");
+  }
+};
+
+// src/resources/push.ts
+var PushResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Whether the user is subscribed, plus the VAPID key to subscribe with. */
+  async status() {
+    return this.http.get("/me/push-subscription");
+  }
+  /** Store a subscription you created yourself.
+   *  409 `push_disabled` when the deployment has no VAPID keys. */
+  async save(input) {
+    return this.http.put("/me/push-subscription", { body: input });
+  }
+  /** Delete the stored subscription. Safe when nothing is stored. */
+  async remove() {
+    await this.http.delete("/me/push-subscription");
+  }
+  /** Subscribe this browser and store the subscription. Ask for
+   *  notification permission before calling. Throws when push isn't set up
+   *  on the deployment. */
+  async enable(registration) {
+    const { vapid_public_key } = await this.status();
+    if (!vapid_public_key) {
+      throw new Error("@takeal/cusfront-sdk: push notifications are not enabled on this deployment");
+    }
+    const sub = await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: base64UrlToBytes(vapid_public_key)
+    });
+    const json = sub.toJSON();
+    if (!json.endpoint || !json.keys?.p256dh || !json.keys.auth) {
+      throw new Error("@takeal/cusfront-sdk: the browser returned an incomplete push subscription");
+    }
+    return this.save({
+      endpoint: json.endpoint,
+      keys: { p256dh: json.keys.p256dh, auth: json.keys.auth }
+    });
+  }
+  /** Unsubscribe this browser and delete the stored subscription. */
+  async disable(registration) {
+    const sub = await registration.pushManager.getSubscription();
+    if (sub) await sub.unsubscribe();
+    await this.remove();
+  }
+};
+function base64UrlToBytes(input) {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  const bin = atob(padded);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
 // src/token-store.ts
 function defaultBrowserStore(key = "takeal_jwt") {
   const fallback = inMemoryStore();
@@ -455,9 +592,12 @@ function createClient(opts) {
     deposits: new DepositsResource(http),
     cards: new CardsResource(http),
     balance: new BalanceResource(http),
+    wallet: new WalletResource(http),
     branding: new BrandingResource(http),
     blog: new BlogResource(http),
-    subscriptions: new SubscriptionsResource(http)
+    subscriptions: new SubscriptionsResource(http),
+    sessions: new SessionsResource(http),
+    push: new PushResource(http)
   };
 }
 function pickDefaultStore() {