@pylonsync/next 0.2.11 → 0.2.12

package/README.md

@@ -0,0 +1,184 @@
+# @pylonsync/next
+
+Next.js 16 helpers for Pylon. Cookie-based auth, server-side data
+loading, edge proxy gate, OAuth provider rendering — all designed
+around App Router conventions.
+
+## Install
+
+```sh
+bun add @pylonsync/next
+# or: npm i @pylonsync/next
+```
+
+## Setup
+
+### 1. Wire the API origin
+
+Set `PYLON_TARGET` on your Next host (Vercel project, fly.toml, etc.)
+to your Pylon control-plane origin.
+
+```env
+PYLON_TARGET=https://api.example.com
+```
+
+In dev `next dev` defaults to `http://localhost:4321` (the `pylon dev`
+default port) so no env tweaking required.
+
+### 2. Build a server helper
+
+```ts
+// src/lib/pylon.ts
+import { createPylonServer } from "@pylonsync/next/server";
+
+export const pylon = createPylonServer({
+  // Pylon emits `${app_name}_session` — pass that exact name. There's
+  // no "default" because the package can't know your app name; passing
+  // it explicitly here also kills a class of silent-breakage bugs
+  // where a wrong env var quietly breaks auth in production.
+  cookieName: "myapp_session",
+  // Optional: name of your "current user" function. Default "getMe".
+  getMeFn: "getMe",
+});
+```
+
+### 3. Define the `getMe` function on Pylon
+
+```ts
+// apps/control-plane/functions/getMe.ts
+import { query } from "@pylonsync/functions";
+
+export default query({
+  args: {},
+  async handler(ctx) {
+    if (!ctx.auth.userId) return null;
+    const user = await ctx.db.get("User", ctx.auth.userId);
+    if (!user) return null;
+    // Project to safe-to-display fields. Bypasses the User entity's
+    // read policy (which typically denies everything to keep the
+    // password hash from leaving the server).
+    return {
+      id: user.id,
+      email: user.email,
+      displayName: user.displayName,
+    };
+  },
+});
+```
+
+### 4. Gate dashboard routes with a proxy
+
+```ts
+// src/proxy.ts
+import { createPylonProxy } from "@pylonsync/next/proxy";
+
+// Next 16 statically extracts `config.matcher` at build time — it has
+// to be an inline literal. We pass the same array to createPylonProxy
+// so the runtime matches; tsc catches drift.
+export const config = {
+  matcher: ["/dashboard/:path*", "/onboarding/:path*"],
+};
+
+export const proxy = createPylonProxy({
+  cookieName: "myapp_session",
+  matcher: ["/dashboard/:path*", "/onboarding/:path*"],
+}).proxy;
+```
+
+### 5. Use it in pages
+
+```tsx
+// src/app/dashboard/layout.tsx
+import { pylon } from "@/lib/pylon";
+import type { User } from "@/lib/types";
+
+export default async function DashboardLayout({ children }) {
+  const me = await pylon.requireMe<User>();
+  return <Chrome user={me.user}>{children}</Chrome>;
+}
+```
+
+```tsx
+// src/app/dashboard/page.tsx
+import { redirect } from "next/navigation";
+import { pylon } from "@/lib/pylon";
+
+type Org = { id: string; name: string; slug: string };
+
+export default async function DashboardPage() {
+  const orgs = await pylon.json<Org[]>("/api/entities/Organization");
+  if (orgs.length === 0) redirect("/onboarding");
+  return <OrgsList orgs={orgs} />;
+}
+```
+
+```tsx
+// src/app/login/page.tsx — no client-mount flicker for OAuth row
+import { pylon } from "@/lib/pylon";
+import { LoginForm } from "./login-form"; // "use client"
+
+export default async function LoginPage() {
+  const providers = await pylon.getOAuthProviders();
+  return <LoginForm providers={providers} />;
+}
+```
+
+## Server helper API
+
+`createPylonServer(config)` returns a `PylonServer` with:
+
+| Method | Returns | Notes |
+|---|---|---|
+| `fetch(path, init?)` | `Response` | Forwards the session cookie. Caller handles status. |
+| `json<T>(path, init?)` | `T` | Parses + status-checks. Throws `ApiError` on non-2xx. |
+| `getAuth()` | `PylonAuth \| null` | userId, tenantId, isAdmin, cookieHeader. |
+| `requireAuth()` | `PylonAuth` | Redirects to `loginUrl` on null. |
+| `getMe<U>()` | `{auth, user: U} \| null` | Calls `/api/fn/${getMeFn}`. |
+| `requireMe<U>()` | `{auth, user: U}` | Redirects on null. |
+| `getOAuthProviders()` | `OAuthProvider[]` | Empty array on failure. |
+
+## Client helpers
+
+```ts
+// src/lib/api.ts
+import { createPylonClient } from "@pylonsync/next/client";
+export const api = createPylonClient(); // same-origin via Next rewrite
+
+// usage from a client component
+const me = await api<Me>("/api/auth/me");
+```
+
+```tsx
+// "use client" form
+import { useAuthSubmit, loginWithPassword } from "@pylonsync/next/auth";
+
+const { submit, error, busy } = useAuthSubmit(loginWithPassword);
+```
+
+`@pylonsync/next/auth` provides: `signupWithPassword`, `loginWithPassword`,
+`logout`, `startOAuthLogin`, `verifyEmail`, `useOAuthProviders`,
+`useAuthSubmit`.
+
+## CORS / cookies across subdomains
+
+Most apps deploy the dashboard at `app.example.com` and the Pylon
+control plane at `api.example.com`. To make the session cookie visible
+on both:
+
+```sh
+fly secrets set -a my-pylon-app \
+  PYLON_DASHBOARD_URL=https://app.example.com \
+  PYLON_COOKIE_DOMAIN=.example.com \
+  PYLON_CORS_ORIGIN=https://app.example.com
+```
+
+The dashboard's `next.config.ts` should rewrite `/api/*` to the API
+origin so the browser sees same-origin (no CORS preflights). The
+package's server-side helpers hit `PYLON_TARGET` directly and skip
+the rewrite.
+
+## Versioning
+
+Tracks the rest of `@pylonsync/*`. Pylon binary 0.2.x → package 0.2.x.
+
+License: MIT OR Apache-2.0.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.11",
+  "version": "0.2.12",
   "type": "module",
   "description": "Next.js helpers for Pylon — cookie-based auth gate, server-side session helpers, and reusable client hooks.",
   "exports": {

package/src/client.ts

@@ -1,19 +1,8 @@
 "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);
-	}
-}
+import { ApiError } from "./errors";
+
+export { ApiError };
 
 /**
  * Options for {@link createPylonClient}.

package/src/errors.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared error type for Pylon API calls. Lives outside `client.ts` (which
+ * is `"use client"`) so server code can throw + catch the same class
+ * without dragging the whole client bundle in.
+ *
+ * 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);
+		this.name = "ApiError";
+	}
+}

package/src/index.ts

@@ -3,5 +3,5 @@
 // don't accidentally land in client bundles; client-only hooks
 // live at `@pylonsync/next/auth` for the same reason.
 
+export { ApiError } from "./errors";
 export type { OAuthProvider, Session } from "./auth";
-export { ApiError } from "./client";

package/src/server.ts

@@ -1,22 +1,12 @@
 import { cookies } from "next/headers";
 import { redirect } from "next/navigation";
 import type { OAuthProvider } from "./auth";
+import { ApiError } from "./errors";
 
 /**
- * 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;
-};
-
-/**
- * Full auth shape from `/api/auth/me`. Superset of {@link PylonSession}
- * — adds the active tenant and admin flag. Use when the server-rendered
- * UI needs to branch on tenant or role (e.g. show org switcher only
- * when isAdmin, scope queries to tenantId).
+ * Full auth shape from `/api/auth/me`. Use when the server-rendered
+ * UI needs more than "is there any session" — branching on tenant or
+ * role, scoping a query to the active tenant, etc.
  */
 export type PylonAuth = {
 	userId: string;
@@ -26,20 +16,230 @@ export type PylonAuth = {
 };
 
 /**
- * Options for the server-side helpers. Both default to env vars:
- * `PYLON_COOKIE_NAME` (fallback `pylon_session`) and `PYLON_TARGET`
- * (fallback `http://localhost:4321` in dev only — required in prod).
+ * Configuration for {@link createPylonServer}.
+ *
+ * `cookieName` is REQUIRED — there's no safe default because Pylon's
+ * binary emits `${app_name}_session` (e.g. `pylon-cloud_session`) and
+ * the package can't know your app name. Passing it explicitly here
+ * also kills a class of bugs where a wrong env var silently breaks
+ * auth in production.
+ *
+ * `target` is the Pylon control-plane origin. Defaults to the
+ * `PYLON_TARGET` env var; throws in production if unset.
+ *
+ * `getMeFn` is the server function name used by {@link PylonServer.getMe}.
+ * Default `"getMe"` — most apps just declare a `functions/getMe.ts`
+ * that returns the current user's safe-to-display fields, see the
+ * Pylon Cloud reference for an example.
+ *
+ * `loginUrl` is where {@link PylonServer.requireAuth} / {@link
+ * PylonServer.requireMe} redirect when the session is missing.
  */
-export type SessionOptions = {
-	cookieName?: string;
+export type PylonServerConfig = {
+	cookieName: string;
 	target?: string;
+	getMeFn?: string;
+	loginUrl?: string;
 };
 
-function resolveOpts(opts: SessionOptions = {}) {
+/**
+ * Bound server helpers — built once per app via {@link createPylonServer}
+ * and used everywhere. Eliminates the per-call cookieName / target
+ * plumbing the standalone helpers required.
+ *
+ * ```ts
+ * // src/lib/pylon.ts
+ * export const pylon = createPylonServer({
+ *   cookieName: "myapp_session",
+ *   getMeFn: "getMe",
+ * });
+ *
+ * // src/app/dashboard/layout.tsx
+ * import { pylon } from "@/lib/pylon";
+ * const me = await pylon.requireMe<User>();
+ * const orgs = await pylon.json<Org[]>("/api/entities/Organization");
+ * ```
+ */
+export interface PylonServer {
+	/** Forwarded raw fetch — caller handles status + body parsing. */
+	fetch(path: string, init?: RequestInit): Promise<Response>;
+	/**
+	 * Fetch + parse + status check in one. Throws {@link ApiError} on
+	 * non-2xx so callers don't have to write the `if (!res.ok)` dance
+	 * before every `.json()`.
+	 */
+	json<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+	/** Resolved auth + null on no session. */
+	getAuth(): Promise<PylonAuth | null>;
+	/** Resolved auth, or `redirect()` to `loginUrl`. */
+	requireAuth(): Promise<PylonAuth>;
+	/**
+	 * OAuth provider list, server-side. Eliminates the post-mount
+	 * flicker the client `useOAuthProviders` causes.
+	 */
+	getOAuthProviders(): Promise<OAuthProvider[]>;
+	/**
+	 * Current user (auth + the row your `getMe` function returns).
+	 * Calls `/api/fn/${getMeFn}` rather than the entity API — the
+	 * function bypasses entity policies and lets you control the
+	 * projection (typically: id, email, displayName; never
+	 * passwordHash).
+	 */
+	getMe<U = Record<string, unknown>>(): Promise<{
+		auth: PylonAuth;
+		user: U;
+	} | null>;
+	/** Like `getMe`, redirects to `loginUrl` on null. */
+	requireMe<U = Record<string, unknown>>(): Promise<{
+		auth: PylonAuth;
+		user: U;
+	}>;
+}
+
+/**
+ * Build a server-side Pylon helper, bound to one app's configuration.
+ * One factory call per app, no per-call boilerplate.
+ *
+ * See {@link PylonServerConfig} for the required options.
+ */
+export function createPylonServer(config: PylonServerConfig): PylonServer {
+	const cookieName = config.cookieName;
+	const targetOpt = config.target;
+	const getMeFn = config.getMeFn ?? "getMe";
+	const loginUrl = config.loginUrl ?? "/login";
+
+	const target = (): string => resolveTarget(targetOpt);
+
+	async function readSession(): Promise<{
+		header: string;
+		value: string;
+	} | null> {
+		const cookieStore = await cookies();
+		const c = cookieStore.get(cookieName);
+		if (!c) return null;
+		return { header: `${cookieName}=${c.value}`, value: c.value };
+	}
+
+	async function getAuth(): Promise<PylonAuth | null> {
+		const session = await readSession();
+		if (!session) return null;
+		const auth = await fetch(`${target()}/api/auth/me`, {
+			headers: { cookie: session.header },
+			cache: "no-store",
+		})
+			.then(
+				(r) =>
+					r.json() as Promise<{
+						user_id?: string;
+						tenant_id?: string | null;
+						is_admin?: boolean;
+					}>,
+			)
+			.catch(
+				() =>
+					({}) as {
+						user_id?: string;
+						tenant_id?: string | null;
+						is_admin?: boolean;
+					},
+			);
+		if (!auth.user_id) return null;
+		return {
+			userId: auth.user_id,
+			tenantId: auth.tenant_id ?? null,
+			isAdmin: auth.is_admin ?? false,
+			cookieHeader: session.header,
+		};
+	}
+
+	async function requireAuth(): Promise<PylonAuth> {
+		const a = await getAuth();
+		if (!a) redirect(loginUrl);
+		return a;
+	}
+
+	async function pylonFetchBound(
+		path: string,
+		init: RequestInit = {},
+	): Promise<Response> {
+		const session = await readSession();
+		const headers = new Headers(init.headers);
+		if (session) headers.set("cookie", session.header);
+		return fetch(`${target()}${path}`, {
+			cache: "no-store",
+			...init,
+			headers,
+		});
+	}
+
+	async function pylonJsonBound<T = unknown>(
+		path: string,
+		init: RequestInit = {},
+	): Promise<T> {
+		const res = await pylonFetchBound(path, init);
+		const text = await res.text();
+		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;
+	}
+
+	async function getOAuthProvidersBound(): Promise<OAuthProvider[]> {
+		// Providers are env-derived on the control plane; they don't
+		// change per-request but DO change across deploys. no-store is
+		// the safe default until a caller opts into caching.
+		try {
+			const res = await fetch(`${target()}/api/auth/providers`, {
+				cache: "no-store",
+			});
+			if (!res.ok) return [];
+			return (await res.json()) as OAuthProvider[];
+		} catch {
+			return [];
+		}
+	}
+
+	async function getMe<U = Record<string, unknown>>(): Promise<{
+		auth: PylonAuth;
+		user: U;
+	} | null> {
+		const auth = await getAuth();
+		if (!auth) return null;
+		try {
+			const user = await pylonJsonBound<U>(`/api/fn/${getMeFn}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: "{}",
+			});
+			if (user == null) return null;
+			return { auth, user };
+		} catch {
+			// Function may not be registered yet, or the row was
+			// deleted while logged in — treat as anonymous.
+			return null;
+		}
+	}
+
+	async function requireMe<U = Record<string, unknown>>(): Promise<{
+		auth: PylonAuth;
+		user: U;
+	}> {
+		const me = await getMe<U>();
+		if (!me) redirect(loginUrl);
+		return me;
+	}
+
 	return {
-		cookieName:
-			opts.cookieName ?? process.env.PYLON_COOKIE_NAME ?? "pylon_session",
-		target: opts.target ?? resolveTarget(),
+		fetch: pylonFetchBound,
+		json: pylonJsonBound,
+		getAuth,
+		requireAuth,
+		getOAuthProviders: getOAuthProvidersBound,
+		getMe,
+		requireMe,
 	};
 }
 
@@ -50,7 +250,8 @@ function resolveOpts(opts: SessionOptions = {}) {
  * on localhost:4321 (sidecar, debug shim, nothing). Throw loudly so
  * the misconfiguration surfaces immediately on the first request.
  */
-function resolveTarget(): string {
+function resolveTarget(target?: string): string {
+	if (target && target.length > 0) return target;
 	const env = process.env.PYLON_TARGET;
 	if (env && env.length > 0) return env;
 	if (process.env.NODE_ENV === "production") {
@@ -61,208 +262,76 @@ function resolveTarget(): string {
 	return "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 };
-}
+// ---------------------------------------------------------------------------
+// Standalone helpers — for callers that want one-off invocations without
+// instantiating a {@link PylonServer}. Most apps should prefer
+// {@link createPylonServer}; these exist for tests, scripts, and
+// migrations.
+// ---------------------------------------------------------------------------
 
 /**
- * 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>;
- * }
- * ```
+ * One-shot version of {@link PylonServer.getAuth}. Pass the cookie
+ * name explicitly — the package no longer reads PYLON_COOKIE_NAME
+ * from env (silently-overridable env-driven config was a footgun in
+ * practice).
  */
-export async function requirePylonSession(
-	opts?: SessionOptions & { loginUrl?: string },
-): Promise<PylonSession> {
-	const session = await getPylonSession(opts);
-	if (!session) redirect(opts?.loginUrl ?? "/login");
-	return session;
-}
-
-/**
- * Like {@link getPylonSession} but returns the full auth shape —
- * userId + tenantId + isAdmin. Use when the server-rendered UI
- * needs more than "is there any session" (e.g. scoping a query to
- * the active tenant, showing an admin-only menu).
- *
- * Returns `null` if no session cookie is present, or the cookie's
- * session has been revoked / expired.
- *
- * ```ts
- * const auth = await getAuth();
- * if (!auth) redirect("/login");
- * if (!auth.tenantId) redirect("/onboarding");
- * ```
- */
-export async function getAuth(
-	opts?: SessionOptions,
-): Promise<PylonAuth | 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;
-					tenant_id?: string | null;
-					is_admin?: boolean;
-				}>,
-		)
-		.catch(
-			() =>
-				({}) as {
-					user_id?: string;
-					tenant_id?: string | null;
-					is_admin?: boolean;
-				},
-		);
-	if (!auth.user_id) return null;
-	return {
-		userId: auth.user_id,
-		tenantId: auth.tenant_id ?? null,
-		isAdmin: auth.is_admin ?? false,
-		cookieHeader,
-	};
+export async function getAuth(opts: {
+	cookieName: string;
+	target?: string;
+}): Promise<PylonAuth | null> {
+	return createPylonServer({
+		cookieName: opts.cookieName,
+		target: opts.target,
+	}).getAuth();
 }
 
-/**
- * Like {@link getAuth} but redirects to `loginUrl` (default `/login`)
- * if no session. The non-null return type frees layouts from the
- * `if (!auth) redirect(...)` guard.
- */
-export async function requireAuth(
-	opts?: SessionOptions & { loginUrl?: string },
-): Promise<PylonAuth> {
-	const auth = await getAuth(opts);
-	if (!auth) redirect(opts?.loginUrl ?? "/login");
-	return auth;
+/** One-shot version of {@link PylonServer.requireAuth}. */
+export async function requireAuth(opts: {
+	cookieName: string;
+	target?: string;
+	loginUrl?: string;
+}): Promise<PylonAuth> {
+	return createPylonServer(opts).requireAuth();
 }
 
-/**
- * Fetch the authed user's row from the User entity in addition to
- * resolving auth. Eliminates the "header chrome renders empty for a
- * frame, then the username pops in" flicker on dashboard layouts.
- *
- * The User shape is app-defined (different Pylon apps add their own
- * fields beyond the base `email`/`displayName`). Pass your `User`
- * type as the generic so the return value is correctly shaped.
- *
- * ```ts
- * type User = { id: string; email: string; displayName: string };
- *
- * const me = await getCurrentUser<User>();
- * if (!me) redirect("/login");
- * return <Chrome user={me.user} />;
- * ```
- *
- * Returns `null` when there's no session OR the user row can't be
- * loaded (deleted account, transient API failure). Most layouts
- * should treat both cases as "redirect to login" — see
- * {@link requireCurrentUser}.
- */
-export async function getCurrentUser<U = Record<string, unknown>>(
-	opts?: SessionOptions,
-): Promise<{ auth: PylonAuth; user: U } | null> {
-	const auth = await getAuth(opts);
-	if (!auth) return null;
-	const { target } = resolveOpts(opts);
-	const res = await fetch(
-		`${target}/api/entities/User/${encodeURIComponent(auth.userId)}`,
-		{ headers: { cookie: auth.cookieHeader }, cache: "no-store" },
-	);
-	if (!res.ok) return null;
-	const user = (await res.json()) as U;
-	return { auth, user };
+/** One-shot version of {@link PylonServer.fetch}. */
+export async function pylonFetch(
+	path: string,
+	init?: RequestInit,
+	opts?: { cookieName: string; target?: string },
+): Promise<Response> {
+	if (!opts) {
+		throw new Error(
+			"pylonFetch requires an `opts` argument with `cookieName`. The package no longer reads PYLON_COOKIE_NAME from env to avoid silent breakage from misconfigured envs.",
+		);
+	}
+	return createPylonServer(opts).fetch(path, init);
 }
 
-/**
- * Like {@link getCurrentUser} but redirects to `loginUrl` (default
- * `/login`) if the session or user can't be resolved.
- */
-export async function requireCurrentUser<U = Record<string, unknown>>(
-	opts?: SessionOptions & { loginUrl?: string },
-): Promise<{ auth: PylonAuth; user: U }> {
-	const me = await getCurrentUser<U>(opts);
-	if (!me) redirect(opts?.loginUrl ?? "/login");
-	return me;
+/** One-shot version of {@link PylonServer.json}. */
+export async function pylonJson<T = unknown>(
+	path: string,
+	init?: RequestInit,
+	opts?: { cookieName: string; target?: string },
+): Promise<T> {
+	if (!opts) {
+		throw new Error(
+			"pylonJson requires an `opts` argument with `cookieName`.",
+		);
+	}
+	return createPylonServer(opts).json<T>(path, init);
 }
 
 /**
- * Server-side fetch of the enabled OAuth providers. Use in Server
- * Components for /login and /signup so the "Continue with Google"
- * row paints in the initial HTML — no post-mount flicker like the
- * client-side {@link useOAuthProviders} hook causes.
- *
- * Returns an empty array on any failure (control plane unreachable,
- * 5xx, etc.) so the page can fall back to rendering the password
- * form alone instead of crashing.
- *
- * ```tsx
- * // app/login/page.tsx
- * import { getOAuthProviders } from "@pylonsync/next/server";
- * import { LoginForm } from "./login-form"; // "use client"
- *
- * export default async function LoginPage() {
- *   const providers = await getOAuthProviders();
- *   return <LoginForm providers={providers} />;
- * }
- * ```
- *
- * Hits PYLON_TARGET directly rather than going through the Next
- * /api/* rewrite — the rewrite is a browser-side same-origin
- * optimization, irrelevant on the server, and skipping it avoids a
- * pointless localhost→localhost hop in dev + a real network round
- * trip to ourselves in prod.
+ * One-shot OAuth provider list. Doesn't need a cookie (the endpoint
+ * is public), but does need a `target` resolution.
  */
-export async function getOAuthProviders(
-	opts?: Pick<SessionOptions, "target">,
-): Promise<OAuthProvider[]> {
-	const { target } = resolveOpts(opts);
+export async function getOAuthProviders(opts: {
+	target?: string;
+} = {}): Promise<OAuthProvider[]> {
+	const target = resolveTarget(opts.target);
 	try {
 		const res = await fetch(`${target}/api/auth/providers`, {
-			// Providers are env-derived on the control plane (set when
-			// PYLON_OAUTH_*_CLIENT_ID is configured). They don't change
-			// per-request, but they DO change across deploys. no-store
-			// is the safest default until callers explicitly opt in to
-			// caching via revalidate.
 			cache: "no-store",
 		});
 		if (!res.ok) return [];
@@ -271,33 +340,3 @@ export async function getOAuthProviders(
 		return [];
 	}
 }
-
-/**
- * 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,
-	});
-}