@takeal/cusfront-sdk 0.1.0

package/dist/react/index.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+var react = require('react');
+
+// src/react/context.ts
+var ClientContext = react.createContext(null);
+ClientContext.displayName = "CusfrontClientContext";
+function ClientProvider(props) {
+  return react.createElement(
+    ClientContext.Provider,
+    { value: props.client },
+    props.children
+  );
+}
+function useClient() {
+  const client = react.useContext(ClientContext);
+  if (client === null) {
+    throw new Error(
+      "@takeal/cusfront-sdk/react: useClient() (or a data hook) was called outside of a <ClientProvider>. Wrap your app in <ClientProvider client={createClient(...)}>."
+    );
+  }
+  return client;
+}
+function useAsyncResource(fetcher, deps) {
+  const [data, setData] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const [loading, setLoading] = react.useState(true);
+  const [nonce, setNonce] = react.useState(0);
+  const refetch = react.useCallback(async () => {
+    setNonce((n) => n + 1);
+  }, []);
+  react.useEffect(() => {
+    let cancelled = false;
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetcher(controller.signal).then((result) => {
+      if (cancelled) return;
+      setData(result);
+    }).catch((e) => {
+      if (cancelled) return;
+      if (controller.signal.aborted) return;
+      setError(e);
+    }).finally(() => {
+      if (cancelled) return;
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [...deps, nonce]);
+  return { data, error, loading, refetch };
+}
+function useMe() {
+  const client = useClient();
+  return useAsyncResource(() => client.auth.me(), [client]);
+}
+function useDeposits() {
+  const client = useClient();
+  return useAsyncResource(() => client.deposits.list(), [client]);
+}
+function useCards() {
+  const client = useClient();
+  return useAsyncResource(() => client.cards.list(), [client]);
+}
+function useBalance(currency) {
+  const client = useClient();
+  return useAsyncResource(
+    () => client.balance.get(currency),
+    [client, currency]
+  );
+}
+
+exports.ClientProvider = ClientProvider;
+exports.useBalance = useBalance;
+exports.useCards = useCards;
+exports.useClient = useClient;
+exports.useDeposits = useDeposits;
+exports.useMe = useMe;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.ts","../../src/react/hooks.ts"],"names":["createContext","createElement","useContext","useState","useCallback","useEffect"],"mappings":"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","file":"index.cjs","sourcesContent":["import { createContext, createElement, useContext, type ReactNode } from \"react\";\nimport type { CusfrontClient } from \"../index.js\";\n\n/**\n * React context carrying a single {@link CusfrontClient} instance.\n *\n * The client is created once by the consumer (via `createClient`) and\n * handed to {@link ClientProvider}; every hook in this entry point\n * reads it back through {@link useClient}. Keeping the client in\n * context (rather than module state) means multiple deployments /\n * brands can coexist in one tree, and the SDK ships no global\n * singleton.\n *\n * SSR-safe: nothing here touches `window` / `document`, and the\n * context default is `null` so a missing provider fails loudly\n * instead of silently using a stale client.\n */\nconst ClientContext = createContext<CusfrontClient | null>(null);\nClientContext.displayName = \"CusfrontClientContext\";\n\nexport interface ClientProviderProps {\n  /** The client built by `createClient(...)`. Create it once (e.g. in\n   *  a module-level `const` or a `useMemo`) and pass it here — do not\n   *  rebuild it on every render. */\n  client: CusfrontClient;\n  children?: ReactNode;\n}\n\n/**\n * Provides a {@link CusfrontClient} to the subtree. Place it near the\n * root of your app:\n *\n * ```tsx\n * const client = createClient({ baseUrl: \"https://api.example.com\" });\n *\n * <ClientProvider client={client}>\n *   <App />\n * </ClientProvider>\n * ```\n *\n * Authored with `createElement` rather than JSX so the SDK's build\n * needs no JSX transform configured.\n */\nexport function ClientProvider(props: ClientProviderProps) {\n  return createElement(\n    ClientContext.Provider,\n    { value: props.client },\n    props.children,\n  );\n}\n\n/**\n * Read the {@link CusfrontClient} from context. Throws a clear error\n * when used outside a {@link ClientProvider} — surfacing the missing\n * wiring at the call site instead of a confusing null-deref later.\n */\nexport function useClient(): CusfrontClient {\n  const client = useContext(ClientContext);\n  if (client === null) {\n    throw new Error(\n      \"@takeal/cusfront-sdk/react: useClient() (or a data hook) was called \" +\n        \"outside of a <ClientProvider>. Wrap your app in \" +\n        \"<ClientProvider client={createClient(...)}>.\",\n    );\n  }\n  return client;\n}\n","import { useCallback, useEffect, useState } from \"react\";\nimport { useClient } from \"./context.js\";\nimport type { User } from \"../resources/auth.js\";\nimport type { Deposit } from \"../resources/deposits.js\";\nimport type { Card } from \"../resources/cards.js\";\nimport type { Balance } from \"../resources/balance.js\";\n\n/**\n * Data-fetching hooks for the React entry point.\n *\n * Each hook wraps one resource call and exposes the same small,\n * predictable shape:\n *\n * ```ts\n * const { data, error, loading, refetch } = useDeposits();\n * ```\n *\n * Design notes:\n *  - Pure React (`useState` + `useEffect` + `useCallback`); no external\n *    data-fetching library, so the React entry stays tiny and the\n *    consumer keeps full control of caching.\n *  - The effect is cancellation-guarded: if the component unmounts (or\n *    the inputs change) before the request settles, the stale result is\n *    dropped instead of writing to an unmounted component.\n *  - SSR-safe: the fetch only runs inside `useEffect`, which never\n *    executes during server render.\n *  - `error` holds whatever the resource threw — typically the SDK's\n *    `ApiError` / `NetworkError` (branch with `isApiError` /\n *    `isNetworkError`).\n */\n\n/** Common return shape for every data hook. */\nexport interface AsyncState<T> {\n  /** The resolved value, or `null` before the first success / on error. */\n  data: T | null;\n  /** The thrown error, or `null` while loading / on success. */\n  error: unknown;\n  /** True from mount (and from each `refetch`) until the call settles. */\n  loading: boolean;\n  /** Re-run the underlying resource call. Returns a promise that\n   *  resolves once the refetch settles (useful for pull-to-refresh). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Internal engine shared by every public hook.\n *\n * `fetcher` is invoked on mount and whenever the caller's `deps`\n * change. It is handed an `AbortSignal` so resource calls that accept\n * one can cancel in-flight work; results are additionally gated behind\n * a `cancelled` flag so a late resolve never lands after teardown.\n *\n * The caller passes a stable `fetcher` (memoise it with `useCallback`)\n * — `useAsyncResource` does not re-subscribe on identity changes alone,\n * only on the explicit `deps` array, mirroring `useEffect` semantics.\n */\nfunction useAsyncResource<T>(\n  fetcher: (signal: AbortSignal) => Promise<T>,\n  deps: ReadonlyArray<unknown>,\n): AsyncState<T> {\n  const [data, setData] = useState<T | null>(null);\n  const [error, setError] = useState<unknown>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n  // Bumping this re-runs the effect on demand, reusing the exact same\n  // cancellation machinery a dependency change would.\n  const [nonce, setNonce] = useState(0);\n\n  const refetch = useCallback(async () => {\n    setNonce((n) => n + 1);\n  }, []);\n\n  useEffect(() => {\n    let cancelled = false;\n    const controller = new AbortController();\n\n    setLoading(true);\n    setError(null);\n\n    fetcher(controller.signal)\n      .then((result) => {\n        if (cancelled) return;\n        setData(result);\n      })\n      .catch((e: unknown) => {\n        if (cancelled) return;\n        // Ignore the abort we triggered ourselves on teardown.\n        if (controller.signal.aborted) return;\n        setError(e);\n      })\n      .finally(() => {\n        if (cancelled) return;\n        setLoading(false);\n      });\n\n    return () => {\n      cancelled = true;\n      controller.abort();\n    };\n    // `fetcher` is intentionally omitted from the dep list: callers\n    // memoise it, and re-runs are driven by `deps` + `nonce` so that an\n    // unstable inline fetcher can't cause an effect loop.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [...deps, nonce]);\n\n  return { data, error, loading, refetch };\n}\n\n/** Current authenticated user (`client.auth.me()`). 401 surfaces as\n *  the thrown `ApiError` in `error` — treat it as \"no session\". */\nexport function useMe(): AsyncState<User> {\n  const client = useClient();\n  return useAsyncResource<User>(() => client.auth.me(), [client]);\n}\n\n/** The caller's deposits, most recent first (`client.deposits.list()`). */\nexport function useDeposits(): AsyncState<Deposit[]> {\n  const client = useClient();\n  return useAsyncResource<Deposit[]>(() => client.deposits.list(), [client]);\n}\n\n/** The caller's cards, most recent first (`client.cards.list()`). */\nexport function useCards(): AsyncState<Card[]> {\n  const client = useClient();\n  return useAsyncResource<Card[]>(() => client.cards.list(), [client]);\n}\n\n/**\n * The user's wallet balance for one currency\n * (`client.balance.get(currency)`). Re-fetches when `currency`\n * changes.\n */\nexport function useBalance(currency: string): AsyncState<Balance> {\n  const client = useClient();\n  return useAsyncResource<Balance>(\n    () => client.balance.get(currency),\n    [client, currency],\n  );\n}\n"]}

package/dist/react/index.d.cts

@@ -0,0 +1,93 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { CusfrontClient } from '../index.cjs';
+import { User } from '../resources/auth.cjs';
+import { Deposit } from '../resources/deposits.cjs';
+import { Card } from '../resources/cards.cjs';
+import { Balance } from '../resources/balance.cjs';
+import '../http-BkZZZI8K.cjs';
+import '../resources/branding.cjs';
+import '../resources/blog.cjs';
+import '../resources/subscriptions.cjs';
+import '../customer-CoxPwe5o.cjs';
+
+interface ClientProviderProps {
+    /** The client built by `createClient(...)`. Create it once (e.g. in
+     *  a module-level `const` or a `useMemo`) and pass it here — do not
+     *  rebuild it on every render. */
+    client: CusfrontClient;
+    children?: ReactNode;
+}
+/**
+ * Provides a {@link CusfrontClient} to the subtree. Place it near the
+ * root of your app:
+ *
+ * ```tsx
+ * const client = createClient({ baseUrl: "https://api.example.com" });
+ *
+ * <ClientProvider client={client}>
+ *   <App />
+ * </ClientProvider>
+ * ```
+ *
+ * Authored with `createElement` rather than JSX so the SDK's build
+ * needs no JSX transform configured.
+ */
+declare function ClientProvider(props: ClientProviderProps): react.FunctionComponentElement<react.ProviderProps<CusfrontClient | null>>;
+/**
+ * Read the {@link CusfrontClient} from context. Throws a clear error
+ * when used outside a {@link ClientProvider} — surfacing the missing
+ * wiring at the call site instead of a confusing null-deref later.
+ */
+declare function useClient(): CusfrontClient;
+
+/**
+ * Data-fetching hooks for the React entry point.
+ *
+ * Each hook wraps one resource call and exposes the same small,
+ * predictable shape:
+ *
+ * ```ts
+ * const { data, error, loading, refetch } = useDeposits();
+ * ```
+ *
+ * Design notes:
+ *  - Pure React (`useState` + `useEffect` + `useCallback`); no external
+ *    data-fetching library, so the React entry stays tiny and the
+ *    consumer keeps full control of caching.
+ *  - The effect is cancellation-guarded: if the component unmounts (or
+ *    the inputs change) before the request settles, the stale result is
+ *    dropped instead of writing to an unmounted component.
+ *  - SSR-safe: the fetch only runs inside `useEffect`, which never
+ *    executes during server render.
+ *  - `error` holds whatever the resource threw — typically the SDK's
+ *    `ApiError` / `NetworkError` (branch with `isApiError` /
+ *    `isNetworkError`).
+ */
+/** Common return shape for every data hook. */
+interface AsyncState<T> {
+    /** The resolved value, or `null` before the first success / on error. */
+    data: T | null;
+    /** The thrown error, or `null` while loading / on success. */
+    error: unknown;
+    /** True from mount (and from each `refetch`) until the call settles. */
+    loading: boolean;
+    /** Re-run the underlying resource call. Returns a promise that
+     *  resolves once the refetch settles (useful for pull-to-refresh). */
+    refetch: () => Promise<void>;
+}
+/** Current authenticated user (`client.auth.me()`). 401 surfaces as
+ *  the thrown `ApiError` in `error` — treat it as "no session". */
+declare function useMe(): AsyncState<User>;
+/** The caller's deposits, most recent first (`client.deposits.list()`). */
+declare function useDeposits(): AsyncState<Deposit[]>;
+/** The caller's cards, most recent first (`client.cards.list()`). */
+declare function useCards(): AsyncState<Card[]>;
+/**
+ * The user's wallet balance for one currency
+ * (`client.balance.get(currency)`). Re-fetches when `currency`
+ * changes.
+ */
+declare function useBalance(currency: string): AsyncState<Balance>;
+
+export { type AsyncState, ClientProvider, type ClientProviderProps, useBalance, useCards, useClient, useDeposits, useMe };

package/dist/react/index.d.ts

@@ -0,0 +1,93 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { CusfrontClient } from '../index.js';
+import { User } from '../resources/auth.js';
+import { Deposit } from '../resources/deposits.js';
+import { Card } from '../resources/cards.js';
+import { Balance } from '../resources/balance.js';
+import '../http-BkZZZI8K.js';
+import '../resources/branding.js';
+import '../resources/blog.js';
+import '../resources/subscriptions.js';
+import '../customer-CoxPwe5o.js';
+
+interface ClientProviderProps {
+    /** The client built by `createClient(...)`. Create it once (e.g. in
+     *  a module-level `const` or a `useMemo`) and pass it here — do not
+     *  rebuild it on every render. */
+    client: CusfrontClient;
+    children?: ReactNode;
+}
+/**
+ * Provides a {@link CusfrontClient} to the subtree. Place it near the
+ * root of your app:
+ *
+ * ```tsx
+ * const client = createClient({ baseUrl: "https://api.example.com" });
+ *
+ * <ClientProvider client={client}>
+ *   <App />
+ * </ClientProvider>
+ * ```
+ *
+ * Authored with `createElement` rather than JSX so the SDK's build
+ * needs no JSX transform configured.
+ */
+declare function ClientProvider(props: ClientProviderProps): react.FunctionComponentElement<react.ProviderProps<CusfrontClient | null>>;
+/**
+ * Read the {@link CusfrontClient} from context. Throws a clear error
+ * when used outside a {@link ClientProvider} — surfacing the missing
+ * wiring at the call site instead of a confusing null-deref later.
+ */
+declare function useClient(): CusfrontClient;
+
+/**
+ * Data-fetching hooks for the React entry point.
+ *
+ * Each hook wraps one resource call and exposes the same small,
+ * predictable shape:
+ *
+ * ```ts
+ * const { data, error, loading, refetch } = useDeposits();
+ * ```
+ *
+ * Design notes:
+ *  - Pure React (`useState` + `useEffect` + `useCallback`); no external
+ *    data-fetching library, so the React entry stays tiny and the
+ *    consumer keeps full control of caching.
+ *  - The effect is cancellation-guarded: if the component unmounts (or
+ *    the inputs change) before the request settles, the stale result is
+ *    dropped instead of writing to an unmounted component.
+ *  - SSR-safe: the fetch only runs inside `useEffect`, which never
+ *    executes during server render.
+ *  - `error` holds whatever the resource threw — typically the SDK's
+ *    `ApiError` / `NetworkError` (branch with `isApiError` /
+ *    `isNetworkError`).
+ */
+/** Common return shape for every data hook. */
+interface AsyncState<T> {
+    /** The resolved value, or `null` before the first success / on error. */
+    data: T | null;
+    /** The thrown error, or `null` while loading / on success. */
+    error: unknown;
+    /** True from mount (and from each `refetch`) until the call settles. */
+    loading: boolean;
+    /** Re-run the underlying resource call. Returns a promise that
+     *  resolves once the refetch settles (useful for pull-to-refresh). */
+    refetch: () => Promise<void>;
+}
+/** Current authenticated user (`client.auth.me()`). 401 surfaces as
+ *  the thrown `ApiError` in `error` — treat it as "no session". */
+declare function useMe(): AsyncState<User>;
+/** The caller's deposits, most recent first (`client.deposits.list()`). */
+declare function useDeposits(): AsyncState<Deposit[]>;
+/** The caller's cards, most recent first (`client.cards.list()`). */
+declare function useCards(): AsyncState<Card[]>;
+/**
+ * The user's wallet balance for one currency
+ * (`client.balance.get(currency)`). Re-fetches when `currency`
+ * changes.
+ */
+declare function useBalance(currency: string): AsyncState<Balance>;
+
+export { type AsyncState, ClientProvider, type ClientProviderProps, useBalance, useCards, useClient, useDeposits, useMe };

package/dist/react/index.js

@@ -0,0 +1,75 @@
+import { createContext, createElement, useContext, useState, useCallback, useEffect } from 'react';
+
+// src/react/context.ts
+var ClientContext = createContext(null);
+ClientContext.displayName = "CusfrontClientContext";
+function ClientProvider(props) {
+  return createElement(
+    ClientContext.Provider,
+    { value: props.client },
+    props.children
+  );
+}
+function useClient() {
+  const client = useContext(ClientContext);
+  if (client === null) {
+    throw new Error(
+      "@takeal/cusfront-sdk/react: useClient() (or a data hook) was called outside of a <ClientProvider>. Wrap your app in <ClientProvider client={createClient(...)}>."
+    );
+  }
+  return client;
+}
+function useAsyncResource(fetcher, deps) {
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [nonce, setNonce] = useState(0);
+  const refetch = useCallback(async () => {
+    setNonce((n) => n + 1);
+  }, []);
+  useEffect(() => {
+    let cancelled = false;
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetcher(controller.signal).then((result) => {
+      if (cancelled) return;
+      setData(result);
+    }).catch((e) => {
+      if (cancelled) return;
+      if (controller.signal.aborted) return;
+      setError(e);
+    }).finally(() => {
+      if (cancelled) return;
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [...deps, nonce]);
+  return { data, error, loading, refetch };
+}
+function useMe() {
+  const client = useClient();
+  return useAsyncResource(() => client.auth.me(), [client]);
+}
+function useDeposits() {
+  const client = useClient();
+  return useAsyncResource(() => client.deposits.list(), [client]);
+}
+function useCards() {
+  const client = useClient();
+  return useAsyncResource(() => client.cards.list(), [client]);
+}
+function useBalance(currency) {
+  const client = useClient();
+  return useAsyncResource(
+    () => client.balance.get(currency),
+    [client, currency]
+  );
+}
+
+export { ClientProvider, useBalance, useCards, useClient, useDeposits, useMe };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.ts","../../src/react/hooks.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { createContext, createElement, useContext, type ReactNode } from \"react\";\nimport type { CusfrontClient } from \"../index.js\";\n\n/**\n * React context carrying a single {@link CusfrontClient} instance.\n *\n * The client is created once by the consumer (via `createClient`) and\n * handed to {@link ClientProvider}; every hook in this entry point\n * reads it back through {@link useClient}. Keeping the client in\n * context (rather than module state) means multiple deployments /\n * brands can coexist in one tree, and the SDK ships no global\n * singleton.\n *\n * SSR-safe: nothing here touches `window` / `document`, and the\n * context default is `null` so a missing provider fails loudly\n * instead of silently using a stale client.\n */\nconst ClientContext = createContext<CusfrontClient | null>(null);\nClientContext.displayName = \"CusfrontClientContext\";\n\nexport interface ClientProviderProps {\n  /** The client built by `createClient(...)`. Create it once (e.g. in\n   *  a module-level `const` or a `useMemo`) and pass it here — do not\n   *  rebuild it on every render. */\n  client: CusfrontClient;\n  children?: ReactNode;\n}\n\n/**\n * Provides a {@link CusfrontClient} to the subtree. Place it near the\n * root of your app:\n *\n * ```tsx\n * const client = createClient({ baseUrl: \"https://api.example.com\" });\n *\n * <ClientProvider client={client}>\n *   <App />\n * </ClientProvider>\n * ```\n *\n * Authored with `createElement` rather than JSX so the SDK's build\n * needs no JSX transform configured.\n */\nexport function ClientProvider(props: ClientProviderProps) {\n  return createElement(\n    ClientContext.Provider,\n    { value: props.client },\n    props.children,\n  );\n}\n\n/**\n * Read the {@link CusfrontClient} from context. Throws a clear error\n * when used outside a {@link ClientProvider} — surfacing the missing\n * wiring at the call site instead of a confusing null-deref later.\n */\nexport function useClient(): CusfrontClient {\n  const client = useContext(ClientContext);\n  if (client === null) {\n    throw new Error(\n      \"@takeal/cusfront-sdk/react: useClient() (or a data hook) was called \" +\n        \"outside of a <ClientProvider>. Wrap your app in \" +\n        \"<ClientProvider client={createClient(...)}>.\",\n    );\n  }\n  return client;\n}\n","import { useCallback, useEffect, useState } from \"react\";\nimport { useClient } from \"./context.js\";\nimport type { User } from \"../resources/auth.js\";\nimport type { Deposit } from \"../resources/deposits.js\";\nimport type { Card } from \"../resources/cards.js\";\nimport type { Balance } from \"../resources/balance.js\";\n\n/**\n * Data-fetching hooks for the React entry point.\n *\n * Each hook wraps one resource call and exposes the same small,\n * predictable shape:\n *\n * ```ts\n * const { data, error, loading, refetch } = useDeposits();\n * ```\n *\n * Design notes:\n *  - Pure React (`useState` + `useEffect` + `useCallback`); no external\n *    data-fetching library, so the React entry stays tiny and the\n *    consumer keeps full control of caching.\n *  - The effect is cancellation-guarded: if the component unmounts (or\n *    the inputs change) before the request settles, the stale result is\n *    dropped instead of writing to an unmounted component.\n *  - SSR-safe: the fetch only runs inside `useEffect`, which never\n *    executes during server render.\n *  - `error` holds whatever the resource threw — typically the SDK's\n *    `ApiError` / `NetworkError` (branch with `isApiError` /\n *    `isNetworkError`).\n */\n\n/** Common return shape for every data hook. */\nexport interface AsyncState<T> {\n  /** The resolved value, or `null` before the first success / on error. */\n  data: T | null;\n  /** The thrown error, or `null` while loading / on success. */\n  error: unknown;\n  /** True from mount (and from each `refetch`) until the call settles. */\n  loading: boolean;\n  /** Re-run the underlying resource call. Returns a promise that\n   *  resolves once the refetch settles (useful for pull-to-refresh). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Internal engine shared by every public hook.\n *\n * `fetcher` is invoked on mount and whenever the caller's `deps`\n * change. It is handed an `AbortSignal` so resource calls that accept\n * one can cancel in-flight work; results are additionally gated behind\n * a `cancelled` flag so a late resolve never lands after teardown.\n *\n * The caller passes a stable `fetcher` (memoise it with `useCallback`)\n * — `useAsyncResource` does not re-subscribe on identity changes alone,\n * only on the explicit `deps` array, mirroring `useEffect` semantics.\n */\nfunction useAsyncResource<T>(\n  fetcher: (signal: AbortSignal) => Promise<T>,\n  deps: ReadonlyArray<unknown>,\n): AsyncState<T> {\n  const [data, setData] = useState<T | null>(null);\n  const [error, setError] = useState<unknown>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n  // Bumping this re-runs the effect on demand, reusing the exact same\n  // cancellation machinery a dependency change would.\n  const [nonce, setNonce] = useState(0);\n\n  const refetch = useCallback(async () => {\n    setNonce((n) => n + 1);\n  }, []);\n\n  useEffect(() => {\n    let cancelled = false;\n    const controller = new AbortController();\n\n    setLoading(true);\n    setError(null);\n\n    fetcher(controller.signal)\n      .then((result) => {\n        if (cancelled) return;\n        setData(result);\n      })\n      .catch((e: unknown) => {\n        if (cancelled) return;\n        // Ignore the abort we triggered ourselves on teardown.\n        if (controller.signal.aborted) return;\n        setError(e);\n      })\n      .finally(() => {\n        if (cancelled) return;\n        setLoading(false);\n      });\n\n    return () => {\n      cancelled = true;\n      controller.abort();\n    };\n    // `fetcher` is intentionally omitted from the dep list: callers\n    // memoise it, and re-runs are driven by `deps` + `nonce` so that an\n    // unstable inline fetcher can't cause an effect loop.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [...deps, nonce]);\n\n  return { data, error, loading, refetch };\n}\n\n/** Current authenticated user (`client.auth.me()`). 401 surfaces as\n *  the thrown `ApiError` in `error` — treat it as \"no session\". */\nexport function useMe(): AsyncState<User> {\n  const client = useClient();\n  return useAsyncResource<User>(() => client.auth.me(), [client]);\n}\n\n/** The caller's deposits, most recent first (`client.deposits.list()`). */\nexport function useDeposits(): AsyncState<Deposit[]> {\n  const client = useClient();\n  return useAsyncResource<Deposit[]>(() => client.deposits.list(), [client]);\n}\n\n/** The caller's cards, most recent first (`client.cards.list()`). */\nexport function useCards(): AsyncState<Card[]> {\n  const client = useClient();\n  return useAsyncResource<Card[]>(() => client.cards.list(), [client]);\n}\n\n/**\n * The user's wallet balance for one currency\n * (`client.balance.get(currency)`). Re-fetches when `currency`\n * changes.\n */\nexport function useBalance(currency: string): AsyncState<Balance> {\n  const client = useClient();\n  return useAsyncResource<Balance>(\n    () => client.balance.get(currency),\n    [client, currency],\n  );\n}\n"]}

package/dist/resources/auth.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+// 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());
+  }
+};
+
+exports.AuthResource = AuthResource;
+//# sourceMappingURL=auth.cjs.map
+//# sourceMappingURL=auth.cjs.map

package/dist/resources/auth.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/resources/auth.ts"],"names":[],"mappings":";;;AAoGO,IAAM,eAAN,MAAmB;AAAA,EACxB,WAAA,CACmB,MACA,MAAA,EACjB;AAFiB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA,EAIH,MAAM,MAAM,KAAA,EAA2C;AACrD,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,IAAA,CAAK,KAAoB,aAAA,EAAe;AAAA,MAC9D,IAAA,EAAM,KAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACX,CAAA;AACD,IAAA,IAAI,IAAA,CAAK,UAAU,KAAA,EAAO;AACxB,MAAA,MAAM,QAAQ,OAAA,CAAQ,IAAA,CAAK,OAAO,GAAA,CAAI,IAAA,CAAK,YAAY,CAAC,CAAA;AAAA,IAC1D;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,MAAM,WAAW,KAAA,EAA4C;AAC3D,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,IAAA,CAAK,KAAgB,kBAAA,EAAoB;AAAA,MAC/D,IAAA,EAAM,KAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACX,CAAA;AACD,IAAA,MAAM,QAAQ,OAAA,CAAQ,IAAA,CAAK,OAAO,GAAA,CAAI,IAAA,CAAK,YAAY,CAAC,CAAA;AACxD,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,MAAM,UAAU,KAAA,EAA2C;AACzD,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,IAAA,CAAK,KAAgB,wBAAA,EAA0B;AAAA,MACrE,IAAA,EAAM,KAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACX,CAAA;AACD,IAAA,MAAM,QAAQ,OAAA,CAAQ,IAAA,CAAK,OAAO,GAAA,CAAI,IAAA,CAAK,YAAY,CAAC,CAAA;AACxD,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,MAAM,aAAa,KAAA,EAAoD;AACrE,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,IAAA,CAAsB,wBAAA,EAA0B;AAAA,MAC/D,IAAA,EAAM,KAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACX,CAAA;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,iBAAiB,KAAA,EAAiD;AACtE,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,IAAA,CAAK,KAAgB,yBAAA,EAA2B;AAAA,MACtE,IAAA,EAAM,EAAE,SAAA,EAAW,KAAA,CAAM,QAAA,EAAS;AAAA,MAClC,QAAA,EAAU;AAAA,KACX,CAAA;AACD,IAAA,MAAM,QAAQ,OAAA,CAAQ,IAAA,CAAK,OAAO,GAAA,CAAI,IAAA,CAAK,YAAY,CAAC,CAAA;AACxD,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,UAAU,KAAA,EAAyC;AACvD,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,IAAA,CAAW,WAAA,EAAa,EAAE,IAAA,EAAM,EAAE,KAAA,EAAO,KAAA,CAAM,KAAA,EAAM,EAAG,CAAA;AAAA,EAC3E;AAAA;AAAA;AAAA,EAIA,MAAM,EAAA,GAAoB;AACxB,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,GAAA,CAAU,UAAU,CAAA;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,OAAA,GAAyB;AAC7B,IAAA,MAAM,OAAA,CAAQ,OAAA,CAAQ,IAAA,CAAK,MAAA,CAAO,OAAO,CAAA;AAAA,EAC3C;AACF","file":"auth.cjs","sourcesContent":["import type { HttpClient } from \"../http.js\";\nimport type { TokenStore } from \"../token-store.js\";\n\n/**\n * Auth resource — `client.auth.*`.\n *\n * Covers the end-user-facing staged auth flow: password login\n * with optional TOTP/OTP step-up. The shape mirrors the responses\n * the Takeal API returns from `/auth/login`, `/auth/login/totp`,\n * `/auth/login/otp/verify`, `/auth/login/2fa/switch`, and `/auth/me`.\n *\n * The login methods stash the JWT in the configured `TokenStore` on\n * success so subsequent `client.*` calls authenticate automatically.\n * Step-up responses (TotpRequired / OtpSent) carry their own short-\n * lived challenge token which the caller passes to the next method\n * — those tokens DO NOT go through the TokenStore (they're not the\n * end-state JWT).\n */\n\nexport interface User {\n  id: string;\n  email: string;\n  role: string;\n  is_active: boolean;\n  /** True for users auto-provisioned via the Telegram Mini App who still hold\n   *  a synthetic placeholder email. The client should prompt for a real email\n   *  and attach it via `auth.linkEmail` — this flips the flag to false. */\n  email_pending?: boolean;\n  created_at: string;\n  updated_at: string;\n}\n\nexport interface LoginInput {\n  email: string;\n  password: string;\n}\n\n/** Discriminated union — `stage` is the discriminator. */\nexport type LoginResponse = JwtIssued | TotpRequired | TotpSetupRequired;\n\nexport interface JwtIssued {\n  stage: \"jwt\";\n  access_token: string;\n  expires_at: string;\n  user: User;\n  /** True iff the user's role grants `system.view_hub`.\n   *  Cusfront ignores this; the operator console uses it to gate `/dashboard`. */\n  hub_access?: boolean;\n}\n\nexport interface TotpRequired {\n  stage: \"totp_required\";\n  challenge_token: string;\n  expires_at: string;\n  /** Alternate second factors. Pick one with `/2fa/switch`. */\n  available_methods: AvailableMethod[];\n}\n\nexport interface TotpSetupRequired {\n  stage: \"totp_setup_required\";\n  challenge_token: string;\n  expires_at: string;\n  /** OTPAuth URI rendered as a QR by the consumer. */\n  otpauth_url: string;\n  /** Same secret base32-encoded — for manual entry alongside QR. */\n  secret_base32: string;\n}\n\nexport interface AvailableMethod {\n  kind: \"totp\" | \"telegram_otp\" | \"email_otp\";\n  /** Short user-facing hint, e.g. `\"Telegram (@user)\"` or `\"e****@example.com\"`. */\n  hint?: string;\n}\n\nexport interface TotpVerifyInput {\n  challenge_token: string;\n  /** 6-digit TOTP code OR `XXXX-XXXX` backup code. */\n  code: string;\n}\n\nexport interface OtpVerifyInput {\n  challenge_token: string;\n  /** 6-digit one-time code delivered via the selected channel. */\n  code: string;\n}\n\nexport interface SwitchMethodInput {\n  challenge_token: string;\n  method: AvailableMethod[\"kind\"];\n}\n\nexport interface OtpSentResponse {\n  stage: \"otp_sent\";\n  challenge_token: string;\n  expires_at: string;\n  method: AvailableMethod[\"kind\"];\n  hint?: string;\n  available_methods: AvailableMethod[];\n}\n\nexport class AuthResource {\n  constructor(\n    private readonly http: HttpClient,\n    private readonly tokens: TokenStore,\n  ) {}\n\n  /** Password-auth entry. May resolve to a JWT, or to a step-up\n   *  challenge that needs `verifyTotp` / `verifyOtp` next. */\n  async login(input: LoginInput): Promise<LoginResponse> {\n    const resp = await this.http.post<LoginResponse>(\"/auth/login\", {\n      body: input,\n      skipAuth: true,\n    });\n    if (resp.stage === \"jwt\") {\n      await Promise.resolve(this.tokens.set(resp.access_token));\n    }\n    return resp;\n  }\n\n  /** Verify a TOTP code (or XXXX-XXXX backup code) against a\n   *  `totp_required` challenge. On success the JWT is stored. */\n  async verifyTotp(input: TotpVerifyInput): Promise<JwtIssued> {\n    const resp = await this.http.post<JwtIssued>(\"/auth/login/totp\", {\n      body: input,\n      skipAuth: true,\n    });\n    await Promise.resolve(this.tokens.set(resp.access_token));\n    return resp;\n  }\n\n  /** Verify a 6-digit OTP code (Telegram / email) against an\n   *  `otp_sent` challenge. */\n  async verifyOtp(input: OtpVerifyInput): Promise<JwtIssued> {\n    const resp = await this.http.post<JwtIssued>(\"/auth/login/otp/verify\", {\n      body: input,\n      skipAuth: true,\n    });\n    await Promise.resolve(this.tokens.set(resp.access_token));\n    return resp;\n  }\n\n  /** Swap the 2FA method mid-flow. Resolves to `otp_sent` for\n   *  telegram/email; for TOTP it short-circuits back to the challenge. */\n  async switchMethod(input: SwitchMethodInput): Promise<OtpSentResponse> {\n    return this.http.post<OtpSentResponse>(\"/auth/login/2fa/switch\", {\n      body: input,\n      skipAuth: true,\n    });\n  }\n\n  /** Exchange a signed Telegram Mini App `initData` payload for a session\n   *  JWT. The server validates the initData HMAC against the deployment's bot\n   *  token, then find-or-creates the end-user. First-time Telegram users are\n   *  auto-provisioned with `user.email_pending === true` — prompt them for a\n   *  real email and call {@link linkEmail}. Stores the JWT on success.\n   *\n   *  Most consumers use the higher-level `fromInitData` / `fromTelegramWebApp`\n   *  helpers in `@takeal/cusfront-sdk/telegram`; reach for this directly when\n   *  you already hold a configured client. */\n  async exchangeTelegram(input: { initData: string }): Promise<JwtIssued> {\n    const resp = await this.http.post<JwtIssued>(\"/auth/telegram/exchange\", {\n      body: { init_data: input.initData },\n      skipAuth: true,\n    });\n    await Promise.resolve(this.tokens.set(resp.access_token));\n    return resp;\n  }\n\n  /** Attach a real email to the current user (and clear `email_pending`).\n   *  Used after a Telegram exchange to satisfy the email requirement; also\n   *  works for a password user changing their address. 409 if taken. */\n  async linkEmail(input: { email: string }): Promise<User> {\n    return this.http.post<User>(\"/me/email\", { body: { email: input.email } });\n  }\n\n  /** Current user — fails 401 when the stored JWT is expired or\n   *  missing. Useful as a \"do I have a session\" probe on app boot. */\n  async me(): Promise<User> {\n    return this.http.get<User>(\"/auth/me\");\n  }\n\n  /** Local sign-out. The SDK doesn't currently call a server-side\n   *  endpoint (the Takeal API issues stateless JWTs); clearing the\n   *  store is enough. Server-side session invalidation may land\n   *  with a future session table. */\n  async signOut(): Promise<void> {\n    await Promise.resolve(this.tokens.clear());\n  }\n}\n"]}

package/dist/resources/auth.d.cts

@@ -0,0 +1,132 @@
+import { H as HttpClient, T as TokenStore } from '../http-BkZZZI8K.cjs';
+
+/**
+ * Auth resource — `client.auth.*`.
+ *
+ * Covers the end-user-facing staged auth flow: password login
+ * with optional TOTP/OTP step-up. The shape mirrors the responses
+ * the Takeal API returns from `/auth/login`, `/auth/login/totp`,
+ * `/auth/login/otp/verify`, `/auth/login/2fa/switch`, and `/auth/me`.
+ *
+ * The login methods stash the JWT in the configured `TokenStore` on
+ * success so subsequent `client.*` calls authenticate automatically.
+ * Step-up responses (TotpRequired / OtpSent) carry their own short-
+ * lived challenge token which the caller passes to the next method
+ * — those tokens DO NOT go through the TokenStore (they're not the
+ * end-state JWT).
+ */
+interface User {
+    id: string;
+    email: string;
+    role: string;
+    is_active: boolean;
+    /** True for users auto-provisioned via the Telegram Mini App who still hold
+     *  a synthetic placeholder email. The client should prompt for a real email
+     *  and attach it via `auth.linkEmail` — this flips the flag to false. */
+    email_pending?: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface LoginInput {
+    email: string;
+    password: string;
+}
+/** Discriminated union — `stage` is the discriminator. */
+type LoginResponse = JwtIssued | TotpRequired | TotpSetupRequired;
+interface JwtIssued {
+    stage: "jwt";
+    access_token: string;
+    expires_at: string;
+    user: User;
+    /** True iff the user's role grants `system.view_hub`.
+     *  Cusfront ignores this; the operator console uses it to gate `/dashboard`. */
+    hub_access?: boolean;
+}
+interface TotpRequired {
+    stage: "totp_required";
+    challenge_token: string;
+    expires_at: string;
+    /** Alternate second factors. Pick one with `/2fa/switch`. */
+    available_methods: AvailableMethod[];
+}
+interface TotpSetupRequired {
+    stage: "totp_setup_required";
+    challenge_token: string;
+    expires_at: string;
+    /** OTPAuth URI rendered as a QR by the consumer. */
+    otpauth_url: string;
+    /** Same secret base32-encoded — for manual entry alongside QR. */
+    secret_base32: string;
+}
+interface AvailableMethod {
+    kind: "totp" | "telegram_otp" | "email_otp";
+    /** Short user-facing hint, e.g. `"Telegram (@user)"` or `"e****@example.com"`. */
+    hint?: string;
+}
+interface TotpVerifyInput {
+    challenge_token: string;
+    /** 6-digit TOTP code OR `XXXX-XXXX` backup code. */
+    code: string;
+}
+interface OtpVerifyInput {
+    challenge_token: string;
+    /** 6-digit one-time code delivered via the selected channel. */
+    code: string;
+}
+interface SwitchMethodInput {
+    challenge_token: string;
+    method: AvailableMethod["kind"];
+}
+interface OtpSentResponse {
+    stage: "otp_sent";
+    challenge_token: string;
+    expires_at: string;
+    method: AvailableMethod["kind"];
+    hint?: string;
+    available_methods: AvailableMethod[];
+}
+declare class AuthResource {
+    private readonly http;
+    private readonly tokens;
+    constructor(http: HttpClient, tokens: TokenStore);
+    /** Password-auth entry. May resolve to a JWT, or to a step-up
+     *  challenge that needs `verifyTotp` / `verifyOtp` next. */
+    login(input: LoginInput): Promise<LoginResponse>;
+    /** Verify a TOTP code (or XXXX-XXXX backup code) against a
+     *  `totp_required` challenge. On success the JWT is stored. */
+    verifyTotp(input: TotpVerifyInput): Promise<JwtIssued>;
+    /** Verify a 6-digit OTP code (Telegram / email) against an
+     *  `otp_sent` challenge. */
+    verifyOtp(input: OtpVerifyInput): Promise<JwtIssued>;
+    /** Swap the 2FA method mid-flow. Resolves to `otp_sent` for
+     *  telegram/email; for TOTP it short-circuits back to the challenge. */
+    switchMethod(input: SwitchMethodInput): Promise<OtpSentResponse>;
+    /** 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. */
+    exchangeTelegram(input: {
+        initData: string;
+    }): Promise<JwtIssued>;
+    /** 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. */
+    linkEmail(input: {
+        email: string;
+    }): Promise<User>;
+    /** Current user — fails 401 when the stored JWT is expired or
+     *  missing. Useful as a "do I have a session" probe on app boot. */
+    me(): Promise<User>;
+    /** 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. */
+    signOut(): Promise<void>;
+}
+
+export { AuthResource, type AvailableMethod, type JwtIssued, type LoginInput, type LoginResponse, type OtpSentResponse, type OtpVerifyInput, type SwitchMethodInput, type TotpRequired, type TotpSetupRequired, type TotpVerifyInput, type User };