convex-zen 0.0.1

package/src/client/tanstack-start-client.ts

@@ -0,0 +1,259 @@
+import type { SessionInfo, SignInInput } from "./primitives";
+import type { ReactAuthClient } from "./react";
+
+export interface TanStackStartAuthServerFns {
+  getSession: () => Promise<SessionInfo | null>;
+}
+
+interface AuthApiErrorPayload {
+  error?: string;
+}
+
+interface SessionResponsePayload {
+  session?: SessionInfo | null;
+}
+
+type UnionToIntersection<T> = (
+  T extends unknown ? (arg: T) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+type PluginExtension<TPlugin> = TPlugin extends TanStackStartAuthApiClientPlugin<
+  infer TExtension
+>
+  ? TExtension
+  : never;
+
+type PluginExtensions<
+  TPlugins extends readonly TanStackStartAuthApiClientPlugin<object>[],
+> = [TPlugins[number]] extends [never]
+  ? {}
+  : Simplify<UnionToIntersection<PluginExtension<TPlugins[number]>>>;
+
+interface RequestFailureContext {
+  fallback: string;
+}
+
+export interface TanStackStartAuthApiClientPluginContext {
+  basePath: string;
+  credentials: RequestCredentials;
+  requestJson: <T>(
+    path: string,
+    init: RequestInit,
+    failure: RequestFailureContext
+  ) => Promise<T>;
+  requestVoid: (
+    path: string,
+    init: RequestInit,
+    failure: RequestFailureContext
+  ) => Promise<void>;
+}
+
+export interface TanStackStartAuthApiClientPlugin<TExtension extends object> {
+  id: string;
+  create: (context: TanStackStartAuthApiClientPluginContext) => TExtension;
+}
+
+export interface TanStackStartAuthApiClientOptions<
+  TPlugins extends readonly TanStackStartAuthApiClientPlugin<object>[] = readonly TanStackStartAuthApiClientPlugin<object>[],
+> {
+  basePath?: string;
+  credentials?: RequestCredentials;
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  plugins?: TPlugins;
+}
+
+export interface TanStackStartAuthApiClient extends ReactAuthClient {
+  signInWithEmail: (input: SignInInput) => Promise<SessionInfo>;
+  signOut: () => Promise<void>;
+  signIn: {
+    email: (input: SignInInput) => Promise<SessionInfo>;
+  };
+}
+
+export type TanStackStartAuthApiClientWithPlugins<
+  TPlugins extends readonly TanStackStartAuthApiClientPlugin<object>[],
+> = TanStackStartAuthApiClient & PluginExtensions<TPlugins>;
+
+function normalizeBasePath(path: string): string {
+  const normalized = path.trim();
+  if (normalized === "") {
+    return "/api/auth";
+  }
+  const withLeadingSlash = normalized.startsWith("/")
+    ? normalized
+    : `/${normalized}`;
+  if (withLeadingSlash.length > 1 && withLeadingSlash.endsWith("/")) {
+    return withLeadingSlash.slice(0, -1);
+  }
+  return withLeadingSlash;
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function errorMessage(
+  response: Response,
+  payload: unknown,
+  fallback: string
+): string {
+  if (
+    payload &&
+    typeof payload === "object" &&
+    "error" in payload &&
+    typeof (payload as AuthApiErrorPayload).error === "string"
+  ) {
+    return (payload as AuthApiErrorPayload).error as string;
+  }
+  return `${fallback} (${response.status})`;
+}
+
+function toSignInBody(input: SignInInput): Record<string, string> {
+  const body: Record<string, string> = {
+    email: input.email,
+    password: input.password,
+  };
+  if (input.ipAddress) {
+    body.ipAddress = input.ipAddress;
+  }
+  if (input.userAgent) {
+    body.userAgent = input.userAgent;
+  }
+  return body;
+}
+
+/**
+ * Build a ConvexZen React auth client from TanStack Start server functions.
+ */
+export function createTanStackStartReactAuthClient(
+  serverFns: TanStackStartAuthServerFns
+): ReactAuthClient {
+  return {
+    getSession: async () => {
+      return await serverFns.getSession();
+    },
+  };
+}
+
+/**
+ * Build a browser auth client targeting TanStack Start auth API routes.
+ *
+ * Defaults to:
+ * - basePath: `/api/auth`
+ * - credentials: `same-origin`
+ */
+export function createTanStackStartAuthApiClient<
+  TPlugins extends readonly TanStackStartAuthApiClientPlugin<object>[] = [],
+>(
+  options: TanStackStartAuthApiClientOptions<TPlugins> = {}
+): TanStackStartAuthApiClientWithPlugins<TPlugins> {
+  const basePath = normalizeBasePath(options.basePath ?? "/api/auth");
+  const credentials = options.credentials ?? "same-origin";
+  const fetchImpl = options.fetch ?? fetch;
+  const plugins = options.plugins ?? [];
+
+  const request = async (
+    path: string,
+    init: RequestInit,
+    failure: RequestFailureContext
+  ): Promise<Response> => {
+    const response = await fetchImpl(`${basePath}/${path}`, {
+      ...init,
+      credentials,
+    });
+    if (!response.ok) {
+      const payload = await readJson(response);
+      throw new Error(errorMessage(response, payload, failure.fallback));
+    }
+    return response;
+  };
+
+  const requestJson = async <T>(
+    path: string,
+    init: RequestInit,
+    failure: RequestFailureContext
+  ): Promise<T> => {
+    const response = await request(path, init, failure);
+    const payload = await readJson(response);
+    return payload as T;
+  };
+
+  const requestVoid = async (
+    path: string,
+    init: RequestInit,
+    failure: RequestFailureContext
+  ): Promise<void> => {
+    await request(path, init, failure);
+  };
+
+  const getSession = async (): Promise<SessionInfo | null> => {
+    const payload = await requestJson<SessionResponsePayload | null>(
+      "session",
+      {
+        method: "GET",
+      },
+      { fallback: "Could not load session" }
+    );
+    return payload?.session ?? null;
+  };
+
+  const signInWithEmail = async (input: SignInInput): Promise<SessionInfo> => {
+    const payload = await requestJson<SessionResponsePayload | null>(
+      "sign-in-with-email",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(toSignInBody(input)),
+      },
+      { fallback: "Sign in failed" }
+    );
+    if (!payload?.session) {
+      throw new Error("Sign in succeeded but no session was returned");
+    }
+    return payload.session;
+  };
+
+  const signOut = async (): Promise<void> => {
+    await requestVoid(
+      "sign-out",
+      {
+        method: "POST",
+      },
+      { fallback: "Sign out failed" }
+    );
+  };
+
+  const baseClient: TanStackStartAuthApiClient = {
+    getSession,
+    signInWithEmail,
+    signOut,
+    signIn: {
+      email: signInWithEmail,
+    },
+  };
+
+  const pluginContext: TanStackStartAuthApiClientPluginContext = {
+    basePath,
+    credentials,
+    requestJson,
+    requestVoid,
+  };
+
+  const pluginExtensions: Record<string, unknown> = {};
+  for (const plugin of plugins) {
+    Object.assign(pluginExtensions, plugin.create(pluginContext));
+  }
+
+  return {
+    ...baseClient,
+    ...pluginExtensions,
+  } as TanStackStartAuthApiClientWithPlugins<TPlugins>;
+}

package/src/client/tanstack-start-plugins.ts

@@ -0,0 +1,203 @@
+import type { FunctionArgs, FunctionReference } from "convex/server";
+import type { TanStackStartAuthApiPluginFactory } from "./tanstack-start";
+
+type ActionRef = FunctionReference<"action", "public">;
+type UnknownRecord = Record<string, unknown>;
+
+export interface TanStackStartAdminApiPluginActions {
+  listUsers: ActionRef;
+  banUser: ActionRef;
+  setRole: ActionRef;
+  unbanUser?: ActionRef;
+  deleteUser?: ActionRef;
+}
+
+export interface TanStackStartAdminApiPluginOptions {
+  actions: TanStackStartAdminApiPluginActions;
+  routePrefix?: string;
+}
+
+function normalizeRoutePrefix(prefix: string): string {
+  const trimmed = prefix.trim().replace(/^\/+|\/+$/g, "");
+  return trimmed.length > 0 ? trimmed : "admin";
+}
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseListUsersArgs(value: unknown): {
+  limit?: number;
+  cursor?: string;
+} | null {
+  if (value === null || value === undefined) {
+    return {};
+  }
+  if (!isRecord(value)) {
+    return null;
+  }
+  const args: { limit?: number; cursor?: string } = {};
+  if (value.limit !== undefined) {
+    if (typeof value.limit !== "number") {
+      return null;
+    }
+    args.limit = value.limit;
+  }
+  if (value.cursor !== undefined) {
+    if (typeof value.cursor !== "string") {
+      return null;
+    }
+    args.cursor = value.cursor;
+  }
+  return args;
+}
+
+function parseBanUserArgs(value: unknown): {
+  userId: string;
+  reason?: string;
+  expiresAt?: number;
+} | null {
+  if (!isRecord(value) || typeof value.userId !== "string") {
+    return null;
+  }
+  const args: { userId: string; reason?: string; expiresAt?: number } = {
+    userId: value.userId,
+  };
+  if (value.reason !== undefined) {
+    if (typeof value.reason !== "string") {
+      return null;
+    }
+    args.reason = value.reason;
+  }
+  if (value.expiresAt !== undefined) {
+    if (typeof value.expiresAt !== "number") {
+      return null;
+    }
+    args.expiresAt = value.expiresAt;
+  }
+  return args;
+}
+
+function parseSetRoleArgs(value: unknown): { userId: string; role: string } | null {
+  if (
+    !isRecord(value) ||
+    typeof value.userId !== "string" ||
+    typeof value.role !== "string"
+  ) {
+    return null;
+  }
+  return {
+    userId: value.userId,
+    role: value.role,
+  };
+}
+
+function parseSingleUserIdArgs(value: unknown): { userId: string } | null {
+  if (!isRecord(value) || typeof value.userId !== "string") {
+    return null;
+  }
+  return { userId: value.userId };
+}
+
+/**
+ * Add admin auth API routes to TanStack Start handler.
+ *
+ * Endpoints:
+ * - POST `/api/auth/admin/list-users`
+ * - POST `/api/auth/admin/ban-user`
+ * - POST `/api/auth/admin/set-role`
+ * - POST `/api/auth/admin/unban-user` (optional)
+ * - POST `/api/auth/admin/delete-user` (optional)
+ */
+export function adminApiPlugin(
+  options: TanStackStartAdminApiPluginOptions
+): TanStackStartAuthApiPluginFactory {
+  const routePrefix = normalizeRoutePrefix(options.routePrefix ?? "admin");
+
+  return {
+    id: "admin",
+    create: ({ fetchers }) => ({
+      id: "admin",
+      handle: async (context) => {
+        const actionPrefix = `${routePrefix}/`;
+        if (!context.action.startsWith(actionPrefix)) {
+          return null;
+        }
+        if (context.method !== "POST") {
+          return context.json({ error: "Method not allowed" }, 405);
+        }
+
+        const adminAction = context.action.slice(actionPrefix.length);
+        const payload = await context.readJson();
+
+        if (adminAction === "list-users") {
+          const args = parseListUsersArgs(payload);
+          if (!args) {
+            return context.json({ error: "Invalid request body" }, 400);
+          }
+          const result = await fetchers.fetchAuthAction(
+            options.actions.listUsers,
+            args as FunctionArgs<typeof options.actions.listUsers>
+          );
+          return context.json(result);
+        }
+
+        if (adminAction === "ban-user") {
+          const args = parseBanUserArgs(payload);
+          if (!args) {
+            return context.json({ error: "Invalid request body" }, 400);
+          }
+          const result = await fetchers.fetchAuthAction(
+            options.actions.banUser,
+            args as FunctionArgs<typeof options.actions.banUser>
+          );
+          return context.json(result);
+        }
+
+        if (adminAction === "set-role") {
+          const args = parseSetRoleArgs(payload);
+          if (!args) {
+            return context.json({ error: "Invalid request body" }, 400);
+          }
+          const result = await fetchers.fetchAuthAction(
+            options.actions.setRole,
+            args as FunctionArgs<typeof options.actions.setRole>
+          );
+          return context.json(result);
+        }
+
+        if (adminAction === "unban-user") {
+          if (!options.actions.unbanUser) {
+            return context.json({ error: "Not found" }, 404);
+          }
+          const args = parseSingleUserIdArgs(payload);
+          if (!args) {
+            return context.json({ error: "Invalid request body" }, 400);
+          }
+          const result = await fetchers.fetchAuthAction(
+            options.actions.unbanUser,
+            args as FunctionArgs<typeof options.actions.unbanUser>
+          );
+          return context.json(result);
+        }
+
+        if (adminAction === "delete-user") {
+          if (!options.actions.deleteUser) {
+            return context.json({ error: "Not found" }, 404);
+          }
+          const args = parseSingleUserIdArgs(payload);
+          if (!args) {
+            return context.json({ error: "Invalid request body" }, 400);
+          }
+          const result = await fetchers.fetchAuthAction(
+            options.actions.deleteUser,
+            args as FunctionArgs<typeof options.actions.deleteUser>
+          );
+          return context.json(result);
+        }
+
+        return null;
+      },
+    }),
+  };
+}