@layers/amba-react 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# @layers/amba-react
+
+React hooks for [amba](https://amba.dev). Companion to `@layers/amba-web`.
+
+## Install
+
+```bash
+pnpm add @layers/amba-react @layers/amba-web react
+```
+
+## Quickstart
+
+```tsx
+import { Amba } from "@layers/amba-web";
+import {
+  AmbaProvider,
+  useUser,
+  useCollection,
+  useFlag,
+} from "@layers/amba-react";
+
+// Configure at app start (before render)
+await Amba.configure({ apiKey: import.meta.env.VITE_AMBA_API_KEY });
+
+function App() {
+  return (
+    <AmbaProvider>
+      <Inner />
+    </AmbaProvider>
+  );
+}
+
+function Inner() {
+  const { user, isAuthenticated } = useUser();
+  const { data: todos, loading } = useCollection<{ id: string; title: string }>(
+    "todos",
+  );
+  const newUi = useFlag("new_ui");
+
+  if (!isAuthenticated) return <SignIn />;
+  if (loading) return <Spinner />;
+  return (
+    <div className={newUi ? "new-ui" : "classic"}>
+      <p>Welcome {user?.display_name}</p>
+      <ul>
+        {todos?.map((t) => (
+          <li key={t.id}>{t.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Hooks
+
+| Hook                            | Returns                                                  |
+| ------------------------------- | -------------------------------------------------------- |
+| `useAmba()`                     | Raw SDK handle.                                          |
+| `useUser()`                     | `{ user, isAuthenticated, loading }`.                    |
+| `useCollection(name, options)`  | `{ data, loading, error, refetch, response }`.           |
+| `useFlag(name)`                 | `boolean`.                                               |
+| `useVariant(name)`              | `string \| null` (multi-variant flag assignment).        |
+| `useEntitlement(name)`          | `boolean` — true if user has the entitlement.            |
+| `useTrackOnMount(event, props)` | Side-effect — tracks an event when the component mounts. |
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+import * as _layers_amba_web0 from "@layers/amba-web";
+import { FindOptions, FindResponse, FlagAssignment, User } from "@layers/amba-web";
+import * as react0 from "react";
+import { ReactNode } from "react";
+
+//#region src/index.d.ts
+
+interface AmbaContextValue {
+  /**
+   * Bump this counter to force a re-render of hooks that read SDK state
+   * (`useUser`, `useIsAuthenticated`, …). Bumped on every auth state
+   * change (sign-in / sign-out / refresh).
+   */
+  version: number;
+  bumpVersion: () => void;
+}
+/**
+ * Wraps your app and provides reactive subscriptions to the amba SDK.
+ *
+ * Call `Amba.configure(...)` BEFORE rendering this provider. It does not
+ * configure the SDK itself — it just plugs the React tree into the SDK's
+ * state-change channel.
+ */
+declare function AmbaProvider({
+  children
+}: {
+  children: ReactNode;
+}): react0.FunctionComponentElement<react0.ProviderProps<AmbaContextValue | null>>;
+/**
+ * Returns the underlying SDK handle (`Amba`). Useful for one-off calls
+ * that don't have a dedicated hook.
+ */
+declare function useAmba(): {
+  configure: (config: _layers_amba_web0.AmbaConfig) => Promise<void>;
+  readonly anonymousId: string;
+  readonly appUserId: string | undefined;
+  readonly isAuthenticated: boolean;
+  setDebug: (enabled: boolean) => void;
+  events: {
+    track: (event: string, properties?: Record<string, unknown>) => Promise<void>;
+  };
+  auth: {
+    signInAnonymously: () => Promise<_layers_amba_web0.AuthResult>;
+    signInWithEmail: (email: string, password: string) => Promise<_layers_amba_web0.AuthResult>;
+    signUpWithEmail: (email: string, password: string) => Promise<_layers_amba_web0.AuthResult>;
+    signInWithSocial: (provider: _layers_amba_web0.SocialProvider, idToken: string) => Promise<_layers_amba_web0.AuthResult>;
+    signOut: (rotateAnonymousId?: boolean) => Promise<void>;
+    refresh: () => Promise<_layers_amba_web0.AuthResult>;
+    me: () => Promise<User>;
+    getSession: () => Promise<_layers_amba_web0.Session | null>;
+    getAnonymousId: () => Promise<string>;
+    onAuthStateChange: (cb: (session: _layers_amba_web0.Session | null) => void) => (() => void);
+  };
+  collections: {
+    find: <T = unknown>(name: string, options?: FindOptions) => Promise<FindResponse<T>>;
+    findOne: <T = unknown>(name: string, id: string) => Promise<T>;
+    insert: <T = unknown>(name: string, row: Record<string, unknown>) => Promise<T>;
+    update: <T = unknown>(name: string, id: string, set: Record<string, unknown>) => Promise<T>;
+    delete: (name: string, id: string) => Promise<{
+      data: {
+        deleted: boolean;
+      };
+    }>;
+    where: {
+      eq: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      ne: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      gt: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      gte: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      lt: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      lte: (column: string, value: _layers_amba_web0.FilterValue) => _layers_amba_web0.Filter;
+      in: (column: string, values: _layers_amba_web0.FilterValue[]) => _layers_amba_web0.Filter;
+      notIn: (column: string, values: _layers_amba_web0.FilterValue[]) => _layers_amba_web0.Filter;
+      like: (column: string, pattern: string) => _layers_amba_web0.Filter;
+      ilike: (column: string, pattern: string) => _layers_amba_web0.Filter;
+      isNull: (column: string) => _layers_amba_web0.Filter;
+      isNotNull: (column: string) => _layers_amba_web0.Filter;
+      and: (...filters: _layers_amba_web0.Filter[]) => _layers_amba_web0.Filter;
+      or: (...filters: _layers_amba_web0.Filter[]) => _layers_amba_web0.Filter;
+      not: (filter: _layers_amba_web0.Filter) => _layers_amba_web0.Filter;
+    };
+  };
+  storage: {
+    presign: (params: {
+      bucket: string;
+      filename: string;
+      mimeType: string;
+      sizeBytes: number;
+      retentionDays?: number;
+    }) => Promise<_layers_amba_web0.PresignData>;
+    upload: (params: {
+      bucket: string;
+      file: File | Blob;
+      filename?: string;
+      retentionDays?: number;
+    }) => Promise<_layers_amba_web0.MediaAsset>;
+  };
+  push: {
+    register: (token: string, platform: _layers_amba_web0.PushPlatform, bundleId?: string) => Promise<_layers_amba_web0.PushToken>;
+    unregister: (token: string) => Promise<void>;
+    getTokens: () => Promise<_layers_amba_web0.PushToken[]>;
+    subscribe: (topic: string) => Promise<void>;
+    unsubscribe: (topic: string) => Promise<void>;
+  };
+  entitlements: {
+    list: () => Promise<_layers_amba_web0.UserEntitlement[]>;
+    has: (name: string) => Promise<boolean>;
+  };
+  ai: {
+    anthropic: {
+      messages: {
+        create: (request: _layers_amba_web0.AiMessageRequest) => Promise<_layers_amba_web0.AiMessageResponse>;
+      };
+    };
+  };
+  config: {
+    fetch: () => Promise<_layers_amba_web0.ConfigBundle>;
+  };
+  flags: {
+    fetch: () => Promise<FlagAssignment[]>;
+  };
+  achievements: {
+    getAll: () => Promise<_layers_amba_web0.Achievement[]>;
+    getProgress: () => Promise<_layers_amba_web0.AchievementProgress[]>;
+  };
+  challenges: {
+    getActive: () => Promise<_layers_amba_web0.Challenge[]>;
+    get: (id: string) => Promise<_layers_amba_web0.Challenge>;
+    getProgress: (id: string) => Promise<_layers_amba_web0.ChallengeProgress>;
+    claim: (id: string) => Promise<_layers_amba_web0.ChallengeProgress>;
+  };
+  currencies: {
+    getBalance: () => Promise<_layers_amba_web0.CurrencyBalance[]>;
+    getTransactions: (currencyKey: string) => Promise<_layers_amba_web0.CurrencyTransaction[]>;
+  };
+  inventory: {
+    getItems: () => Promise<_layers_amba_web0.InventoryItem[]>;
+    getItem: (id: string) => Promise<_layers_amba_web0.InventoryItem>;
+    purchase: (request: _layers_amba_web0.PurchaseRequest) => Promise<_layers_amba_web0.InventoryItem>;
+    consume: (request: _layers_amba_web0.ConsumeRequest) => Promise<_layers_amba_web0.InventoryItem>;
+  };
+  leaderboards: {
+    get: (key: string) => Promise<_layers_amba_web0.Leaderboard>;
+    getEntries: (key: string, limit?: number) => Promise<_layers_amba_web0.LeaderboardEntry[]>;
+    getMyRank: (key: string) => Promise<_layers_amba_web0.LeaderboardEntry>;
+  };
+  stores: {
+    list: () => Promise<_layers_amba_web0.Store[]>;
+    getPurchaseOptions: (storeKey: string) => Promise<_layers_amba_web0.PurchaseOption[]>;
+    purchase: (storeKey: string, purchaseOptionId: string, receipt: unknown) => Promise<_layers_amba_web0.PurchaseResult>;
+  };
+  xp: {
+    getBalance: () => Promise<_layers_amba_web0.XpBalance>;
+    getHistory: (limit?: number) => Promise<_layers_amba_web0.XpTransaction[]>;
+    claim: (grantKey: string) => Promise<_layers_amba_web0.XpTransaction>;
+  };
+  streaks: {
+    getAll: () => Promise<_layers_amba_web0.Streak[]>;
+    qualify: (streakKey: string) => Promise<_layers_amba_web0.Streak>;
+  };
+  feeds: {
+    getActivity: (feed?: string, cursor?: string) => Promise<_layers_amba_web0.FeedResponse>;
+  };
+  friends: {
+    getList: () => Promise<_layers_amba_web0.Friendship[]>;
+    getFriends: () => Promise<_layers_amba_web0.Friendship[]>;
+    blockUser: (userId: string) => Promise<_layers_amba_web0.Friendship>;
+    unblockUser: (userId: string) => Promise<void>;
+    removeBlock: (friendshipId: string) => Promise<void>;
+  };
+  groups: {
+    create: (params: _layers_amba_web0.GroupCreate) => Promise<_layers_amba_web0.Group>;
+    get: (id: string) => Promise<_layers_amba_web0.Group>;
+    update: (id: string, patch: _layers_amba_web0.GroupUpdate) => Promise<_layers_amba_web0.Group>;
+    delete: (id: string) => Promise<void>;
+    getMembers: (id: string) => Promise<_layers_amba_web0.GroupMember[]>;
+    join: (id: string) => Promise<_layers_amba_web0.GroupMember>;
+    leave: (id: string) => Promise<void>;
+    invite: (id: string, userId: string) => Promise<_layers_amba_web0.GroupMember>;
+  };
+  messaging: {
+    getConversations: () => Promise<_layers_amba_web0.Conversation[]>;
+    getMessage: (id: string) => Promise<_layers_amba_web0.Message>;
+    sendMessage: (request: _layers_amba_web0.SendMessageRequest) => Promise<_layers_amba_web0.Message>;
+  };
+  moderation: {
+    reportUser: (request: _layers_amba_web0.ReportRequest) => Promise<_layers_amba_web0.Report>;
+    reportContent: (request: _layers_amba_web0.ReportRequest) => Promise<_layers_amba_web0.Report>;
+    getReportStatus: (id: string) => Promise<_layers_amba_web0.Report>;
+  };
+  reviews: {
+    list: (targetType: string, targetId: string) => Promise<_layers_amba_web0.Review[]>;
+    create: (params: _layers_amba_web0.ReviewCreate) => Promise<_layers_amba_web0.Review>;
+    update: (id: string, patch: _layers_amba_web0.ReviewUpdate) => Promise<_layers_amba_web0.Review>;
+    delete: (id: string) => Promise<void>;
+  };
+  roles: {
+    getMyRoles: () => Promise<_layers_amba_web0.Role[]>;
+    hasPermission: (permission: string) => Promise<boolean>;
+  };
+  referrals: {
+    getReferralCode: () => Promise<_layers_amba_web0.ReferralCode>;
+    claimReferral: (code: string) => Promise<_layers_amba_web0.ReferralClaim>;
+    create: (code?: string, maxUses?: number) => Promise<_layers_amba_web0.ReferralCode>;
+  };
+  catalog: {
+    list: () => Promise<_layers_amba_web0.CatalogItem[]>;
+  };
+  content: {
+    getToday: (channel?: string) => Promise<_layers_amba_web0.ContentItem | null>;
+    getLibrary: (channel?: string, options?: {
+      limit?: number;
+      cursor?: string;
+    }) => Promise<_layers_amba_web0.ContentItem[]>;
+    getItem: (id: string) => Promise<_layers_amba_web0.ContentItem>;
+    updateItem: (id: string, state: unknown) => Promise<_layers_amba_web0.ContentItem>;
+    createItem: (channel: string, item: unknown) => Promise<_layers_amba_web0.ContentItem>;
+  };
+  deepLinks: {
+    get: (shortCode: string) => Promise<_layers_amba_web0.DeepLink>;
+    create: (params: _layers_amba_web0.DeepLinkCreate) => Promise<_layers_amba_web0.DeepLink>;
+  };
+  onboarding: {
+    getStatus: () => Promise<_layers_amba_web0.OnboardingStatus>;
+    nextStep: (payload: unknown) => Promise<_layers_amba_web0.OnboardingStatus>;
+    skipStep: () => Promise<_layers_amba_web0.OnboardingStatus>;
+    complete: () => Promise<_layers_amba_web0.OnboardingStatus>;
+  };
+};
+/**
+ * Returns `{ user, isAuthenticated }` for the currently-signed-in user.
+ * `user` is `null` until `auth.me()` resolves; the hook auto-fetches when
+ * the SDK is authenticated and refreshes on auth-state changes.
+ */
+declare function useUser(): {
+  user: User | null;
+  isAuthenticated: boolean;
+  loading: boolean;
+};
+/**
+ * Reactive subscription to a collection. Re-fetches when `options` or
+ * `version` changes. Includes a `refetch` callback for manual refresh.
+ */
+declare function useCollection<T = unknown>(name: string, options?: FindOptions): {
+  data: T[] | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+  response: FindResponse<T> | null;
+};
+/**
+ * Returns true if the named feature flag is enabled.
+ * Fetches the flag set once on mount; subsequent calls read from cache.
+ */
+declare function useFlag(name: string): boolean;
+/**
+ * Returns the variant assignment for a multi-variant flag, or `null`
+ * if unset / not loaded.
+ */
+declare function useVariant(name: string): string | null;
+/**
+ * Returns true if the user has the named entitlement (active subscription
+ * or one-time purchase grant). Defaults to false on loading / error —
+ * safe for paywall gating.
+ */
+declare function useEntitlement(name: string): boolean;
+/**
+ * Tracks an event when this hook mounts. Useful for page-view tracking:
+ * `useTrackOnMount('page_viewed', { path: '/home' })`.
+ */
+declare function useTrackOnMount(event: string, properties?: Record<string, unknown>): void;
+declare const SDK_VERSION = "0.1.0";
+//#endregion
+export { AmbaProvider, SDK_VERSION, useAmba, useCollection, useEntitlement, useFlag, useTrackOnMount, useUser, useVariant };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,177 @@
+import { Amba } from "@layers/amba-web";
+import { createContext, createElement, useCallback, useContext, useEffect, useState } from "react";
+
+//#region src/index.ts
+const AmbaContext = createContext(null);
+/**
+* Wraps your app and provides reactive subscriptions to the amba SDK.
+*
+* Call `Amba.configure(...)` BEFORE rendering this provider. It does not
+* configure the SDK itself — it just plugs the React tree into the SDK's
+* state-change channel.
+*/
+function AmbaProvider({ children }) {
+	const [version, setVersion] = useState(0);
+	const bumpVersion = useCallback(() => setVersion((v) => v + 1), []);
+	return createElement(AmbaContext.Provider, { value: {
+		version,
+		bumpVersion
+	} }, children);
+}
+function useAmbaContext() {
+	const ctx = useContext(AmbaContext);
+	if (!ctx) throw new Error("@layers/amba-react: hooks must be used inside <AmbaProvider>. Wrap your app with <AmbaProvider> after calling Amba.configure()");
+	return ctx;
+}
+/**
+* Returns the underlying SDK handle (`Amba`). Useful for one-off calls
+* that don't have a dedicated hook.
+*/
+function useAmba() {
+	useAmbaContext();
+	return Amba;
+}
+/**
+* Returns `{ user, isAuthenticated }` for the currently-signed-in user.
+* `user` is `null` until `auth.me()` resolves; the hook auto-fetches when
+* the SDK is authenticated and refreshes on auth-state changes.
+*/
+function useUser() {
+	const { version } = useAmbaContext();
+	const [user, setUser] = useState(null);
+	const [loading, setLoading] = useState(false);
+	useEffect(() => {
+		if (!Amba.isAuthenticated) {
+			setUser(null);
+			return;
+		}
+		let cancelled = false;
+		setLoading(true);
+		Amba.auth.me().then((u) => {
+			if (!cancelled) setUser(u);
+		}).catch(() => {
+			if (!cancelled) setUser(null);
+		}).finally(() => {
+			if (!cancelled) setLoading(false);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [version]);
+	return {
+		user,
+		isAuthenticated: Amba.isAuthenticated,
+		loading
+	};
+}
+/**
+* Reactive subscription to a collection. Re-fetches when `options` or
+* `version` changes. Includes a `refetch` callback for manual refresh.
+*/
+function useCollection(name, options = {}) {
+	const { version } = useAmbaContext();
+	const [data, setData] = useState(null);
+	const [response, setResponse] = useState(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState(null);
+	const fetchData = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const resp = await Amba.collections.find(name, options);
+			setResponse(resp);
+			setData(resp.data);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+		} finally {
+			setLoading(false);
+		}
+	}, [name, JSON.stringify(options)]);
+	useEffect(() => {
+		fetchData();
+	}, [fetchData, version]);
+	return {
+		data,
+		loading,
+		error,
+		refetch: fetchData,
+		response
+	};
+}
+/**
+* Returns true if the named feature flag is enabled.
+* Fetches the flag set once on mount; subsequent calls read from cache.
+*/
+function useFlag(name) {
+	useAmbaContext();
+	const [enabled, setEnabled] = useState(false);
+	useEffect(() => {
+		let cancelled = false;
+		Amba.flags.fetch().then((flags) => {
+			if (cancelled) return;
+			setEnabled(flags.find((f) => f.name === name)?.enabled ?? false);
+		}).catch(() => {
+			if (!cancelled) setEnabled(false);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [name]);
+	return enabled;
+}
+/**
+* Returns the variant assignment for a multi-variant flag, or `null`
+* if unset / not loaded.
+*/
+function useVariant(name) {
+	useAmbaContext();
+	const [variant, setVariant] = useState(null);
+	useEffect(() => {
+		let cancelled = false;
+		Amba.flags.fetch().then((flags) => {
+			if (cancelled) return;
+			setVariant(flags.find((f) => f.name === name)?.variant ?? null);
+		}).catch(() => {
+			if (!cancelled) setVariant(null);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [name]);
+	return variant;
+}
+/**
+* Returns true if the user has the named entitlement (active subscription
+* or one-time purchase grant). Defaults to false on loading / error —
+* safe for paywall gating.
+*/
+function useEntitlement(name) {
+	useAmbaContext();
+	const [has, setHas] = useState(false);
+	useEffect(() => {
+		let cancelled = false;
+		Amba.entitlements.has(name).then((v) => {
+			if (!cancelled) setHas(v);
+		}).catch(() => {
+			if (!cancelled) setHas(false);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [name]);
+	return has;
+}
+/**
+* Tracks an event when this hook mounts. Useful for page-view tracking:
+* `useTrackOnMount('page_viewed', { path: '/home' })`.
+*/
+function useTrackOnMount(event, properties) {
+	useEffect(() => {
+		Amba.events.track(event, properties).catch(() => {});
+	}, []);
+}
+const SDK_VERSION = "0.1.0";
+
+//#endregion
+export { AmbaProvider, SDK_VERSION, useAmba, useCollection, useEntitlement, useFlag, useTrackOnMount, useUser, useVariant };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @layers/amba-react — React hooks for the amba SDK.\n *\n * Companion package to `@layers/amba-web`. Wraps the imperative `Amba.*`\n * surface in reactive hooks that re-render on state change.\n *\n * @example\n * ```tsx\n * import { Amba } from '@layers/amba-web';\n * import { AmbaProvider, useUser, useCollection, useFlag } from '@layers/amba-react';\n *\n * await Amba.configure({ apiKey: import.meta.env.VITE_AMBA_API_KEY });\n *\n * function App() {\n *   return (\n *     <AmbaProvider>\n *       <TodoList />\n *     </AmbaProvider>\n *   );\n * }\n *\n * function TodoList() {\n *   const user = useUser();\n *   const { data: todos, loading, refetch } = useCollection('todos', { limit: 20 });\n *   const newOnboarding = useFlag('new_onboarding');\n *   if (loading) return <Spinner />;\n *   return <ul>{todos?.map(t => <li key={t.id}>{t.title}</li>)}</ul>;\n * }\n * ```\n */\n\nimport { Amba } from \"@layers/amba-web\";\nimport type {\n  FindOptions,\n  FindResponse,\n  User,\n  FlagAssignment,\n} from \"@layers/amba-web\";\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useState,\n  type ReactNode,\n} from \"react\";\n\ninterface AmbaContextValue {\n  /**\n   * Bump this counter to force a re-render of hooks that read SDK state\n   * (`useUser`, `useIsAuthenticated`, …). Bumped on every auth state\n   * change (sign-in / sign-out / refresh).\n   */\n  version: number;\n  bumpVersion: () => void;\n}\n\nconst AmbaContext = createContext<AmbaContextValue | null>(null);\n\n/**\n * Wraps your app and provides reactive subscriptions to the amba SDK.\n *\n * Call `Amba.configure(...)` BEFORE rendering this provider. It does not\n * configure the SDK itself — it just plugs the React tree into the SDK's\n * state-change channel.\n */\nexport function AmbaProvider({ children }: { children: ReactNode }) {\n  const [version, setVersion] = useState(0);\n  const bumpVersion = useCallback(() => setVersion((v) => v + 1), []);\n  return createElement(\n    AmbaContext.Provider,\n    { value: { version, bumpVersion } },\n    children,\n  );\n}\n\nfunction useAmbaContext(): AmbaContextValue {\n  const ctx = useContext(AmbaContext);\n  if (!ctx) {\n    throw new Error(\n      \"@layers/amba-react: hooks must be used inside <AmbaProvider>. Wrap your app with <AmbaProvider> after calling Amba.configure()\",\n    );\n  }\n  return ctx;\n}\n\n/**\n * Returns the underlying SDK handle (`Amba`). Useful for one-off calls\n * that don't have a dedicated hook.\n */\nexport function useAmba() {\n  // Subscribe to version so this re-renders on state change.\n  useAmbaContext();\n  return Amba;\n}\n\n/**\n * Returns `{ user, isAuthenticated }` for the currently-signed-in user.\n * `user` is `null` until `auth.me()` resolves; the hook auto-fetches when\n * the SDK is authenticated and refreshes on auth-state changes.\n */\nexport function useUser(): {\n  user: User | null;\n  isAuthenticated: boolean;\n  loading: boolean;\n} {\n  const { version } = useAmbaContext();\n  const [user, setUser] = useState<User | null>(null);\n  const [loading, setLoading] = useState(false);\n\n  useEffect(() => {\n    if (!Amba.isAuthenticated) {\n      setUser(null);\n      return;\n    }\n    let cancelled = false;\n    setLoading(true);\n    Amba.auth\n      .me()\n      .then((u) => {\n        if (!cancelled) setUser(u);\n      })\n      .catch(() => {\n        if (!cancelled) setUser(null);\n      })\n      .finally(() => {\n        if (!cancelled) setLoading(false);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [version]);\n\n  return { user, isAuthenticated: Amba.isAuthenticated, loading };\n}\n\n/**\n * Reactive subscription to a collection. Re-fetches when `options` or\n * `version` changes. Includes a `refetch` callback for manual refresh.\n */\nexport function useCollection<T = unknown>(\n  name: string,\n  options: FindOptions = {},\n): {\n  data: T[] | null;\n  loading: boolean;\n  error: Error | null;\n  refetch: () => Promise<void>;\n  response: FindResponse<T> | null;\n} {\n  const { version } = useAmbaContext();\n  const [data, setData] = useState<T[] | null>(null);\n  const [response, setResponse] = useState<FindResponse<T> | null>(null);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Stringify options for stable dependency tracking\n  const optionsKey = JSON.stringify(options);\n\n  const fetchData = useCallback(async () => {\n    setLoading(true);\n    setError(null);\n    try {\n      const resp = await Amba.collections.find<T>(name, options);\n      setResponse(resp);\n      setData(resp.data);\n    } catch (e) {\n      setError(e instanceof Error ? e : new Error(String(e)));\n    } finally {\n      setLoading(false);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [name, optionsKey]);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData, version]);\n\n  return { data, loading, error, refetch: fetchData, response };\n}\n\n/**\n * Returns true if the named feature flag is enabled.\n * Fetches the flag set once on mount; subsequent calls read from cache.\n */\nexport function useFlag(name: string): boolean {\n  useAmbaContext();\n  const [enabled, setEnabled] = useState(false);\n\n  useEffect(() => {\n    let cancelled = false;\n    Amba.flags\n      .fetch()\n      .then((flags: FlagAssignment[]) => {\n        if (cancelled) return;\n        const match = flags.find((f) => f.name === name);\n        setEnabled(match?.enabled ?? false);\n      })\n      .catch(() => {\n        if (!cancelled) setEnabled(false);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [name]);\n\n  return enabled;\n}\n\n/**\n * Returns the variant assignment for a multi-variant flag, or `null`\n * if unset / not loaded.\n */\nexport function useVariant(name: string): string | null {\n  useAmbaContext();\n  const [variant, setVariant] = useState<string | null>(null);\n\n  useEffect(() => {\n    let cancelled = false;\n    Amba.flags\n      .fetch()\n      .then((flags: FlagAssignment[]) => {\n        if (cancelled) return;\n        const match = flags.find((f) => f.name === name);\n        setVariant(match?.variant ?? null);\n      })\n      .catch(() => {\n        if (!cancelled) setVariant(null);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [name]);\n\n  return variant;\n}\n\n/**\n * Returns true if the user has the named entitlement (active subscription\n * or one-time purchase grant). Defaults to false on loading / error —\n * safe for paywall gating.\n */\nexport function useEntitlement(name: string): boolean {\n  useAmbaContext();\n  const [has, setHas] = useState(false);\n\n  useEffect(() => {\n    let cancelled = false;\n    Amba.entitlements\n      .has(name)\n      .then((v) => {\n        if (!cancelled) setHas(v);\n      })\n      .catch(() => {\n        if (!cancelled) setHas(false);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [name]);\n\n  return has;\n}\n\n/**\n * Tracks an event when this hook mounts. Useful for page-view tracking:\n * `useTrackOnMount('page_viewed', { path: '/home' })`.\n */\nexport function useTrackOnMount(\n  event: string,\n  properties?: Record<string, unknown>,\n) {\n  useEffect(() => {\n    Amba.events.track(event, properties).catch(() => {\n      /* swallow — failure here is non-critical */\n    });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n}\n\nexport const SDK_VERSION = \"0.1.0\";\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@layers/amba-react",
+  "version": "1.0.0",
+  "description": "React hooks for the amba SDK — useAmba, useUser, useCollection, useFlag, and more",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/layers/amba-sdks.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@layers/amba-web": "^1.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@types/node": "^22.13.14",
+    "happy-dom": "^15.11.7",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.15.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}