@smarthivelabs-devs/auth-expo 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,472 @@
+# @smarthivelabs-devs/auth-expo
+
+SmartHive Auth for React Native and Expo. Provides a provider, hooks, and components with SecureStore-backed token storage and deep-link OAuth support.
+
+---
+
+## Installation
+
+```bash
+npx expo install @smarthivelabs-devs/auth-expo @smarthivelabs-devs/auth-sdk expo-auth-session expo-secure-store
+```
+
+Or with npm/pnpm (non-Expo managed workflow):
+
+```bash
+npm install @smarthivelabs-devs/auth-expo @smarthivelabs-devs/auth-sdk expo-auth-session expo-secure-store
+pnpm add @smarthivelabs-devs/auth-expo @smarthivelabs-devs/auth-sdk expo-auth-session expo-secure-store
+```
+
+> **Peer dependencies required:** `expo-auth-session>=5`, `expo-secure-store>=12`, `react>=18`, `react-native>=0.73`
+
+---
+
+## Prerequisites
+
+1. A SmartHive Auth project — grab `projectId`, `publishableKey`, and `baseUrl` from your dashboard.
+2. A registered deep link scheme for your Expo app (see below).
+
+---
+
+## Deep Link Setup
+
+SmartHive Auth uses OAuth 2.0 + PKCE. After login, the server redirects back to your app via a deep link (e.g. `myapp://auth/callback`). You must register a custom scheme in `app.json`:
+
+```json
+// app.json
+{
+  "expo": {
+    "scheme": "myapp",
+    "android": {
+      "intentFilters": [
+        {
+          "action": "VIEW",
+          "autoVerify": true,
+          "data": [{ "scheme": "myapp" }],
+          "category": ["BROWSABLE", "DEFAULT"]
+        }
+      ]
+    }
+  }
+}
+```
+
+Rebuild your native app after this change:
+
+```bash
+npx expo prebuild
+```
+
+---
+
+## Setup
+
+Wrap your root component with `SmartHiveProvider`. Use `buildRedirectUri` to construct the deep link URI from your scheme.
+
+```tsx
+// App.tsx
+import { SmartHiveProvider, buildRedirectUri } from "@smarthivelabs-devs/auth-expo";
+
+const REDIRECT_URI = buildRedirectUri("myapp"); // → "myapp://auth/callback"
+
+export default function App() {
+  return (
+    <SmartHiveProvider
+      projectId={process.env.EXPO_PUBLIC_AUTH_PROJECT_ID!}
+      publishableKey={process.env.EXPO_PUBLIC_AUTH_PUBLISHABLE_KEY!}
+      baseUrl={process.env.EXPO_PUBLIC_AUTH_BASE_URL!}
+      redirectUri={REDIRECT_URI}
+    >
+      <RootNavigator />
+    </SmartHiveProvider>
+  );
+}
+```
+
+### `buildRedirectUri(scheme, path?)`
+
+Helper that constructs a deep link URI:
+
+```ts
+buildRedirectUri("myapp")                 // → "myapp://auth/callback"
+buildRedirectUri("myapp", "auth/done")    // → "myapp://auth/done"
+```
+
+---
+
+## Provider Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `projectId` | `string` | Yes | Your SmartHive project ID |
+| `publishableKey` | `string` | Yes | Your publishable key |
+| `baseUrl` | `string` | Yes | URL of your SmartHive Auth service |
+| `redirectUri` | `string` | Yes | Deep link callback URI (e.g. `myapp://auth/callback`) |
+| `authDomain` | `string` | No | Custom branded auth domain |
+| `children` | `ReactNode` | Yes | Your app tree |
+
+---
+
+## How OAuth Works in Expo
+
+1. User taps **Sign in** → `login()` is called
+2. The SDK builds the OAuth URL with PKCE, saves the verifier in SecureStore, and opens the URL in the system browser via `Linking.openURL()`
+3. The user logs in via the browser
+4. The server redirects to `myapp://auth/callback?code=...&state=...`
+5. `Linking` fires a `url` event — `SmartHiveProvider` handles it automatically, exchanges the code for tokens, and updates the session state
+
+No manual callback handling is needed — the provider sets up the `Linking` event listener internally.
+
+---
+
+## Hooks
+
+### `useAuth()`
+
+Returns the full auth context.
+
+```tsx
+import { useAuth } from "@smarthivelabs-devs/auth-expo";
+
+function HomeScreen() {
+  const {
+    session,        // AuthSession | null
+    isLoaded,       // true once initial SecureStore read is done
+    isSignedIn,     // boolean
+    login,          // (options?) => Promise<void>
+    logout,         // () => Promise<void>
+    refreshSession, // () => Promise<void>
+    authFetch,      // authenticated fetch wrapper
+  } = useAuth();
+
+  if (!isLoaded) return <ActivityIndicator />;
+
+  return isSignedIn ? (
+    <Button title="Sign out" onPress={logout} />
+  ) : (
+    <Button title="Sign in" onPress={() => login()} />
+  );
+}
+```
+
+---
+
+### `useSession()`
+
+Returns the current `AuthSession` or `null`.
+
+```tsx
+import { useSession } from "@smarthivelabs-devs/auth-expo";
+
+function TokenScreen() {
+  const session = useSession();
+  if (!session) return <Text>Not signed in</Text>;
+  return <Text selectable>{session.accessToken}</Text>;
+}
+```
+
+---
+
+### `useUser()`
+
+Returns the user object from the session, or `null`.
+
+```tsx
+import { useUser } from "@smarthivelabs-devs/auth-expo";
+
+function ProfileScreen() {
+  const user = useUser();
+  if (!user) return null;
+  return <Text>Welcome, {(user as any).email}</Text>;
+}
+```
+
+---
+
+### `useIsLoaded()`
+
+Returns `true` once the initial SecureStore session check is done. Prevents a flash of the signed-out state on app startup.
+
+```tsx
+import { useIsLoaded } from "@smarthivelabs-devs/auth-expo";
+
+function RootNavigator() {
+  const isLoaded = useIsLoaded();
+  if (!isLoaded) return <SplashScreen />;
+  return <AppNavigator />;
+}
+```
+
+---
+
+### `useIsSignedIn()`
+
+Returns `true` (signed in), `false` (signed out), or `null` (still loading).
+
+```tsx
+import { useIsSignedIn } from "@smarthivelabs-devs/auth-expo";
+
+function AuthGate({ children }: { children: React.ReactNode }) {
+  const isSignedIn = useIsSignedIn();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (isSignedIn === false) router.replace("/login");
+  }, [isSignedIn]);
+
+  if (isSignedIn === null) return <ActivityIndicator />;
+  if (!isSignedIn) return null;
+  return <>{children}</>;
+}
+```
+
+---
+
+### `useAuthFetch()`
+
+Returns an authenticated `fetch` function. Automatically injects the Bearer token on every request — tokens are refreshed transparently.
+
+```tsx
+import { useAuthFetch } from "@smarthivelabs-devs/auth-expo";
+
+function DataScreen() {
+  const authFetch = useAuthFetch();
+  const [data, setData] = useState(null);
+
+  async function load() {
+    const res = await authFetch("https://api.myapp.com/protected");
+    setData(await res.json());
+  }
+
+  return (
+    <View>
+      <Button title="Load data" onPress={load} />
+      {data && <Text>{JSON.stringify(data)}</Text>}
+    </View>
+  );
+}
+```
+
+---
+
+### `useAuthorizationHeader()`
+
+Returns a function that resolves to `{ authorization: "Bearer <token>" }`. Useful for passing to SDKs or GraphQL clients.
+
+```tsx
+import { useAuthorizationHeader } from "@smarthivelabs-devs/auth-expo";
+
+function ApolloSetup() {
+  const getAuthorizationHeader = useAuthorizationHeader();
+
+  const authLink = new ApolloLink(async (operation, forward) => {
+    const headers = await getAuthorizationHeader();
+    operation.setContext({ headers });
+    return forward(operation);
+  });
+
+  // ...
+}
+```
+
+---
+
+## Render Helpers
+
+### `<SignedIn>`
+
+Renders children only when auth has loaded **and** a session exists.
+
+```tsx
+import { SignedIn } from "@smarthivelabs-devs/auth-expo";
+
+<SignedIn>
+  <UserDashboard />
+</SignedIn>
+```
+
+### `<SignedOut>`
+
+Renders children only when auth has loaded **and** there is no session.
+
+```tsx
+import { SignedOut } from "@smarthivelabs-devs/auth-expo";
+
+<SignedOut>
+  <LandingScreen />
+</SignedOut>
+```
+
+### `<AuthLoading>`
+
+Renders children while the initial session check is running.
+
+```tsx
+import { AuthLoading } from "@smarthivelabs-devs/auth-expo";
+
+<AuthLoading>
+  <ActivityIndicator size="large" />
+</AuthLoading>
+```
+
+---
+
+## Expo Router Integration
+
+```
+app/
+├── _layout.tsx         ← SmartHiveProvider here
+├── index.tsx           ← SignedIn / SignedOut
+├── login.tsx           ← login screen
+└── (protected)/
+    └── dashboard.tsx   ← authenticated screen
+```
+
+```tsx
+// app/_layout.tsx
+import { Stack } from "expo-router";
+import { SmartHiveProvider, buildRedirectUri } from "@smarthivelabs-devs/auth-expo";
+
+export default function Layout() {
+  return (
+    <SmartHiveProvider
+      projectId={process.env.EXPO_PUBLIC_AUTH_PROJECT_ID!}
+      publishableKey={process.env.EXPO_PUBLIC_AUTH_PUBLISHABLE_KEY!}
+      baseUrl={process.env.EXPO_PUBLIC_AUTH_BASE_URL!}
+      redirectUri={buildRedirectUri("myapp")}
+    >
+      <Stack />
+    </SmartHiveProvider>
+  );
+}
+```
+
+```tsx
+// app/index.tsx
+import { SignedIn, SignedOut, AuthLoading } from "@smarthivelabs-devs/auth-expo";
+import { Redirect } from "expo-router";
+import { ActivityIndicator } from "react-native";
+
+export default function Index() {
+  return (
+    <>
+      <AuthLoading><ActivityIndicator /></AuthLoading>
+      <SignedIn><Redirect href="/dashboard" /></SignedIn>
+      <SignedOut><Redirect href="/login" /></SignedOut>
+    </>
+  );
+}
+```
+
+```tsx
+// app/login.tsx
+import { useAuth } from "@smarthivelabs-devs/auth-expo";
+import { Button, View } from "react-native";
+
+export default function LoginScreen() {
+  const { login } = useAuth();
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <Button title="Sign in with SmartHive" onPress={() => login()} />
+    </View>
+  );
+}
+```
+
+```tsx
+// app/(protected)/dashboard.tsx
+import { useAuth, SignedIn } from "@smarthivelabs-devs/auth-expo";
+import { Button, Text, View } from "react-native";
+
+export default function Dashboard() {
+  const { logout, authFetch } = useAuth();
+
+  return (
+    <SignedIn>
+      <View>
+        <Text>Dashboard</Text>
+        <Button title="Sign out" onPress={logout} />
+      </View>
+    </SignedIn>
+  );
+}
+```
+
+---
+
+## Low-level: `initExpoAuth`
+
+If you need the client directly without the provider (advanced use), use `initExpoAuth`:
+
+```ts
+import { initExpoAuth, buildRedirectUri } from "@smarthivelabs-devs/auth-expo";
+
+const client = initExpoAuth({
+  projectId: "proj_abc123",
+  publishableKey: "pk_live_abc123",
+  baseUrl: "https://auth.myapp.com",
+  redirectUri: buildRedirectUri("myapp"),
+});
+
+await client.initialize();
+
+// The client behaves the same as SmartHiveAuthClient from auth-sdk,
+// but uses SecureStore and Linking instead of localStorage + location.assign
+```
+
+---
+
+## Environment Variables
+
+With Expo's built-in env support (SDK 49+):
+
+```bash
+# .env
+EXPO_PUBLIC_AUTH_PROJECT_ID=proj_abc123
+EXPO_PUBLIC_AUTH_PUBLISHABLE_KEY=pk_live_abc123
+EXPO_PUBLIC_AUTH_BASE_URL=https://auth.myapp.com
+```
+
+> Variables prefixed `EXPO_PUBLIC_` are embedded in the app bundle at build time.
+
+---
+
+## Token Storage
+
+Tokens are stored in `expo-secure-store`, which uses:
+- **iOS**: Keychain Services
+- **Android**: Keystore System (Android Keystore-backed AES encryption)
+
+PKCE verifier and state are also stored in SecureStore during the login flow and deleted after the code exchange.
+
+---
+
+## TypeScript Types
+
+```ts
+import type {
+  SmartHiveExpoConfig,
+  SmartHiveProviderProps,
+} from "@smarthivelabs-devs/auth-expo";
+
+import type {
+  AuthSession,
+  SmartHiveAuthClient,
+} from "@smarthivelabs-devs/auth-sdk";
+```
+
+---
+
+## Related Packages
+
+| Package | Use case |
+|---|---|
+| [`@smarthivelabs-devs/auth-sdk`](https://www.npmjs.com/package/@smarthivelabs-devs/auth-sdk) | Core SDK — framework-agnostic |
+| [`@smarthivelabs-devs/auth-react`](https://www.npmjs.com/package/@smarthivelabs-devs/auth-react) | React web apps |
+| [`@smarthivelabs-devs/auth-server`](https://www.npmjs.com/package/@smarthivelabs-devs/auth-server) | Express / Next.js server-side JWT verification |
+
+---
+
+## License
+
+MIT © SmartHive Labs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smarthivelabs-devs/auth-expo",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "SmartHive Auth provider, hooks, and SecureStore integration for React Native / Expo",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@smarthivelabs-devs/auth-sdk": "^0.1.0",
+    "@smarthivelabs-devs/auth-sdk": "^1.0.0",
     "expo-auth-session": ">=5",
     "expo-secure-store": ">=12",
     "react": ">=18",
@@ -36,7 +36,7 @@
     "@types/react-native": "^0.73.0",
     "tsup": "^8.3.0",
     "typescript": "^5.7.3",
-    "@smarthivelabs-devs/auth-sdk": "^0.1.0"
+    "@smarthivelabs-devs/auth-sdk": "^1.0.0"
   },
   "scripts": {
     "build": "tsup",