@pylonsync/client 0.3.267

package/README.md

@@ -0,0 +1,125 @@
+# @pylonsync/client
+
+Drop-in React components for Pylon auth. Clerk-style API, wired to the
+existing `/api/auth/*` surface — magic link, password, and OAuth all
+work with zero config.
+
+```bash
+pnpm add @pylonsync/client
+```
+
+```tsx
+import { init } from "@pylonsync/react";
+import {
+	SignIn,
+	SignedIn,
+	SignedOut,
+	UserButton,
+} from "@pylonsync/client";
+import "@pylonsync/client/theme.css"; // optional default theme
+
+init(); // once at app boot
+
+export function App() {
+	return (
+		<header>
+			<SignedIn>
+				<UserButton showName afterSignOutUrl="/" />
+			</SignedIn>
+			<SignedOut>
+				<SignIn afterSignInUrl="/dashboard" />
+			</SignedOut>
+		</header>
+	);
+}
+```
+
+## Components
+
+**Auth surfaces**
+- `<SignIn />` — magic link + password + OAuth, two-step code flow.
+- `<SignUp />` — password registration with email validation.
+- `<ForgotPassword />` — request a reset link.
+- `<ResetPassword token={...} />` — landing page for the reset email.
+- `<UserButton />` — avatar dropdown with sign-out.
+- `<SignOutButton />` — bare sign-out trigger.
+- `<UserProfile />` — account management: identity, password, sessions, API keys.
+
+**Org surfaces**
+- `<OrganizationSwitcher />` — list + switch + inline create.
+- `<CreateOrganization />` — standalone create form.
+- `<InviteMembers />` — invite by email, pending list, role mgmt.
+- `<AcceptInvite token={...} />` — landing page for invite emails.
+
+**Integrations**
+- `<ConnectAccount name="slack" />` — start OAuth for a `defineConnection(...)`.
+- `<ChatBot fn="chat" />` — streaming UI over a server-side `ctx.llm` handler.
+
+**Files**
+- `<FileUpload />` — drag-and-drop, multi-file, server-side via `/api/files/upload`.
+
+**Data scaffolds**
+- `<EntityList entity columns where orderBy />` — reactive table.
+- `<EntityForm entity fields row onSubmitted />` — create + edit form.
+
+**Control components**
+- `<SignedIn>` / `<SignedOut>` — auth render-gates.
+- `<InOrg>` / `<NoOrg>` — active-org render-gates.
+- `<HasRole role="owner">` — role render-gate (single or array).
+- `<Protect admin>` / `<Protect predicate={...}>` — predicate gate.
+- `<RedirectToSignIn signInUrl="/sign-in" />` — client redirect.
+
+**Routing**
+- `<Router routes={...} />` — SPA router with nested layouts via `<Outlet />`.
+- `<Link href />` — SPA link (intercepts left-click, lets cmd-click through).
+- `useRouter()` / `useParams()` / `useSearchParams()` / `usePathname()`.
+
+```tsx
+<Router routes={[
+  { path: "/", component: Home },
+  {
+    path: "/app",
+    component: AppLayout, // contains an <Outlet />
+    requireAuth: true,
+    children: [
+      { path: "/", component: Dashboard },
+      { path: "/posts/:id", component: PostDetail },
+    ],
+  },
+]} />
+```
+
+**Hooks**
+- `useAuth()` — `{isSignedIn, userId, tenantId, isAdmin, session, signOut, ...}`.
+
+## Orgs
+
+Pylon ships org/membership endpoints (`/api/auth/orgs`) when your
+manifest declares `Org` and `OrgMember` entities. `<OrganizationSwitcher />`
+reads + writes through those endpoints — no app-side glue needed.
+
+```tsx
+<OrganizationSwitcher
+	onSwitched={(orgId) => router.push("/")}
+	onCreated={(org) => analytics.track("org_created", org)}
+/>
+```
+
+## Theming
+
+All styling references CSS variables namespaced under `--pylon-*`. Import
+`@pylonsync/client/theme.css` for sensible light/dark defaults, or define
+the variables yourself.
+
+```css
+:root {
+	--pylon-ink: #1d4ed8;
+	--pylon-paper: #f8fafc;
+}
+```
+
+## OAuth providers
+
+`<SignIn />` queries `/api/auth/providers` and renders a button per
+enabled provider. Configure providers via env vars on the Pylon process
+(e.g. `PYLON_OAUTH_GOOGLE_CLIENT_ID` / `PYLON_OAUTH_GOOGLE_CLIENT_SECRET`).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pylonsync/client",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.267",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./theme.css": "./src/theme.css"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@pylonsync/react": "0.3.267",
+    "@pylonsync/sync": "0.3.267",
+    "clsx": "^2.1.1"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0"
+  }
+}

package/src/components/AcceptInvite.tsx

@@ -0,0 +1,160 @@
+"use client";
+import React from "react";
+
+import { type ReactNode, useEffect, useState } from "react";
+import { useAuth } from "../hooks/useAuth";
+import { acceptInvite, ApiError } from "../lib/api";
+import { cn } from "../lib/cn";
+
+export interface AcceptInviteProps {
+	/**
+	 * The invite token. Pulled from the email link's `?token=` param
+	 * by the consuming page. Falls back to `window.location.search`
+	 * when omitted.
+	 */
+	token?: string;
+	/** Where to send the user after a successful accept. */
+	afterAcceptUrl?: string;
+	/** Where to send a signed-out user so they can sign in / sign up first. */
+	signInUrl?: string;
+	/** Optional callback once accept lands. Receives `{org_id, role}`. */
+	onAccepted?: (result: { org_id: string; role: string }) => void;
+	/** Override the headline copy. */
+	title?: ReactNode;
+	className?: string;
+}
+
+type State =
+	| { kind: "idle" }
+	| { kind: "accepting" }
+	| { kind: "accepted"; orgId: string; role: string }
+	| { kind: "error"; message: string };
+
+/**
+ * Drop-in landing surface for `/accept-invite?token=…`. Reads the token
+ * from props or the URL, calls `POST /api/auth/invites/:token/accept`,
+ * and lights up org membership when the request succeeds.
+ *
+ * Signed-out users see a "sign in to accept" prompt that bounces through
+ * `signInUrl` with the current href as `?next=` so they end up back on
+ * this page with the token preserved.
+ */
+export function AcceptInvite({
+	token: tokenProp,
+	afterAcceptUrl,
+	signInUrl = "/sign-in",
+	onAccepted,
+	title = "Accept invite",
+	className,
+}: AcceptInviteProps) {
+	const { isSignedIn, refresh } = useAuth();
+	const [state, setState] = useState<State>({ kind: "idle" });
+
+	const token =
+		tokenProp ??
+		(typeof window !== "undefined"
+			? new URLSearchParams(window.location.search).get("token")
+			: null) ??
+		undefined;
+
+	useEffect(() => {
+		if (!token || !isSignedIn) return;
+		// Auto-accept once we have both a token and a session. Saves the
+		// "click accept" step that doesn't add any safety — the user is
+		// already on the URL they were emailed.
+		setState({ kind: "accepting" });
+		(async () => {
+			try {
+				const result = await acceptInvite(token);
+				setState({ kind: "accepted", orgId: result.org_id, role: result.role });
+				onAccepted?.(result);
+				// Refresh the cached session so the new tenantId / role is
+				// visible in useAuth() immediately. Without this the user
+				// would need to reload to see the org switcher pick up the
+				// membership.
+				void refresh();
+				if (afterAcceptUrl && typeof window !== "undefined") {
+					window.location.assign(afterAcceptUrl);
+				}
+			} catch (err) {
+				setState({ kind: "error", message: messageFromError(err) });
+			}
+		})();
+	}, [token, isSignedIn, afterAcceptUrl, onAccepted, refresh]);
+
+	return (
+		<div
+			className={cn(
+				"mx-auto w-full max-w-sm space-y-4 rounded-xl border border-[var(--pylon-rule,#e5e7eb)] bg-[var(--pylon-paper,#ffffff)] p-7 text-center shadow-sm",
+				className,
+			)}
+		>
+			<h2 className="text-lg font-semibold tracking-tight text-[var(--pylon-ink,#0a0a0a)]">
+				{title}
+			</h2>
+			{!token ? (
+				<p className="text-sm text-[var(--pylon-ink-2,#52525b)]">
+					This page needs an invite token. Check the email link you
+					were sent.
+				</p>
+			) : !isSignedIn ? (
+				<SignInPrompt signInUrl={signInUrl} />
+			) : state.kind === "idle" || state.kind === "accepting" ? (
+				<p className="text-sm text-[var(--pylon-ink-2,#52525b)]">
+					Joining…
+				</p>
+			) : state.kind === "accepted" ? (
+				<p className="text-sm text-[var(--pylon-ink-2,#52525b)]">
+					You're in. Welcome to the team.
+				</p>
+			) : (
+				<p className="rounded-md border border-[var(--pylon-error-rule,#fecaca)] bg-[var(--pylon-error-bg,#fef2f2)] px-3 py-2 text-xs text-[var(--pylon-error-ink,#b91c1c)]">
+					{state.message}
+				</p>
+			)}
+		</div>
+	);
+}
+
+function SignInPrompt({ signInUrl }: { signInUrl: string }) {
+	const next =
+		typeof window !== "undefined" && window.location?.href
+			? `?next=${encodeURIComponent(window.location.href)}`
+			: "";
+	return (
+		<>
+			<p className="text-sm text-[var(--pylon-ink-2,#52525b)]">
+				Sign in to accept your invite. We'll bring you right back.
+			</p>
+			<a
+				href={`${signInUrl}${next}`}
+				className="inline-flex items-center justify-center rounded-md bg-[var(--pylon-ink,#0a0a0a)] px-4 py-2 text-sm font-medium text-[var(--pylon-paper,#ffffff)]"
+			>
+				Sign in
+			</a>
+		</>
+	);
+}
+
+function messageFromError(err: unknown): string {
+	if (err instanceof ApiError) {
+		switch (err.code) {
+			case "INVITE_NOT_FOUND":
+				return "This invite link is no longer valid.";
+			case "INVITE_EXPIRED":
+				return "This invite has expired. Ask for a fresh one.";
+			case "ALREADY_ACCEPTED":
+				return "You've already accepted this invite.";
+			case "WRONG_EMAIL":
+				return "This invite was for a different email. Sign in with the account that received it.";
+			case "ALREADY_MEMBER":
+				return "You're already a member of this org.";
+			case "NO_EMAIL":
+				return "Your account has no email on file — add one and try again.";
+			default:
+				return err.message;
+		}
+	}
+	if (err instanceof Error) return err.message;
+	return "Something went wrong accepting the invite.";
+}

package/src/components/ChatBot.tsx

@@ -0,0 +1,228 @@
+"use client";
+import React from "react";
+
+import {
+	type FormEvent,
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+import { db } from "@pylonsync/react";
+import { cn } from "../lib/cn";
+
+export interface ChatMessage {
+	role: "user" | "assistant" | "system";
+	content: string;
+}
+
+export interface ChatBotProps {
+	/**
+	 * Name of the server-side function that drives the model. It runs
+	 * `ctx.llm.*` and emits its response as SSE chunks via
+	 * `db.streamFn`. The handler receives `{ messages, ...extra }`.
+	 */
+	fn: string;
+	/** Extra args merged into every call (e.g., `{model: "haiku"}`). */
+	extraArgs?: Record<string, unknown>;
+	/** System prompt prepended to every turn. */
+	systemPrompt?: string;
+	/** Initial messages to display (e.g., a welcome from the assistant). */
+	initialMessages?: ChatMessage[];
+	/** Placeholder shown in the input. */
+	placeholder?: string;
+	/** Header copy. */
+	title?: ReactNode;
+	className?: string;
+}
+
+/**
+ * Drop-in chat UI for a server-side LLM handler. Wires the assistant
+ * turn to `db.streamFn(fn, { messages })`; each yielded chunk is parsed
+ * as a JSON event of the shape `{type: "text", delta: string}` (the
+ * default emitted by the framework's streaming helpers). Plain string
+ * chunks are also accepted so this works with apps that just yield
+ * `event.delta` directly.
+ *
+ * Server-side authoring (5 lines):
+ * ```ts
+ * export default action({
+ *   args: { messages: v.array(v.object({ role: v.string(), content: v.string() })) },
+ *   async handler(ctx, { messages }) {
+ *     return ctx.llm.streamMessage({ model: "claude-haiku", messages });
+ *   },
+ * });
+ * ```
+ */
+export function ChatBot({
+	fn,
+	extraArgs,
+	systemPrompt,
+	initialMessages,
+	placeholder = "Ask anything…",
+	title = "Assistant",
+	className,
+}: ChatBotProps) {
+	const [messages, setMessages] = useState<ChatMessage[]>(
+		initialMessages ?? [],
+	);
+	const [draft, setDraft] = useState("");
+	const [streaming, setStreaming] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const scrollerRef = useRef<HTMLDivElement | null>(null);
+
+	// Keep the latest message visible without yanking scroll if the user
+	// has manually scrolled up. Simple heuristic: only auto-scroll when
+	// the user is already at the bottom.
+	useEffect(() => {
+		const el = scrollerRef.current;
+		if (!el) return;
+		const nearBottom =
+			el.scrollHeight - el.scrollTop - el.clientHeight < 80;
+		if (nearBottom) el.scrollTop = el.scrollHeight;
+	}, [messages]);
+
+	const send = useCallback(
+		async (e?: FormEvent) => {
+			e?.preventDefault();
+			const text = draft.trim();
+			if (!text || streaming) return;
+			setError(null);
+
+			const userTurn: ChatMessage = { role: "user", content: text };
+			const turns: ChatMessage[] = systemPrompt
+				? [{ role: "system", content: systemPrompt }, ...messages, userTurn]
+				: [...messages, userTurn];
+
+			setMessages((prev) => [
+				...prev,
+				userTurn,
+				{ role: "assistant", content: "" },
+			]);
+			setDraft("");
+			setStreaming(true);
+
+			try {
+				const args = { messages: turns, ...(extraArgs ?? {}) };
+				let acc = "";
+				for await (const chunk of db.streamFn(fn, args)) {
+					const delta = extractDelta(chunk);
+					if (!delta) continue;
+					acc += delta;
+					setMessages((prev) => {
+						const next = prev.slice();
+						const idx = next.length - 1;
+						if (idx >= 0 && next[idx]?.role === "assistant") {
+							next[idx] = { role: "assistant", content: acc };
+						}
+						return next;
+					});
+				}
+			} catch (err) {
+				setError(err instanceof Error ? err.message : "Stream failed.");
+				setMessages((prev) => prev.slice(0, -1));
+			} finally {
+				setStreaming(false);
+			}
+		},
+		[draft, extraArgs, fn, messages, streaming, systemPrompt],
+	);
+
+	function onKeyDown(e: React.KeyboardEvent<HTMLTextAreaElement>) {
+		if (e.key === "Enter" && !e.shiftKey) {
+			e.preventDefault();
+			void send();
+		}
+	}
+
+	return (
+		<div
+			className={cn(
+				"mx-auto flex h-[480px] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-[var(--pylon-rule,#e5e7eb)] bg-[var(--pylon-paper,#ffffff)] shadow-sm",
+				className,
+			)}
+		>
+			<div className="border-b border-[var(--pylon-rule,#e5e7eb)] px-4 py-2.5">
+				<p className="text-sm font-semibold tracking-tight text-[var(--pylon-ink,#0a0a0a)]">
+					{title}
+				</p>
+			</div>
+			<div
+				ref={scrollerRef}
+				className="flex-1 space-y-3 overflow-y-auto px-4 py-4"
+			>
+				{messages.length === 0 ? (
+					<p className="text-center text-xs text-[var(--pylon-ink-3,#71717a)]">
+						{placeholder}
+					</p>
+				) : null}
+				{messages.map((m, i) => (
+					<MessageBubble key={i} message={m} />
+				))}
+				{error ? (
+					<p className="rounded-md border border-[var(--pylon-error-rule,#fecaca)] bg-[var(--pylon-error-bg,#fef2f2)] px-3 py-2 text-xs text-[var(--pylon-error-ink,#b91c1c)]">
+						{error}
+					</p>
+				) : null}
+			</div>
+			<form
+				onSubmit={send}
+				className="flex items-end gap-2 border-t border-[var(--pylon-rule,#e5e7eb)] p-3"
+			>
+				<textarea
+					value={draft}
+					onChange={(e) => setDraft(e.target.value)}
+					onKeyDown={onKeyDown}
+					placeholder={placeholder}
+					rows={1}
+					className="flex-1 resize-none rounded-md border border-[var(--pylon-rule,#e5e7eb)] bg-[var(--pylon-paper,#ffffff)] px-3 py-2 text-sm text-[var(--pylon-ink,#0a0a0a)] placeholder:text-[var(--pylon-ink-3,#a1a1aa)] focus:border-[var(--pylon-ink,#0a0a0a)] focus:outline-none"
+				/>
+				<button
+					type="submit"
+					disabled={streaming || !draft.trim()}
+					className="rounded-md bg-[var(--pylon-ink,#0a0a0a)] px-3 py-2 text-sm font-medium text-[var(--pylon-paper,#ffffff)] transition-opacity hover:opacity-90 disabled:opacity-60"
+				>
+					{streaming ? "…" : "Send"}
+				</button>
+			</form>
+		</div>
+	);
+}
+
+function MessageBubble({ message }: { message: ChatMessage }) {
+	const isUser = message.role === "user";
+	return (
+		<div className={cn("flex", isUser ? "justify-end" : "justify-start")}>
+			<div
+				className={cn(
+					"max-w-[80%] whitespace-pre-wrap rounded-2xl px-3 py-2 text-sm",
+					isUser
+						? "bg-[var(--pylon-ink,#0a0a0a)] text-[var(--pylon-paper,#ffffff)]"
+						: "bg-[var(--pylon-paper-2,#f4f4f5)] text-[var(--pylon-ink,#0a0a0a)]",
+				)}
+			>
+				{message.content || (
+					<span className="text-[var(--pylon-ink-3,#71717a)]">…</span>
+				)}
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Normalise streamed chunks. The framework's streaming helpers emit
+ * `{type: "text", delta: string}` JSON; apps writing raw streams may
+ * just yield strings. Anything else is ignored — defensive parsing
+ * keeps the UI from blowing up on tool-call events the chatbot doesn't
+ * render yet.
+ */
+function extractDelta(chunk: unknown): string {
+	if (typeof chunk === "string") return chunk;
+	if (chunk && typeof chunk === "object") {
+		const obj = chunk as { type?: string; delta?: unknown; text?: unknown };
+		if (typeof obj.delta === "string") return obj.delta;
+		if (obj.type === "text" && typeof obj.text === "string") return obj.text;
+	}
+	return "";
+}

package/src/components/ConnectAccount.tsx

@@ -0,0 +1,119 @@
+"use client";
+import React from "react";
+
+import { type ReactNode, useState } from "react";
+import { useAuth } from "../hooks/useAuth";
+import { ApiError, connectionAuthUrl } from "../lib/api";
+import { cn } from "../lib/cn";
+
+export interface ConnectAccountProps {
+	/**
+	 * Name of the connection in the manifest (matches the `name` you
+	 * passed to `defineConnection({...})`). NOT the OAuth provider id.
+	 */
+	name: string;
+	/**
+	 * URL the OAuth provider sends the user back to after consent.
+	 * Defaults to the current page so the user lands on the same screen
+	 * with the new connection already in place.
+	 */
+	postRedirect?: string;
+	/** Optional label override. Default: "Connect <name>". */
+	label?: ReactNode;
+	/**
+	 * If true, render an "outline" style button instead of the solid
+	 * primary. Useful when the connect-button sits next to a primary
+	 * CTA.
+	 */
+	variant?: "primary" | "outline";
+	className?: string;
+}
+
+/**
+ * Drop-in button that starts an OAuth flow for a connection defined via
+ * `defineConnection(...)` in the manifest. Hits
+ * `POST /api/connections/<name>/auth-url` and navigates the browser to
+ * the returned URL; the provider redirects back to
+ * `/api/connections/<name>/callback`, which stores the encrypted token
+ * row and bounces to `postRedirect` (default: current page).
+ *
+ * Renders nothing for signed-out users — connections need an
+ * authenticated identity to bind the access token to.
+ */
+export function ConnectAccount({
+	name,
+	postRedirect,
+	label,
+	variant = "primary",
+	className,
+}: ConnectAccountProps) {
+	const { isSignedIn } = useAuth();
+	const [pending, setPending] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	if (!isSignedIn) return null;
+
+	async function onClick() {
+		setError(null);
+		setPending(true);
+		try {
+			const redirect =
+				postRedirect ??
+				(typeof window !== "undefined" ? window.location.href : undefined);
+			const { url } = await connectionAuthUrl(name, redirect);
+			if (typeof window !== "undefined") {
+				window.location.assign(url);
+			}
+		} catch (err) {
+			setError(messageFromError(err));
+			setPending(false);
+		}
+	}
+
+	return (
+		<span className={cn("inline-flex flex-col gap-1.5", className)}>
+			<button
+				type="button"
+				onClick={onClick}
+				disabled={pending}
+				className={cn(
+					"inline-flex items-center justify-center gap-2 rounded-md px-3 py-2 text-sm font-medium transition-colors disabled:opacity-60",
+					variant === "primary"
+						? "bg-[var(--pylon-ink,#0a0a0a)] text-[var(--pylon-paper,#ffffff)] hover:opacity-90"
+						: "border border-[var(--pylon-rule,#e5e7eb)] bg-[var(--pylon-paper,#ffffff)] text-[var(--pylon-ink,#0a0a0a)] hover:bg-[var(--pylon-paper-2,#f4f4f5)]",
+				)}
+			>
+				{pending ? "…" : (label ?? `Connect ${capitalize(name)}`)}
+			</button>
+			{error ? (
+				<span className="text-[11px] text-[var(--pylon-error-ink,#b91c1c)]">
+					{error}
+				</span>
+			) : null}
+		</span>
+	);
+}
+
+function capitalize(s: string): string {
+	if (!s) return "";
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function messageFromError(err: unknown): string {
+	if (err instanceof ApiError) {
+		switch (err.code) {
+			case "CONNECTION_UNKNOWN":
+				return "This connection isn't defined in the app manifest.";
+			case "PROVIDER_NOT_CONFIGURED":
+				return "Connection provider isn't configured on the server.";
+			case "ENCRYPTION_REQUIRED":
+				return "Connection storage needs PYLON_ENCRYPTION_KEY set.";
+			case "CONNECTIONS_NOT_CONFIGURED":
+				return "No connections are defined in this app yet.";
+			default:
+				return err.message;
+		}
+	}
+	if (err instanceof Error) return err.message;
+	return "Couldn't start the connection flow.";
+}