@palbase/web 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Palbase
+
+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,292 @@
+# @palbase/web
+
+The Palbase client SDK for web. One import, one entry point: **`pb`**.
+
+`@palbase/web` is typed against **your own backend**. You run `palbase web link` once, it
+generates a `palbe.gen.ts` file from your deployed endpoints, and from then on
+`pb.todos.create(...)`, `pb.rooms.list(...)` and friends are fully typed — request
+shapes, response shapes and per-endpoint errors, all inferred from the backend you
+shipped. Auth, feature flags, realtime and analytics come built in.
+
+```ts
+import { pb } from '@palbase/web';
+
+await pb.auth.signIn({ email, password });
+const todo = await pb.todos.create({ title: 'Ship it' }); // typed by your backend
+```
+
+---
+
+## Install
+
+```bash
+npm i @palbase/web
+```
+
+Then link your project and generate the typed client:
+
+```bash
+npx palbase web link
+```
+
+`palbase web link` writes `palbe.gen.ts` (the typed client config + namespaces),
+wires `import './palbe.gen';` into your app entry, and adds a `predev`/`prebuild`
+hook that keeps the types in sync. **Commit `palbe.gen.ts`** — it's the typed
+client your app imports, not a build artifact.
+
+The generated file calls `__configure(...)` with your project's URL and anon API
+key at module load, so importing it once at startup is all the setup there is.
+If you forget to import it, every `pb` call throws a guided `BackendError`
+(`kind: 'notConfigured'`).
+
+> Regenerate any time your backend changes: `npx palbase types` (or just run
+> `dev`/`build` — the hook does it for you).
+
+---
+
+## Calling your backend
+
+Codegen turns each backend controller into a typed namespace on `pb`. A
+controller method `todos.create` becomes `pb.todos.create(input)`; a top-level
+endpoint `getHello` becomes `pb.getHello()`. Path params come first, the request
+body/query second:
+
+```ts
+import { pb } from '@palbase/web';
+
+// POST /todos/create  — body typed, response typed
+const todo = await pb.todos.create({ title: 'Buy milk', done: false });
+
+// GET /todos/{id}     — path param, then options
+const one = await pb.todos.get('todo_123');
+
+// GET /todos          — typed query object
+const list = await pb.todos.list({ limit: 20, done: false });
+```
+
+### Escape hatches
+
+When you need to call an endpoint that isn't in the generated types yet (or do a
+raw multipart upload), use `pb.call` and `pb.upload`:
+
+```ts
+// Untyped POST — you supply the response type
+const result = await pb.call<{ ok: boolean }>('todos/archive', { id: 'todo_123' });
+
+// Multipart upload with progress
+const uploaded = await pb.upload<{ url: string }>('files/avatar', {
+  file: blob,
+  filename: 'avatar.png',
+  onProgress: ({ sent, total }) => console.log(sent / total),
+});
+```
+
+---
+
+## Auth
+
+`pb.auth` is the full authentication surface — email/password, OTP, magic links,
+OAuth, password reset, email verification:
+
+```ts
+await pb.auth.signUp({ email: 'a@b.com', password: 'secret123' });
+const { user, session } = await pb.auth.signIn({ email: 'a@b.com', password: 'secret123' });
+await pb.auth.signOut();
+
+// React to session changes
+const unsub = pb.auth.onAuthStateChange((state) => {
+  console.log(state.status); // 'signedIn' | 'signedOut'
+});
+
+pb.auth.isSignedIn;     // boolean (token presence)
+pb.auth.currentUser;    // AuthUser | null
+await pb.auth.refreshUser();   // re-fetch the profile (e.g. emailVerified flip)
+```
+
+Phone OTP, magic links and OAuth:
+
+```ts
+await pb.auth.signInWithOTP({ phone: '+1555…' });
+await pb.auth.verifyOTP({ phone: '+1555…', token: '123456' });
+
+await pb.auth.signInWithMagicLink('a@b.com');
+
+// Redirects the browser to the provider; completes via @palbase/web/next (see below)
+await pb.auth.signInWithOAuth({ provider: 'google', redirectTo: '/auth/callback' });
+```
+
+---
+
+## Feature flags
+
+`pb.flags` polls and caches your project's feature flags (auth-aware — flags
+re-evaluate when the user signs in/out):
+
+```ts
+if (pb.flags.isEnabled('new-checkout')) { /* … */ }
+
+pb.flags.getString('theme', 'light');
+pb.flags.getInt('max-items', 10);
+
+await pb.flags.getVariant('pricing-experiment'); // multivariate → variant name | null
+
+const off = pb.flags.onChange(() => console.log('flags changed', pb.flags.all()));
+```
+
+---
+
+## Realtime
+
+`pb.realtime` multiplexes every subscription over one auto-reconnecting
+WebSocket. Channels are client-only (browser):
+
+```ts
+const room = pb.realtime.channel('room:42');
+
+const sub = room.on('message', (payload) => {
+  console.log('got', payload);
+});
+
+room.send('message', { text: 'hello' }); // broadcast to other subscribers
+
+sub.cancel(); // last cancel on a channel leaves it
+```
+
+Connection status is observable (`pb.realtime.status.state` /
+`pb.realtime.status.onChange(...)`).
+
+---
+
+## Analytics
+
+`pb.analytics` buffers events client-side and flushes in batches. It manages an
+anonymous distinct id and stitches it to the user on sign-in automatically:
+
+```ts
+pb.analytics.capture('checkout_started', { plan: 'pro' });
+pb.analytics.screen('Dashboard');
+pb.analytics.identify('user_123', { email: 'a@b.com' });
+await pb.analytics.flush();      // force-send buffered events
+pb.analytics.setOptOut(true);    // GDPR opt-out (drops pending + future)
+```
+
+---
+
+## Errors
+
+Every failing call throws a `BackendError`. Inspect `kind` (a coarse category)
+and `code` (the server's machine code):
+
+```ts
+import { pb, BackendError, isBackendError } from '@palbase/web';
+
+try {
+  await pb.todos.create({ title: '' });
+} catch (e) {
+  if (isBackendError(e)) {
+    e.kind;       // 'validation' | 'unauthorized' | 'rateLimited' | 'notConfigured'
+                  //   | 'network' | 'server' | 'decode'
+    e.code;       // server machine code, e.g. 'invalid_input'
+    e.status;     // HTTP status
+    e.fields;     // field-level validation errors (when kind === 'validation')
+    e.retryAfter; // seconds (when kind === 'rateLimited')
+  }
+}
+```
+
+Generated code also gives you **typed per-endpoint error classes** (e.g.
+`RoomsCreateRoomLockedError`) with typed `.data`, so you can `instanceof`-match the
+specific failures a given endpoint documents.
+
+---
+
+## Next.js — `@palbase/web/next`
+
+The Next.js App Router adapter shares one session cookie between the browser and
+the server so Server Components, Route Handlers and middleware all see the same
+auth state.
+
+**1. Configure the browser client** (a client provider/component):
+
+```tsx
+'use client';
+import { setupPalbeNext } from '@palbase/web/next/client';
+import { useEffect } from 'react';
+
+export function PalbeProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => { setupPalbeNext(); }, []);
+  return <>{children}</>;
+}
+```
+
+`setupPalbeNext()` swaps in `cookieSessionStorage` so the session is written to a
+cookie the server can read.
+
+**2. Refresh the session in middleware** (required for session-bearing RSC apps):
+
+```ts
+// middleware.ts
+import './palbe.gen';
+import { palbeMiddleware } from '@palbase/web/next';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  return palbeMiddleware(request);
+}
+
+export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+```
+
+**3. Read data in Server Components** with `pbServer()` — a per-request,
+session-isolated client:
+
+```tsx
+import { pbServer } from '@palbase/web/next';
+
+export default async function Page() {
+  const pb = await pbServer();
+  const todos = await pb.todos.list({ limit: 20 });
+  return <TodoList items={todos} />;
+}
+```
+
+**4. Complete OAuth** with a callback route handler:
+
+```ts
+// app/auth/callback/route.ts
+import { handleAuthCallback } from '@palbase/web/next';
+export const GET = handleAuthCallback({ defaultNext: '/' });
+```
+
+---
+
+## React — `@palbase/web/react`
+
+Thin, concurrent-safe hooks over the observable `pb.*` facades. `react` is an
+**optional** peer dependency — importing `@palbase/web` never pulls React; only
+`@palbase/web/react` does.
+
+```tsx
+'use client';
+import { useUser, useSession, useFlag, useFlags, useChannel } from '@palbase/web/react';
+
+function Profile() {
+  const user = useUser();                 // AuthUser | null, re-renders on auth change
+  const { signedIn } = useSession();      // { signedIn, user }
+  const dark = useFlag('dark-mode', false);
+  const flags = useFlags();               // whole flag set
+
+  // Subscribe to a realtime event for the component's lifetime
+  const { status } = useChannel('room:42', 'message', (payload) => {
+    console.log(payload);
+  });
+
+  return signedIn ? <span>{user?.email}</span> : <SignInButton />;
+}
+```
+
+---
+
+## License
+
+MIT