@newco-ai-platform/sdk-react

React auth surface for the NewCo Suite — <AuthGuard>, useUser(), useSession(), plus a pluggable AuthAdapter shape. Mirrors the Python newco_sdk.auth surface so a developer touching both sides learns one API.

Zero direct Clerk / Authentik / OIDC imports. Concrete adapters ship in subsequent stories alongside their Python counterparts (NEW-36 epic). Web apps depend on this package; the provider plug-in lives in the host app via the <AuthProvider adapter={…}> boundary.

Install

npm install @newco-ai-platform/sdk-react react

React 18 or 19 is a peer dependency.

Usage

import {
  AuthProvider,
  AuthGuard,
  useUser,
  useSession,
  type AuthAdapter,
} from '@newco-ai-platform/sdk-react';
import { useState } from 'react';

function App() {
  const [auth, setAuth] = useState({ user: null, session: null });

  const adapter: AuthAdapter = {
    ...auth,
    signOut: () => setAuth({ user: null, session: null }),
  };

  return (
    <AuthProvider adapter={adapter}>
      <AuthGuard onUnauthenticated={() => router.replace('/sign-in')}>
        <Dashboard />
      </AuthGuard>
    </AuthProvider>
  );
}

function Dashboard() {
  const user = useUser();
  const session = useSession();
  return <p>Hello {user?.name} (org {session?.org_id})</p>;
}

API

<AuthProvider adapter={…}>

Wraps the tree with the auth context. Reads user, session, signOut off the adapter; context value updates when any of the three references change.

<AuthGuard>

Gates children on useSession() !== null. Children NEVER render when the session is null — the fallback (or built-in sign-in prompt) renders instead.

Props:

| Prop | Type | Default | Notes | |---------------------|---------------------|--------------------------|--------------------------------------------------------| | children | ReactNode | required | Rendered only when authenticated. | | fallback | ReactNode | minimal sign-in panel | Rendered when session === null. | | onUnauthenticated | () => void | — | Fired in useEffect when session === null. Wire to your router. |

useUser(): User | null

Current user, or null when unauthenticated. Throws if called outside <AuthProvider>.

useSession(): Session | null

Current session, or null when unauthenticated. Throws if called outside <AuthProvider>.

useAuth(): { user, session, signOut }

Escape hatch — most callers should use the narrower useUser / useSession. Use this when you also need signOut.

AuthAdapter

interface AuthAdapter {
  user: User | null;
  session: Session | null;
  signOut: () => void;
}

Concrete adapters (Clerk, Authentik, OIDC) ship as separate packages in subsequent stories. The simplest local pattern is to hold auth state in useState and recreate the adapter on each render (see the example above).

Types

User, Session, and IdentityProvider mirror the canonical zod schemas in @newco-ai-platform/types/auth. They're declared locally here (TS-only, no zod runtime) so apps don't pull a validation library into the bundle just to read User.email. Shape MUST match the canonical schema — contracts-owner PR review catches divergence.

Scripts

| Script | What it does | |---------------------|------------------------------------| | npm run typecheck | tsc --noEmit | | npm test | vitest run (jsdom environment) | | npm run build | tsup → ESM + CJS + d.ts in dist/ |

License

UNLICENSED — internal use.