@fanapps/react-native 0.2.0

package/README.md

@@ -0,0 +1,324 @@
+# @fanapps/react-native
+
+React Native SDK for the Fanapps API — Firebase-powered auth, paginated content hooks, and FCM push-target registration.
+
+## Install
+
+```sh
+pnpm add @fanapps/react-native \
+  @tanstack/react-query \
+  @react-native-firebase/app \
+  @react-native-firebase/auth
+```
+
+`react`, `react-native`, `@tanstack/react-query`, `@react-native-firebase/app`, and `@react-native-firebase/auth` are **required** peer dependencies.
+
+Optional peers (install only if you use the matching feature):
+
+| Feature                             | Package                                        |
+| ----------------------------------- | ---------------------------------------------- |
+| Push registration + topic subscribe | `@react-native-firebase/messaging`             |
+| Persist `targetId` across launches  | `@react-native-async-storage/async-storage`    |
+| Google sign-in                      | `@react-native-google-signin/google-signin`    |
+| Apple sign-in (iOS)                 | `@invertase/react-native-apple-authentication` |
+
+You also need Firebase's native config (`google-services.json` on Android, `GoogleService-Info.plist` on iOS) — see the [React Native Firebase docs](https://rnfirebase.io).
+
+## Quick start
+
+```tsx
+import { FanappsProvider, useAuth, useEntries } from '@fanapps/react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export default function App() {
+  return (
+    <FanappsProvider
+      apiKey={process.env.EXPO_PUBLIC_FANAPPS_TOKEN!}
+      project={process.env.EXPO_PUBLIC_FANAPPS_PROJECT!}
+      locale="en"
+      storage={AsyncStorage}
+    >
+      <Feed />
+    </FanappsProvider>
+  );
+}
+
+function Feed() {
+  const { user, status } = useAuth();
+  const { data, isLoading, error } = useEntries({ blueprint: 'news', perPage: 20 });
+
+  if (status === 'loading') return <Text>…</Text>;
+  if (isLoading) return <Text>Loading…</Text>;
+  if (error) return <Text>Failed: {error.message}</Text>;
+
+  return <FlatList data={data?.data} /* ... */ />;
+}
+```
+
+## Provider props
+
+| Prop          | Type             | Required | Description                                                                                                     |
+| ------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `apiKey`      | `string`         | yes      | App-level bearer token. Sent as `Authorization: Bearer <apiKey>`.                                               |
+| `project`     | `string`         | yes      | Tenant UUID. Sent as `X-Tenant` header.                                                                         |
+| `locale`      | `string`         | no       | Default locale (e.g. `"en"`). Reactive — changing it refetches all queries.                                     |
+| `baseUrl`     | `string`         | no       | API base URL. Defaults to production.                                                                           |
+| `queryClient` | `QueryClient`    | no       | Reuse an existing React Query client. Otherwise one is created internally.                                      |
+| `storage`     | `StorageAdapter` | no       | Storage for persisted state (e.g. push target IDs). Defaults to AsyncStorage if installed; otherwise in-memory. |
+
+## Auth
+
+`useAuth` wraps `@react-native-firebase/auth` and keeps the SDK in sync with Firebase's auth state. The SDK automatically attaches a fresh Firebase ID token as `X-Firebase-Token` on every request, so the backend can resolve the signed-in `AppUser`.
+
+```tsx
+import { useAuth } from '@fanapps/react-native';
+
+function Screen() {
+  const {
+    user,            // AuthUser | null  — Firebase user shape
+    status,          // 'loading' | 'signed-in' | 'signed-out'
+    signInWithEmail,
+    signUpWithEmail,
+    sendPasswordResetEmail,
+    sendEmailVerification,
+    signInWithGoogle,
+    signInWithApple,
+    signOut,
+  } = useAuth();
+
+  // ...
+}
+```
+
+**Notes**
+
+- `user` is sourced entirely from Firebase (`onAuthStateChanged`) — no backend round-trip on auth state change.
+- `signInWithGoogle` throws a `FanappsAuthError` with code `peer/missing` if `@react-native-google-signin/google-signin` isn't installed. Same for `signInWithApple`.
+- `signInWithApple` is iOS-only in v1. On Android it throws `auth/platform-not-supported`.
+- Token refresh is handled by Firebase; the SDK calls `currentUser.getIdToken()` before each request, which returns a cached token and only refreshes when close to expiry.
+
+## Push notifications
+
+The SDK registers the device's FCM token as a _push target_ on the backend, using the Appwrite-style targetId pattern: a client-generated, client-persisted ID that's stable across token rotations.
+
+### Register a device
+
+```tsx
+import { useAuth, useRegisterDevice } from '@fanapps/react-native';
+import { useEffect } from 'react';
+
+function PushSetup() {
+  const { status } = useAuth();
+  const push = useRegisterDevice();
+
+  useEffect(() => {
+    if (status === 'signed-in') push.register();
+    else if (status === 'signed-out') push.unregister();
+  }, [status]);
+
+  return null;
+}
+```
+
+`register()` does all of:
+
+1. Requests notification permission (iOS prompt; no-op if already granted).
+2. Fetches the FCM token.
+3. Creates a push target on the backend (or updates an existing one if a `targetId` is stored locally).
+4. Persists the `targetId` via the `storage` adapter.
+5. Subscribes to `onTokenRefresh`; when FCM rotates the token, the SDK silently PATCHes the backend.
+
+`unregister()` deletes the backend row and clears the stored `targetId`. Call it on sign-out.
+
+### Subscribe to topics
+
+FCM topics are the cheapest way to broadcast — no backend round-trip, no storage needed.
+
+```tsx
+import { useTopicSubscription } from '@fanapps/react-native';
+
+const topics = useTopicSubscription();
+await topics.subscribe('news');
+await topics.unsubscribe('news');
+```
+
+The backend has no visibility into who subscribed to which topic — that's FCM's job. Your dashboard just sends a message to the topic name.
+
+### Displaying notifications
+
+The SDK does **not** manage notification display or tap handling. Set up handlers yourself using `@react-native-firebase/messaging`:
+
+```tsx
+import messaging from '@react-native-firebase/messaging';
+
+messaging().onMessage(async remote => {
+  // foreground notification
+});
+
+messaging().onNotificationOpenedApp(remote => {
+  // user tapped a background notification
+});
+```
+
+## Content hooks
+
+All hooks accept an `options` arg with `{ locale?, enabled? }` to override the provider locale per call or pause the query.
+
+### Entries
+
+```ts
+useEntries(filters?: EntryFilters, options?)  // Paginated<Entry>
+useEntry(id, options?)                        // Entry
+```
+
+Filters: `blueprint`, `collection`, `slug`, `published`, `sort` (e.g. `-date`), `perPage`, `page`.
+
+### Articles
+
+```ts
+useArticles(filters?: ArticleFilters, options?)  // Paginated<Article>
+useArticle(id, options?)                         // Article
+```
+
+Filters: `is_published`, `sort`, `perPage`, `page`.
+
+### Trivia
+
+```ts
+useTrivias(options?)         // Trivia[]
+useTrivia(id, options?)      // Trivia
+useSubmitTriviaResponse()    // mutation
+```
+
+```tsx
+const submit = useSubmitTriviaResponse();
+submit.mutate(
+  { triviaId, answerId },
+  {
+    onSuccess: ({ is_correct, points_awarded }) => {
+      // ...
+    },
+  },
+);
+```
+
+On success the mutation invalidates the related `useTrivia(id)` query so `responses_count` and other derived values refresh.
+
+## Escape hatch
+
+For endpoints not covered by a hook:
+
+```tsx
+import { useFanappsClient } from '@fanapps/react-native';
+
+function Thing() {
+  const client = useFanappsClient();
+  // client.get('/api/custom', { foo: 'bar' })
+  // client.post('/api/custom', { ... })
+  // client.patch('/api/custom/1', { ... })
+  // client.delete('/api/custom/1')
+}
+```
+
+All client calls carry the same `Authorization`, `X-Tenant`, and `X-Firebase-Token` headers as the hooks.
+
+## Errors
+
+- Non-2xx HTTP responses throw `FanappsError` with `{ status, body, message }`.
+- Auth flows throw `FanappsAuthError` with a `code` field. Common codes: `peer/load-failed` (module can't be loaded — usually a Metro symlink issue, see below), `peer/unexpected-shape` (loaded but wrong interop shape), `auth/platform-not-supported`, `auth/not-supported`, `auth/no-token`.
+
+```tsx
+import { FanappsError, FanappsAuthError } from '@fanapps/react-native';
+
+const { error } = useEntries();
+if (error instanceof FanappsError && error.status === 401) {
+  // sign-out, etc.
+}
+
+try {
+  await signInWithGoogle();
+} catch (e) {
+  if (e instanceof FanappsAuthError && e.code === 'peer/load-failed') {
+    // Google package couldn't be loaded — see "Symlinked installs" section
+  }
+}
+```
+
+## Storage adapter
+
+`FanappsProvider`'s `storage` prop accepts anything with this shape:
+
+```ts
+interface StorageAdapter {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+```
+
+`@react-native-async-storage/async-storage`'s default export matches this exactly. If you want to use `expo-secure-store` or a custom backend, wrap it in an adapter.
+
+If no `storage` prop is passed and AsyncStorage isn't installed, the SDK falls back to in-memory storage — the `targetId` will be lost on app restart, and a new push target row will be created on the next `register()` call.
+
+## Symlinked installs (local development)
+
+If you link the SDK via `pnpm link`, a filesystem symlink, or `file:` protocol, Metro will often fail to resolve peer dependencies like `@react-native-firebase/auth` from the SDK's location — even though they're installed in your app. You'll see:
+
+```
+FanappsAuthError: @fanapps/react-native could not load @react-native-firebase/auth:
+Unable to resolve module '@react-native-firebase/auth'
+```
+
+The error code on the thrown `FanappsAuthError` is `peer/load-failed`. Two fixes:
+
+### Option A — `yalc` (recommended)
+
+`yalc` copies files instead of symlinking, so Metro has nothing special to resolve. From the SDK directory:
+
+```sh
+yalc publish
+```
+
+In your app:
+
+```sh
+yalc add @fanapps/react-native
+pnpm install
+```
+
+When you change the SDK: `pnpm build && yalc push` — all linked apps update immediately.
+
+### Option B — Metro config with `extraNodeModules`
+
+If you must keep the symlink (e.g. you want live SDK changes without a push step), tell Metro to always resolve peer deps from the app's `node_modules`:
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('@react-native/metro-config');
+const path = require('path');
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.unstable_enableSymlinks = true;
+config.resolver.extraNodeModules = new Proxy(
+  {},
+  { get: (_, name) => path.resolve(__dirname, 'node_modules', String(name)) },
+);
+config.watchFolders = [
+  path.resolve(__dirname, '../path/to/fanapps/resources/sdk/react-native'),
+];
+
+module.exports = config;
+```
+
+Then clear Metro cache: `npx react-native start --reset-cache` (or `expo start -c`).
+
+The `extraNodeModules` Proxy forces every module lookup — including ones originating inside the symlinked SDK — to resolve against your app's `node_modules`. This avoids duplicate copies of `react` / `react-native` / `@react-native-firebase/*` too, which would otherwise cause "Invalid hook call" errors.
+
+## Build
+
+```sh
+pnpm install
+pnpm build       # tsup → dist/
+pnpm typecheck   # tsc --noEmit
+```

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueryClient, UseQueryResult, UseMutationResult } from '@tanstack/react-query';
+import { ReactNode } from 'react';
+
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+type Locale = string;
+type EntryData = Record<string, unknown>;
+interface Entry {
+    id: string | number;
+    slug: string;
+    published: boolean;
+    date: string | null;
+    order: number | null;
+    collection: string | null;
+    blueprint: string;
+    data: EntryData;
+    created_at: string;
+    updated_at: string;
+    locale: Locale;
+    available_locales?: Locale[];
+}
+interface Article {
+    id: string | number;
+    title: string;
+    content: string;
+    is_published: boolean;
+    featured_image_url: string | null;
+    created_at: string;
+    updated_at: string;
+    locale: Locale;
+    available_locales?: Locale[];
+}
+interface TriviaAnswer {
+    id: string | number;
+    text: string;
+    is_correct: boolean;
+    sort_order: number;
+}
+interface Trivia {
+    id: string | number;
+    title: string;
+    description: string | null;
+    featured_image_id: string | number | null;
+    featured_image?: {
+        id: string | number;
+        url: string;
+        [key: string]: unknown;
+    } | null;
+    awards_points: boolean;
+    points_amount: number;
+    max_time_seconds: number | null;
+    show_correct_after: boolean;
+    starts_at: string | null;
+    ends_at: string | null;
+    answers: TriviaAnswer[];
+    responses_count?: number;
+    created_at: string;
+    updated_at: string;
+}
+interface TriviaResponseResult {
+    is_correct: boolean;
+    points_awarded: number;
+    correct_answer?: TriviaAnswer;
+}
+interface PaginationMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+    path?: string;
+}
+interface PaginationLinks {
+    first: string | null;
+    last: string | null;
+    prev: string | null;
+    next: string | null;
+}
+interface Paginated<T> {
+    data: T[];
+    meta: PaginationMeta;
+    links: PaginationLinks;
+}
+interface PaginationParams {
+    page?: number;
+    perPage?: number;
+    sort?: string;
+}
+interface EntryFilters extends PaginationParams {
+    blueprint?: string;
+    collection?: string;
+    slug?: string;
+    published?: boolean;
+}
+interface ArticleFilters extends PaginationParams {
+    is_published?: boolean;
+}
+interface HookOptions {
+    locale?: Locale;
+    enabled?: boolean;
+}
+type AuthStatus = 'loading' | 'signed-in' | 'signed-out';
+interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+    phoneNumber: string | null;
+    isAnonymous: boolean;
+    providerId: string | null;
+}
+interface PushTarget {
+    id: string;
+    app_user_id: number | string | null;
+    identifier: string;
+    provider: 'fcm' | 'apns';
+    provider_id: string | null;
+    device_brand: string | null;
+    device_model: string | null;
+    os_name: string | null;
+    os_version: string | null;
+    last_seen_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreatePushTargetInput {
+    targetId: string;
+    identifier: string;
+    providerId?: string;
+    deviceBrand?: string;
+    deviceModel?: string;
+    osName?: string;
+    osVersion?: string;
+}
+
+interface FanappsProviderProps {
+    apiKey: string;
+    project: string;
+    locale?: Locale;
+    baseUrl?: string;
+    queryClient?: QueryClient;
+    storage?: StorageAdapter;
+    children: ReactNode;
+}
+declare function FanappsProvider({ apiKey, project, locale, baseUrl, queryClient, storage, children, }: FanappsProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FanappsClientOptions {
+    apiKey: string;
+    project: string;
+    baseUrl: string;
+    getIdToken?: () => Promise<string | null>;
+}
+type QueryParams = Record<string, unknown>;
+declare class FanappsClient {
+    private readonly apiKey;
+    private readonly project;
+    private readonly baseUrl;
+    private readonly getIdToken?;
+    constructor(options: FanappsClientOptions);
+    get<T>(path: string, params?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    patch<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    delete<T>(path: string, signal?: AbortSignal): Promise<T>;
+    createPushTarget(input: CreatePushTargetInput): Promise<PushTarget>;
+    updatePushTarget(targetId: string, identifier: string): Promise<PushTarget>;
+    deletePushTarget(targetId: string): Promise<void>;
+    private request;
+    private buildUrl;
+}
+
+declare class FanappsError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+
+declare class FanappsAuthError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+declare function useFanappsClient(): FanappsClient;
+
+interface UseAuthResult {
+    user: AuthUser | null;
+    status: AuthStatus;
+    signInWithEmail(email: string, password: string): Promise<AuthUser>;
+    signUpWithEmail(email: string, password: string): Promise<AuthUser>;
+    sendPasswordResetEmail(email: string): Promise<void>;
+    sendEmailVerification(): Promise<void>;
+    signInWithGoogle(): Promise<AuthUser>;
+    signInWithApple(): Promise<AuthUser>;
+    signOut(): Promise<void>;
+}
+declare function useAuth(): UseAuthResult;
+
+declare function useEntries(filters?: EntryFilters, options?: HookOptions): UseQueryResult<Paginated<Entry>>;
+
+declare function useEntry(id: string | number | null | undefined, options?: HookOptions): UseQueryResult<Entry>;
+
+declare function useArticles(filters?: ArticleFilters, options?: HookOptions): UseQueryResult<Paginated<Article>>;
+
+declare function useArticle(id: string | number | null | undefined, options?: HookOptions): UseQueryResult<Article>;
+
+interface UseRegisterDeviceResult {
+    targetId: string | null;
+    token: string | null;
+    target: PushTarget | null;
+    isRegistering: boolean;
+    error: Error | null;
+    register(): Promise<PushTarget>;
+    unregister(): Promise<void>;
+}
+declare function useRegisterDevice(): UseRegisterDeviceResult;
+
+declare function useTrivias(options?: HookOptions): UseQueryResult<Trivia[]>;
+
+declare function useTrivia(id: string | number | null | undefined, options?: HookOptions): UseQueryResult<Trivia>;
+
+interface SubmitTriviaResponseInput {
+    triviaId: string | number;
+    answerId: string | number;
+}
+declare function useSubmitTriviaResponse(): UseMutationResult<TriviaResponseResult, FanappsError, SubmitTriviaResponseInput>;
+
+interface UseTopicSubscriptionResult {
+    subscribe(topic: string): Promise<void>;
+    unsubscribe(topic: string): Promise<void>;
+}
+declare function useTopicSubscription(): UseTopicSubscriptionResult;
+
+export { type Article, type ArticleFilters, type AuthStatus, type AuthUser, type CreatePushTargetInput, type Entry, type EntryData, type EntryFilters, FanappsAuthError, FanappsClient, type FanappsClientOptions, FanappsError, FanappsProvider, type FanappsProviderProps, type HookOptions, type Locale, type Paginated, type PaginationLinks, type PaginationMeta, type PaginationParams, type PushTarget, type StorageAdapter, type SubmitTriviaResponseInput, type Trivia, type TriviaAnswer, type TriviaResponseResult, type UseAuthResult, type UseRegisterDeviceResult, type UseTopicSubscriptionResult, useArticle, useArticles, useAuth, useEntries, useEntry, useFanappsClient, useRegisterDevice, useSubmitTriviaResponse, useTopicSubscription, useTrivia, useTrivias };