@optare/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Optare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @optare/react
+
+React bindings for Optare — a provider, session hooks, and drop-in **white-label**
+sign-in / sign-up / account components. Built on [`@optare/client`](../client).
+
+The entire integration contract is one string: a publishable key (`pk_live_…`).
+It is **not** a secret — it ships in your browser bundle — so the SDK uses it to
+look up, from a public endpoint, where the auth API lives and what the project's
+branding is (logo, name, primary colour, corner radius). That is how a customer
+gets a branded login screen without hosting anything.
+
+## Install
+
+```bash
+npm install @optare/react
+# peer deps: react >= 18, react-dom >= 18
+```
+
+## Quick start
+
+```tsx
+import { OptareProvider, SignIn, AccountButton, useSession } from "@optare/react";
+
+function Root() {
+  return (
+    <OptareProvider publishableKey={import.meta.env.VITE_OPTARE_PK}>
+      <App />
+    </OptareProvider>
+  );
+}
+
+function App() {
+  const { isPending, isAuthenticated, user } = useSession();
+  if (isPending) return null;
+  return isAuthenticated ? (
+    <>
+      <p>Hello {user?.name}</p>
+      <AccountButton />
+    </>
+  ) : (
+    <SignIn onSuccess={() => location.assign("/dashboard")} />
+  );
+}
+```
+
+Nothing above configures branding — the provider resolves it from the key and
+every component renders against `--optare-*` CSS variables you can override.
+
+## SSR
+
+Resolve the config on the server and hand it to the provider as `bootstrap` to
+skip the client-side fetch:
+
+```tsx
+import { resolveOptareConfig } from "@optare/react";
+
+const bootstrap = await resolveOptareConfig({ publishableKey: process.env.OPTARE_PK! });
+// ...serialize `bootstrap` into the page, then:
+<OptareProvider publishableKey={pk} bootstrap={bootstrap}>{children}</OptareProvider>
+```
+
+## API
+
+### `<OptareProvider>`
+
+| prop | type | notes |
+|---|---|---|
+| `publishableKey` | `string` | required |
+| `bootstrap` | `OptareBootstrap` | pre-resolved config; skips the network |
+| `baseURL` | `string` | override the auth API origin (self-hosted / preview) |
+| `configURL` | `string` | where `GET /api/public/config` lives; defaults to `baseURL` then the hosted origin |
+| `fetch` | `typeof fetch` | custom fetch (tests, RN) |
+| `loadingFallback` / `errorFallback` | `ReactNode` \| `(err, retry) => ReactNode` | optional gates; default is optimistic (render children, expose `status`) |
+
+### Hooks
+
+- `useOptare()` — `{ status, error, bootstrap, branding, project, cssVars, auth, retry }`
+- `useOptareAuth()` — the better-auth React client (throws until `status === "ready"`)
+- `useSession()` — `{ data, user, isPending, isAuthenticated, error, refetch }`
+- `useUser()` — the current user or `null`
+- `useSignOut()` — `{ signOut, isPending, error }`
+- `useActiveOrganization()` — `{ activeOrganizationId, setActive, isPending }`
+- `useBranding()` / `useOptareConfig()`
+
+### Components
+
+- `<SignIn />` — email + password, optional magic-link path, 2FA-challenge
+  callback (`onTwoFactor`), `onSuccess` / `redirectTo`.
+- `<SignUp />` — name + email + password with a strength meter; the landing
+  organization is decided server-side from the publishable key (F6).
+  `onVerificationRequired` fires when an email must be confirmed first.
+- `<AccountButton />` — avatar + dropdown (profile slot, sign out); renders
+  `signInSlot` (or nothing) when signed out.
+
+### Theming
+
+`brandingToCssVars(branding)` returns the `--optare-*` map the provider applies.
+All colour/length values from branding are sanitised (`safeColor`, `safeLength`)
+so a project's branding string can never inject CSS. Override any variable in
+your own stylesheet, or pass `style` / `className` to a component.
+
+## Server-side
+
+`sk_live_` management calls and offline JWT verification are **not** in this
+package — use [`@optare/node`](../node).
+
+## Versioning
+
+See [`docs/SDK_VERSIONING.md`](../../docs/SDK_VERSIONING.md). Pre-1.0: minor =
+breaking, patch = fixes.