@takeal/cusfront-sdk 0.1.0

package/dist/telegram.js

@@ -0,0 +1,550 @@
+// src/error.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, body) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.isApiError = true;
+    this.name = "ApiError";
+  }
+};
+var NetworkError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.isNetworkError = true;
+    this.name = "NetworkError";
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(baseUrl, tokens, fetchImpl) {
+    this.baseUrl = baseUrl;
+    this.tokens = tokens;
+    this.fetchImpl = fetchImpl;
+    if (!baseUrl) throw new Error("HttpClient: baseUrl is required");
+  }
+  async get(path, opts = {}) {
+    return this.request("GET", path, opts);
+  }
+  async post(path, opts = {}) {
+    return this.request("POST", path, opts);
+  }
+  async put(path, opts = {}) {
+    return this.request("PUT", path, opts);
+  }
+  async patch(path, opts = {}) {
+    return this.request("PATCH", path, opts);
+  }
+  async delete(path, opts = {}) {
+    return this.request("DELETE", path, opts);
+  }
+  async request(method, path, opts) {
+    const url = this.absolute(path);
+    const headers = {
+      Accept: "application/json"
+    };
+    if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+    if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    if (!opts.skipAuth) {
+      const token = await Promise.resolve(this.tokens.get());
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+    }
+    Object.assign(headers, opts.headers ?? {});
+    const init = {
+      method,
+      headers,
+      ...opts.signal ? { signal: opts.signal } : {}
+    };
+    if (opts.body !== void 0) {
+      init.body = typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body);
+    }
+    let resp;
+    try {
+      resp = await this.fetchImpl(url, init);
+    } catch (e) {
+      throw new NetworkError(
+        e instanceof Error ? e.message : "network error",
+        e
+      );
+    }
+    return parseResponse(resp);
+  }
+  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}`;
+  }
+};
+async function parseResponse(resp) {
+  const text = await resp.text();
+  let body;
+  if (text.length === 0) {
+    body = void 0;
+  } else {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = { raw: text };
+    }
+  }
+  if (!resp.ok) {
+    const errBody = body ?? {};
+    throw new ApiError(
+      resp.status,
+      errBody.code ?? `http_${resp.status}`,
+      errBody.message ?? resp.statusText ?? "request failed",
+      body
+    );
+  }
+  return body;
+}
+
+// src/resources/auth.ts
+var AuthResource = class {
+  constructor(http, tokens) {
+    this.http = http;
+    this.tokens = tokens;
+  }
+  /** Password-auth entry. May resolve to a JWT, or to a step-up
+   *  challenge that needs `verifyTotp` / `verifyOtp` next. */
+  async login(input) {
+    const resp = await this.http.post("/auth/login", {
+      body: input,
+      skipAuth: true
+    });
+    if (resp.stage === "jwt") {
+      await Promise.resolve(this.tokens.set(resp.access_token));
+    }
+    return resp;
+  }
+  /** Verify a TOTP code (or XXXX-XXXX backup code) against a
+   *  `totp_required` challenge. On success the JWT is stored. */
+  async verifyTotp(input) {
+    const resp = await this.http.post("/auth/login/totp", {
+      body: input,
+      skipAuth: true
+    });
+    await Promise.resolve(this.tokens.set(resp.access_token));
+    return resp;
+  }
+  /** Verify a 6-digit OTP code (Telegram / email) against an
+   *  `otp_sent` challenge. */
+  async verifyOtp(input) {
+    const resp = await this.http.post("/auth/login/otp/verify", {
+      body: input,
+      skipAuth: true
+    });
+    await Promise.resolve(this.tokens.set(resp.access_token));
+    return resp;
+  }
+  /** 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) {
+    return this.http.post("/auth/login/2fa/switch", {
+      body: input,
+      skipAuth: true
+    });
+  }
+  /** Exchange a signed Telegram Mini App `initData` payload for a session
+   *  JWT. The server validates the initData HMAC against the deployment's bot
+   *  token, then find-or-creates the end-user. First-time Telegram users are
+   *  auto-provisioned with `user.email_pending === true` — prompt them for a
+   *  real email and call {@link linkEmail}. Stores the JWT on success.
+   *
+   *  Most consumers use the higher-level `fromInitData` / `fromTelegramWebApp`
+   *  helpers in `@takeal/cusfront-sdk/telegram`; reach for this directly when
+   *  you already hold a configured client. */
+  async exchangeTelegram(input) {
+    const resp = await this.http.post("/auth/telegram/exchange", {
+      body: { init_data: input.initData },
+      skipAuth: true
+    });
+    await Promise.resolve(this.tokens.set(resp.access_token));
+    return resp;
+  }
+  /** Attach a real email to the current user (and clear `email_pending`).
+   *  Used after a Telegram exchange to satisfy the email requirement; also
+   *  works for a password user changing their address. 409 if taken. */
+  async linkEmail(input) {
+    return this.http.post("/me/email", { body: { email: input.email } });
+  }
+  /** Current user — fails 401 when the stored JWT is expired or
+   *  missing. Useful as a "do I have a session" probe on app boot. */
+  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. */
+  async signOut() {
+    await Promise.resolve(this.tokens.clear());
+  }
+};
+
+// src/resources/deposits.ts
+var DepositsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Initiate a top-up. Resolves to the freshly-created `Deposit`, whose
+   * `status` may already be `confirmed` (synchronous rails / mock) or
+   * `redirect_required` (3DS / APM — forward the user to `redirect_url`).
+   */
+  /**
+   * Price a cross-currency deposit BEFORE paying. The rate is locked
+   * server-side until `expires_at`; deposits in the local currency need no
+   * quote (the API answers 400 `no_quote_needed`).
+   */
+  async quote(input) {
+    return this.http.post("/me/deposits/quotes", { body: input });
+  }
+  async initiate(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.post("/me/deposits", {
+      body,
+      idempotencyKey
+    });
+  }
+  /** Fetch one deposit by id — the poll target while a redirect resolves. */
+  async get(id) {
+    return this.http.get(`/me/deposits/${encodeURIComponent(id)}`);
+  }
+  /** List the caller's deposits, most recent first. */
+  async list() {
+    return this.http.get("/me/deposits");
+  }
+  /**
+   * Refund a previously-confirmed deposit. Synchronous when the
+   * connector settles inline; otherwise the row stays `pending` and flips
+   * later via the inbound `deposit.refunded` event.
+   */
+  async refund(depositId, input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.post(
+      `/me/deposits/${encodeURIComponent(depositId)}/refunds`,
+      { body, idempotencyKey }
+    );
+  }
+};
+
+// src/resources/cards.ts
+var CardsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Issue a card backed by the user's wallet balance. Resolves to the new
+   * `Card`. On a ledger failure after provider creation, the Takeal API rolls the row
+   * to `failed` (never an orphaned active card); inspect `status` /
+   * `failure_reason` on the result.
+   */
+  async create(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.post("/me/cards", {
+      body,
+      idempotencyKey
+    });
+  }
+  /** Fetch one card by id. */
+  async get(id) {
+    return this.http.get(`/me/cards/${encodeURIComponent(id)}`);
+  }
+  /** List the caller's cards, most recent first. */
+  async list() {
+    return this.http.get("/me/cards");
+  }
+  /**
+   * Remaining balance of a prepaid card. `currency` is required by the Takeal API and
+   * forwarded as a query param.
+   */
+  async balance(id, currency) {
+    const q = new URLSearchParams({ currency }).toString();
+    return this.http.get(
+      `/me/cards/${encodeURIComponent(id)}/balance?${q}`
+    );
+  }
+  /**
+   * Freeze the caller's own card. Reversible via {@link unfreeze}. The optional
+   * `reason` is recorded on the audit trail. Resolves to the updated card.
+   * 404 if the card isn't the caller's; 501 if the issuer can't freeze.
+   */
+  async freeze(id, reason) {
+    return this.http.post(
+      `/me/cards/${encodeURIComponent(id)}/freeze`,
+      { body: { reason } }
+    );
+  }
+  /**
+   * Reveal the FULL PAN + CVV for the caller's own card. Re-auth gated
+   * (password, + TOTP when the user has it enrolled) and rate-limited
+   * server-side. The Takeal API never persists this data and marks the
+   * response no-store; the SDK returns it verbatim and holds nothing.
+   *
+   * **Consumer security duties** (the SDK can't enforce these for you):
+   * keep the result in volatile memory only, never write it to
+   * localStorage / logs, and clear it within `expires_in_seconds`.
+   *
+   * 401 bad re-auth · 403 not your card · 429 rate-limited · 501 connector
+   * has no sensitive-data endpoint · 503 provider error.
+   */
+  async reveal(id, input) {
+    return this.http.post(
+      `/me/cards/${encodeURIComponent(id)}/reveal`,
+      { body: { password: input.password, totp_code: input.totpCode } }
+    );
+  }
+  /** Unfreeze a previously-frozen card. Idempotent on an already-active card. */
+  async unfreeze(id) {
+    return this.http.post(
+      `/me/cards/${encodeURIComponent(id)}/unfreeze`,
+      { body: {} }
+    );
+  }
+  /**
+   * Terminate the caller's own card. **One-way** — a terminated card cannot be
+   * reactivated. The optional `reason` is audited. Idempotent on an
+   * already-terminated card.
+   */
+  async terminate(id, reason) {
+    return this.http.post(
+      `/me/cards/${encodeURIComponent(id)}/terminate`,
+      { body: { reason } }
+    );
+  }
+};
+
+// src/resources/balance.ts
+var BalanceResource = class {
+  constructor(http) {
+    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.
+   */
+  async get(currency) {
+    const q = new URLSearchParams({ currency }).toString();
+    return this.http.get(`/me/balance?${q}`);
+  }
+};
+
+// src/resources/branding.ts
+var BrandingResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Fetch the deployment's public brand config. Safe to call before login. */
+  async get(opts = {}) {
+    return this.http.get("/branding", { skipAuth: true, signal: opts.signal });
+  }
+};
+
+// src/resources/blog.ts
+var BlogResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Published posts, newest first. No authentication required. */
+  async list(input = {}) {
+    const q = new URLSearchParams();
+    if (input.page) q.set("page", String(input.page));
+    if (input.perPage) q.set("per_page", String(input.perPage));
+    if (input.tag) q.set("tag", input.tag);
+    if (input.locale) q.set("locale", input.locale);
+    const qs = q.toString();
+    return this.http.get(`/blog/posts${qs ? `?${qs}` : ""}`, {
+      skipAuth: true
+    });
+  }
+  /** One post by slug. No authentication required. */
+  async get(slug) {
+    return this.http.get(`/blog/posts/${encodeURIComponent(slug)}`, {
+      skipAuth: true
+    });
+  }
+  /**
+   * Absolute URL for an image path returned inside a post (`cover_url`, or an
+   * image block's `url`). Handy when the app renders on a different origin
+   * than the API.
+   */
+  imageUrl(baseUrl, path) {
+    if (/^https?:\/\//i.test(path)) return path;
+    return `${baseUrl.replace(/\/$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
+  }
+};
+
+// src/resources/subscriptions.ts
+var SubscriptionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async get() {
+    return this.http.get("/me/subscriptions");
+  }
+  /**
+   * Replace the whole set — this is a PUT, not a merge. Pass `[]` to opt out
+   * of everything.
+   */
+  async set(channels) {
+    return this.http.put("/me/subscriptions", {
+      body: { channels }
+    });
+  }
+};
+
+// src/token-store.ts
+function defaultBrowserStore(key = "takeal_jwt") {
+  const fallback = inMemoryStore();
+  let usable = false;
+  try {
+    if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+      const ls2 = globalThis.localStorage;
+      const probe = "__takeal_probe__";
+      ls2.setItem(probe, "1");
+      ls2.removeItem(probe);
+      usable = true;
+    }
+  } catch {
+    usable = false;
+  }
+  if (!usable) return fallback;
+  const ls = globalThis.localStorage;
+  return {
+    get: () => ls.getItem(key),
+    set: (token) => ls.setItem(key, token),
+    clear: () => ls.removeItem(key)
+  };
+}
+function inMemoryStore() {
+  let value = null;
+  return {
+    get: () => value,
+    set: (token) => {
+      value = token;
+    },
+    clear: () => {
+      value = null;
+    }
+  };
+}
+
+// src/index.ts
+function createClient(opts) {
+  const tokens = opts.tokenStore ?? pickDefaultStore();
+  const fetchImpl = opts.fetch ?? defaultFetch();
+  const http = new HttpClient(opts.baseUrl, tokens, fetchImpl);
+  return {
+    brand: opts.brand,
+    tokens,
+    auth: new AuthResource(http, tokens),
+    deposits: new DepositsResource(http),
+    cards: new CardsResource(http),
+    balance: new BalanceResource(http),
+    branding: new BrandingResource(http),
+    blog: new BlogResource(http),
+    subscriptions: new SubscriptionsResource(http)
+  };
+}
+function pickDefaultStore() {
+  if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+    return defaultBrowserStore();
+  }
+  return inMemoryStore();
+}
+function defaultFetch() {
+  if (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+  throw new Error(
+    "@takeal/cusfront-sdk: native fetch is not available in this runtime. Pass a polyfill via createClient({ fetch })."
+  );
+}
+
+// src/telegram.ts
+var InitDataError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "InitDataError";
+  }
+};
+function parseInitData(initData) {
+  const params = {};
+  const sp = new URLSearchParams(initData);
+  for (const [k, v] of sp.entries()) params[k] = v;
+  let user;
+  if (params.user) {
+    try {
+      user = JSON.parse(params.user);
+    } catch {
+      user = void 0;
+    }
+  }
+  const authDateRaw = params.auth_date;
+  const auth_date = authDateRaw && /^\d+$/.test(authDateRaw) ? Number(authDateRaw) : void 0;
+  return {
+    raw: initData,
+    params,
+    ...params.hash ? { hash: params.hash } : {},
+    ...auth_date !== void 0 ? { auth_date } : {},
+    ...params.query_id ? { query_id: params.query_id } : {},
+    ...user ? { user } : {}
+  };
+}
+function assertWellFormed(initData, opts = {}) {
+  if (!initData) throw new InitDataError("initData is empty", "empty");
+  const parsed = parseInitData(initData);
+  if (!parsed.hash)
+    throw new InitDataError("initData is missing `hash`", "missing_hash");
+  if (parsed.auth_date === void 0)
+    throw new InitDataError(
+      "initData is missing a valid `auth_date`",
+      "missing_auth_date"
+    );
+  if (!parsed.user || typeof parsed.user.id !== "number")
+    throw new InitDataError(
+      "initData is missing a valid `user`",
+      "bad_user"
+    );
+  const maxAge = opts.maxAgeSeconds ?? 86400;
+  if (maxAge > 0) {
+    const now = opts.nowUnix ?? Math.floor(Date.now() / 1e3);
+    if (now - parsed.auth_date > maxAge)
+      throw new InitDataError(
+        "initData is stale (auth_date older than the freshness window)",
+        "stale"
+      );
+  }
+  return parsed;
+}
+async function fromInitData(initData, config, opts = {}) {
+  if (!opts.skipWellFormedCheck) assertWellFormed(initData, opts);
+  const client = createClient(config);
+  await client.auth.exchangeTelegram({ initData });
+  return client;
+}
+function readWebAppInitData() {
+  const tg = globalThis.Telegram;
+  const data = tg?.WebApp?.initData;
+  return data && data.length > 0 ? data : null;
+}
+async function fromTelegramWebApp(config, opts = {}) {
+  const initData = readWebAppInitData();
+  if (!initData)
+    throw new InitDataError(
+      "not running inside a Telegram Mini App (window.Telegram.WebApp.initData is empty)",
+      "empty"
+    );
+  return fromInitData(initData, config, opts);
+}
+
+export { InitDataError, assertWellFormed, fromInitData, fromTelegramWebApp, parseInitData, readWebAppInitData };
+//# sourceMappingURL=telegram.js.map
+//# sourceMappingURL=telegram.js.map