@pylonsync/next 0.2.8

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pylonsync/next",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.2.8",
+  "type": "module",
+  "description": "Next.js helpers for Pylon — cookie-based auth gate, server-side session helpers, and reusable client hooks.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./proxy": "./src/proxy.ts",
+    "./server": "./src/server.ts",
+    "./client": "./src/client.ts",
+    "./auth": "./src/auth.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0 <17.0.0",
+    "react": ">=18.0.0 <20.0.0",
+    "react-dom": ">=18.0.0 <20.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,159 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { ApiError, api } from "./client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Session = {
+	token: string;
+	user_id: string;
+	expires_at: number;
+};
+
+export type OAuthProvider = {
+	provider: "google" | "github";
+	auth_url: string;
+};
+
+// ---------------------------------------------------------------------------
+// Direct API helpers
+//
+// Each one wraps a Pylon `/api/auth/*` endpoint. They're plain async
+// functions so callers can compose them however they want — see the
+// hooks below for the typical "form submit" pattern.
+// ---------------------------------------------------------------------------
+
+export async function signupWithPassword(input: {
+	email: string;
+	password: string;
+	displayName?: string;
+}): Promise<Session> {
+	return api<Session>("/api/auth/password/register", {
+		method: "POST",
+		body: JSON.stringify(input),
+	});
+}
+
+export async function loginWithPassword(input: {
+	email: string;
+	password: string;
+}): Promise<Session> {
+	return api<Session>("/api/auth/password/login", {
+		method: "POST",
+		body: JSON.stringify(input),
+	});
+}
+
+/**
+ * Sign the user out. Best-effort — even if the server-side revoke
+ * fails (e.g. session already expired) the clearing Set-Cookie comes
+ * back so the browser drops the cookie either way.
+ */
+export async function logout(): Promise<void> {
+	try {
+		await api("/api/auth/session", { method: "DELETE" });
+	} catch {
+		// ignore — token may already be expired/invalid
+	}
+}
+
+export async function listOAuthProviders(): Promise<OAuthProvider[]> {
+	return api<OAuthProvider[]>("/api/auth/providers");
+}
+
+/**
+ * Kick off an OAuth login. Browser navigates to Pylon's GET login
+ * route, which 302s to the provider, which 302s back to Pylon's GET
+ * callback (Set-Cookie + 302 to PYLON_DASHBOARD_URL). The OAuth code
+ * never enters JS, so XSS in the dashboard can't intercept the
+ * handshake.
+ */
+export function startOAuthLogin(provider: OAuthProvider["provider"]): void {
+	window.location.href = `/api/auth/login/${provider}?redirect=1`;
+}
+
+export async function sendVerificationEmail(): Promise<{
+	sent: boolean;
+	email: string;
+	dev_code?: string;
+}> {
+	return api("/api/auth/email/send-verification", { method: "POST" });
+}
+
+export async function verifyEmail(
+	code: string,
+): Promise<{ verified: boolean; emailVerified: string }> {
+	return api("/api/auth/email/verify", {
+		method: "POST",
+		body: JSON.stringify({ code }),
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Hooks — form-shaped wrappers that handle the common busy/error state
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the enabled OAuth providers on mount. Returns an empty array
+ * until the request resolves, so callers can render the password form
+ * unconditionally and conditionally show the OAuth button row when
+ * `providers.length > 0`.
+ */
+export function useOAuthProviders(): OAuthProvider[] {
+	const [providers, setProviders] = useState<OAuthProvider[]>([]);
+	useEffect(() => {
+		listOAuthProviders()
+			.then(setProviders)
+			.catch(() => {});
+	}, []);
+	return providers;
+}
+
+/**
+ * Manage busy + error state for an auth-shaped async submission.
+ * Wraps the provided `fn` so callers don't have to write
+ * `try/catch/finally` around every form submit.
+ *
+ * ```tsx
+ * const { error, busy, submit } = useAuthSubmit(loginWithPassword);
+ *
+ * async function onSubmit(e: React.FormEvent) {
+ *   e.preventDefault();
+ *   const ok = await submit({ email, password });
+ *   if (ok) router.push("/dashboard");
+ * }
+ * ```
+ *
+ * `submit` returns `undefined` on failure (error is set internally),
+ * the awaited resolution otherwise. `setError` is exposed for the
+ * rare case a page wants to clear the error programmatically.
+ */
+export function useAuthSubmit<I, O>(fn: (input: I) => Promise<O>): {
+	error: string | null;
+	busy: boolean;
+	submit: (input: I) => Promise<O | undefined>;
+	setError: (e: string | null) => void;
+} {
+	const [error, setError] = useState<string | null>(null);
+	const [busy, setBusy] = useState(false);
+	const submit = useCallback(
+		async (input: I): Promise<O | undefined> => {
+			setError(null);
+			setBusy(true);
+			try {
+				return await fn(input);
+			} catch (err) {
+				if (err instanceof ApiError) setError(err.message);
+				else setError(err instanceof Error ? err.message : String(err));
+				return undefined;
+			} finally {
+				setBusy(false);
+			}
+		},
+		[fn],
+	);
+	return { error, busy, submit, setError };
+}

package/src/client.ts

@@ -0,0 +1,80 @@
+"use client";
+
+/**
+ * Thrown by the API client on any non-2xx response. Carries the wire
+ * `code` (e.g. `OAUTH_INVALID_STATE`) so UI can branch on specific
+ * failures instead of string-matching the message.
+ */
+export class ApiError extends Error {
+	constructor(
+		public status: number,
+		public code: string,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+/**
+ * Options for {@link createPylonClient}.
+ */
+export type CreatePylonClientOptions = {
+	/**
+	 * Base URL prefixed to every request. Empty string (default) means
+	 * same-origin — the right choice when Next is proxying `/api/*`
+	 * to the Pylon backend via `next.config.ts` rewrites, because the
+	 * browser sees same-origin and the cookie is auto-attached.
+	 */
+	baseUrl?: string;
+};
+
+/**
+ * Build a typed `api()` function for the dashboard. Sends `credentials:
+ * "include"` so the HttpOnly Pylon session cookie rides along on every
+ * request — there's no token in JS to steal.
+ *
+ * ```ts
+ * import { createPylonClient } from "@pylonsync/next/client";
+ * export const api = createPylonClient();
+ *
+ * const me = await api<Me>("/api/entities/User/abc");
+ * ```
+ *
+ * Throws {@link ApiError} on non-2xx so callers can `instanceof` it
+ * and surface `.code` + `.message` near the form that triggered the
+ * call.
+ */
+export function createPylonClient(opts: CreatePylonClientOptions = {}) {
+	const baseUrl = opts.baseUrl ?? "";
+	return async function api<T = unknown>(
+		path: string,
+		init: RequestInit = {},
+	): Promise<T> {
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+			...((init.headers as Record<string, string>) ?? {}),
+		};
+		const res = await fetch(`${baseUrl}${path}`, {
+			...init,
+			headers,
+			credentials: "include",
+		});
+		const text = await res.text();
+		// 204 / empty body → null. Callers that know the endpoint
+		// returns nothing don't have to special-case.
+		const body = text ? JSON.parse(text) : null;
+		if (!res.ok) {
+			const code = body?.error?.code ?? body?.code ?? "UNKNOWN";
+			const msg = body?.error?.message ?? body?.message ?? res.statusText;
+			throw new ApiError(res.status, code, msg);
+		}
+		return body as T;
+	};
+}
+
+/**
+ * Default client: same-origin, paired with the Next.js `/api/*`
+ * rewrite. Most apps use this directly; call {@link createPylonClient}
+ * if you need a different `baseUrl`.
+ */
+export const api = createPylonClient();

package/src/index.ts

@@ -0,0 +1,7 @@
+// Top-level re-exports for the most common items. Server-only
+// helpers live at the `@pylonsync/next/server` subpath so they
+// don't accidentally land in client bundles; client-only hooks
+// live at `@pylonsync/next/auth` for the same reason.
+
+export type { OAuthProvider, Session } from "./auth";
+export { ApiError } from "./client";

package/src/proxy.ts

@@ -0,0 +1,65 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+/**
+ * Options for {@link createPylonProxy}.
+ */
+export type CreatePylonProxyOptions = {
+	/**
+	 * Cookie name to look for. Defaults to `process.env.PYLON_COOKIE_NAME`,
+	 * falling back to `pylon_session`. Should match the Pylon backend's
+	 * `PYLON_COOKIE_NAME` (or `${app_name}_session` if unset there).
+	 */
+	cookieName?: string;
+	/**
+	 * Where to redirect unauthenticated requests. Defaults to `/login`.
+	 * The original path is preserved in `?next=…` so the login page can
+	 * bounce the user back after sign-in.
+	 */
+	loginUrl?: string;
+	/**
+	 * Routes the proxy applies to. Forms the `config.matcher` Next reads.
+	 * Defaults to `["/dashboard/:path*"]`.
+	 */
+	matcher?: string[];
+};
+
+/**
+ * Build a Next 16 `proxy.ts` that gates routes on the presence of the
+ * Pylon session cookie. Drop the result into `src/proxy.ts`:
+ *
+ * ```ts
+ * import { createPylonProxy } from "@pylonsync/next/proxy";
+ *
+ * const { proxy, config } = createPylonProxy({
+ *   matcher: ["/dashboard/:path*", "/onboarding/:path*"],
+ * });
+ *
+ * export { proxy, config };
+ * ```
+ *
+ * The proxy only checks cookie *presence* — a forged value will fail the
+ * server-side `/api/auth/me` revalidation in your layout. Its job is to
+ * short-circuit the obvious "no session at all" case before any page
+ * renders, so users never see protected UI flash before the redirect.
+ */
+export function createPylonProxy(opts: CreatePylonProxyOptions = {}) {
+	const cookieName =
+		opts.cookieName ?? process.env.PYLON_COOKIE_NAME ?? "pylon_session";
+	const loginUrl = opts.loginUrl ?? "/login";
+	const matcher = opts.matcher ?? ["/dashboard/:path*"];
+
+	function proxy(request: NextRequest) {
+		const session = request.cookies.get(cookieName);
+		if (session) return NextResponse.next();
+
+		const url = request.nextUrl.clone();
+		url.pathname = loginUrl;
+		// Preserve the original destination so the login page can bounce
+		// the user back after sign-in (read `?next=`).
+		url.searchParams.set("next", request.nextUrl.pathname);
+		return NextResponse.redirect(url);
+	}
+
+	return { proxy, config: { matcher } };
+}

package/src/server.ts

@@ -0,0 +1,110 @@
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+
+/**
+ * Resolved Pylon session for a server-side request. Use `cookieHeader`
+ * when forwarding the cookie to subsequent Pylon API calls (see
+ * {@link pylonFetch}).
+ */
+export type PylonSession = {
+	userId: string;
+	cookieHeader: string;
+};
+
+/**
+ * Options for the server-side helpers. Both default to env vars:
+ * `PYLON_COOKIE_NAME` (fallback `pylon_session`) and `PYLON_TARGET`
+ * (fallback `http://localhost:4321`).
+ */
+export type SessionOptions = {
+	cookieName?: string;
+	target?: string;
+};
+
+function resolveOpts(opts: SessionOptions = {}) {
+	return {
+		cookieName:
+			opts.cookieName ?? process.env.PYLON_COOKIE_NAME ?? "pylon_session",
+		target:
+			opts.target ?? process.env.PYLON_TARGET ?? "http://localhost:4321",
+	};
+}
+
+/**
+ * Read the Pylon session cookie and validate it server-side via
+ * `/api/auth/me`. Returns `null` if the cookie is missing or the
+ * session has been revoked / expired. Suitable for layouts that want
+ * to render different UI for anonymous vs. authenticated users.
+ *
+ * Use {@link requirePylonSession} if you'd rather just redirect.
+ */
+export async function getPylonSession(
+	opts?: SessionOptions,
+): Promise<PylonSession | null> {
+	const { cookieName, target } = resolveOpts(opts);
+	const cookieStore = await cookies();
+	const session = cookieStore.get(cookieName);
+	if (!session) return null;
+
+	const cookieHeader = `${cookieName}=${session.value}`;
+	const auth = await fetch(`${target}/api/auth/me`, {
+		headers: { cookie: cookieHeader },
+		cache: "no-store",
+	})
+		.then((r) => r.json() as Promise<{ user_id?: string }>)
+		.catch(() => ({}) as { user_id?: string });
+	if (!auth.user_id) return null;
+	return { userId: auth.user_id, cookieHeader };
+}
+
+/**
+ * Like {@link getPylonSession} but redirects to `loginUrl` (default
+ * `/login`) if the session is missing or invalid. Use in Server
+ * Component layouts to gate a whole subtree without leaking protected
+ * UI before the redirect.
+ *
+ * ```ts
+ * export default async function DashboardLayout({ children }) {
+ *   const { userId, cookieHeader } = await requirePylonSession();
+ *   const me = await fetchMe(userId, cookieHeader);
+ *   return <Chrome user={me}>{children}</Chrome>;
+ * }
+ * ```
+ */
+export async function requirePylonSession(
+	opts?: SessionOptions & { loginUrl?: string },
+): Promise<PylonSession> {
+	const session = await getPylonSession(opts);
+	if (!session) redirect(opts?.loginUrl ?? "/login");
+	return session;
+}
+
+/**
+ * Server-side fetch to the Pylon control plane that auto-forwards the
+ * caller's session cookie. Use from Server Components, Route Handlers,
+ * and Server Actions to call Pylon as the user.
+ *
+ * ```ts
+ * const me: Me = await pylonFetch(`/api/entities/User/${userId}`)
+ *   .then(r => r.json());
+ * ```
+ *
+ * Defaults to `cache: "no-store"` because Pylon responses are
+ * per-user; pass an explicit `cache` to override.
+ */
+export async function pylonFetch(
+	path: string,
+	init: RequestInit = {},
+	opts?: SessionOptions,
+): Promise<Response> {
+	const { cookieName, target } = resolveOpts(opts);
+	const cookieStore = await cookies();
+	const session = cookieStore.get(cookieName);
+	const headers = new Headers(init.headers);
+	if (session) headers.set("cookie", `${cookieName}=${session.value}`);
+	return fetch(`${target}${path}`, {
+		cache: "no-store",
+		...init,
+		headers,
+	});
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src"]
+}