@clubedge/create-clubedge-app 0.2.0 → 0.3.0

package/template/packages/cache/src/index.ts

@@ -0,0 +1,19 @@
+import { createMemoryRateLimiter, type RateLimiter, type RateLimitOptions } from "./rate-limit";
+import { createRedisRateLimiter } from "./redis";
+
+export {
+  createMemoryRateLimiter,
+  type RateLimiter,
+  type RateLimitOptions,
+  type RateLimitResult,
+} from "./rate-limit";
+export { createRedisCache, createRedisRateLimiter, type Cache } from "./redis";
+
+/**
+ * Uses Redis when a URL is provided so limits are shared across instances. Without one it
+ * falls back to a per-process memory limiter, which suits a single server only.
+ */
+export function createRateLimiter(options: RateLimitOptions & { redisUrl?: string }): RateLimiter {
+  const { redisUrl, ...limits } = options;
+  return redisUrl ? createRedisRateLimiter(redisUrl, limits) : createMemoryRateLimiter(limits);
+}

package/template/packages/cache/src/rate-limit.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { createMemoryRateLimiter } from "./rate-limit";
+
+describe("createMemoryRateLimiter", () => {
+  it("allows requests up to the limit and then blocks", async () => {
+    const limiter = createMemoryRateLimiter({ requests: 2, windowSeconds: 60 }, { now: () => 0 });
+
+    expect(await limiter.limit("client")).toMatchObject({ success: true, remaining: 1 });
+    expect(await limiter.limit("client")).toMatchObject({ success: true, remaining: 0 });
+    expect(await limiter.limit("client")).toMatchObject({ success: false, remaining: 0 });
+  });
+
+  it("tracks identifiers independently", async () => {
+    const limiter = createMemoryRateLimiter({ requests: 1, windowSeconds: 60 }, { now: () => 0 });
+
+    expect((await limiter.limit("a")).success).toBe(true);
+    expect((await limiter.limit("b")).success).toBe(true);
+    expect((await limiter.limit("a")).success).toBe(false);
+  });
+
+  it("starts a new window after the previous one expires", async () => {
+    let time = 0;
+    const limiter = createMemoryRateLimiter(
+      { requests: 1, windowSeconds: 10 },
+      { now: () => time },
+    );
+
+    expect((await limiter.limit("client")).success).toBe(true);
+    expect((await limiter.limit("client")).success).toBe(false);
+    time = 10_000;
+    expect(await limiter.limit("client")).toMatchObject({ success: true, resetAt: 20_000 });
+  });
+
+  it("never holds more than maxKeys windows", async () => {
+    const limiter = createMemoryRateLimiter(
+      { requests: 1, windowSeconds: 60 },
+      { maxKeys: 2, now: () => 0 },
+    );
+
+    await limiter.limit("a");
+    await limiter.limit("b");
+    await limiter.limit("c");
+    // "a" was evicted to make room, so it gets a fresh window.
+    expect((await limiter.limit("a")).success).toBe(true);
+  });
+
+  it("rejects invalid options and identifiers", async () => {
+    expect(() => createMemoryRateLimiter({ requests: 0 })).toThrow();
+    expect(() => createMemoryRateLimiter({ windowSeconds: 1.5 })).toThrow();
+    await expect(createMemoryRateLimiter().limit("")).rejects.toThrow();
+  });
+});

package/template/packages/cache/src/rate-limit.ts

@@ -0,0 +1,74 @@
+export type RateLimitResult = {
+  success: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+};
+
+export type RateLimiter = {
+  limit(identifier: string): Promise<RateLimitResult>;
+};
+
+export type RateLimitOptions = {
+  requests?: number;
+  windowSeconds?: number;
+};
+
+export function validateRateLimitOptions({ requests = 10, windowSeconds = 60 }: RateLimitOptions) {
+  if (!Number.isInteger(requests) || requests < 1) {
+    throw new Error("Rate limit must allow at least one request.");
+  }
+  if (!Number.isInteger(windowSeconds) || windowSeconds < 1) {
+    throw new Error("Rate limit window must be a positive number of seconds.");
+  }
+  return { requests, windowSeconds };
+}
+
+export function validateRateLimitIdentifier(identifier: string) {
+  if (identifier.length < 1 || identifier.length > 256) {
+    throw new Error("Rate limit identifier must contain between 1 and 256 characters.");
+  }
+}
+
+/**
+ * Fixed-window limiter held in process memory. Limits apply per server instance, so use
+ * Redis when the app runs on several instances or serverless functions.
+ */
+export function createMemoryRateLimiter(
+  options: RateLimitOptions = {},
+  { maxKeys = 10_000, now = Date.now }: { maxKeys?: number; now?: () => number } = {},
+): RateLimiter {
+  const { requests, windowSeconds } = validateRateLimitOptions(options);
+  const windowMilliseconds = windowSeconds * 1_000;
+  const windows = new Map<string, { count: number; resetAt: number }>();
+
+  function evictExpired(currentTime: number) {
+    for (const [key, window] of windows) {
+      if (window.resetAt <= currentTime) windows.delete(key);
+    }
+  }
+
+  return {
+    async limit(identifier) {
+      validateRateLimitIdentifier(identifier);
+      const currentTime = now();
+      let window = windows.get(identifier);
+
+      if (!window || window.resetAt <= currentTime) {
+        if (windows.size >= maxKeys) evictExpired(currentTime);
+        // Still full: drop the oldest entry rather than grow without bound.
+        if (windows.size >= maxKeys) windows.delete(windows.keys().next().value!);
+        window = { count: 0, resetAt: currentTime + windowMilliseconds };
+        windows.set(identifier, window);
+      }
+
+      window.count += 1;
+      return {
+        success: window.count <= requests,
+        limit: requests,
+        remaining: Math.max(0, requests - window.count),
+        resetAt: window.resetAt,
+      };
+    },
+  };
+}

package/template/packages/cache/src/redis.ts

@@ -0,0 +1,106 @@
+import { createClient } from "redis";
+import {
+  validateRateLimitIdentifier,
+  validateRateLimitOptions,
+  type RateLimiter,
+  type RateLimitOptions,
+} from "./rate-limit";
+
+type RedisClient = ReturnType<typeof createClient>;
+
+// One client per URL for the life of the process, surviving dev-server module reloads.
+const globalForRedis = globalThis as typeof globalThis & {
+  clubedgeRedis?: Map<string, { client: RedisClient; connection?: Promise<RedisClient> }>;
+};
+
+function redisEntry(url: string) {
+  globalForRedis.clubedgeRedis ??= new Map();
+  let entry = globalForRedis.clubedgeRedis.get(url);
+  if (!entry) {
+    const client = createClient({
+      url,
+      socket: {
+        connectTimeout: 5_000,
+        reconnectStrategy: (retries) => Math.min(retries * 250, 3_000),
+      },
+    });
+    client.on("error", (error) => console.error("Redis client error", error));
+    entry = { client };
+    globalForRedis.clubedgeRedis.set(url, entry);
+  }
+  return entry;
+}
+
+export async function connectRedis(url: string): Promise<RedisClient> {
+  const entry = redisEntry(url);
+  if (entry.client.isReady) return entry.client;
+
+  entry.connection ??= entry.client.connect().catch((error: unknown) => {
+    entry.connection = undefined;
+    throw error;
+  });
+  return entry.connection;
+}
+
+export interface Cache {
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+}
+
+export function createRedisCache(url: string, prefix = "clubedge:cache:"): Cache {
+  return {
+    async get<T>(key: string) {
+      const value = await (await connectRedis(url)).get(`${prefix}${key}`);
+      if (value === null) return null;
+      try {
+        return JSON.parse(value) as T;
+      } catch {
+        return value as T;
+      }
+    },
+    async set(key, value, ttlSeconds) {
+      if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) {
+        throw new Error("Cache TTL must be a positive integer number of seconds.");
+      }
+      const serialized = JSON.stringify(value);
+      if (serialized === undefined) {
+        throw new Error("Cache values must be JSON serializable.");
+      }
+      await (await connectRedis(url)).set(`${prefix}${key}`, serialized, { EX: ttlSeconds });
+    },
+  };
+}
+
+/** Fixed-window limiter shared by every instance that uses the same Redis database. */
+export function createRedisRateLimiter(
+  url: string,
+  options: RateLimitOptions = {},
+  prefix = "clubedge:rate-limit:",
+): RateLimiter {
+  const { requests, windowSeconds } = validateRateLimitOptions(options);
+
+  return {
+    async limit(identifier) {
+      validateRateLimitIdentifier(identifier);
+      const client = await connectRedis(url);
+      const result = await client.eval(
+        `local count = redis.call('INCR', KEYS[1])
+         if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+         return { count, redis.call('PTTL', KEYS[1]) }`,
+        { keys: [`${prefix}${identifier}`], arguments: [String(windowSeconds * 1_000)] },
+      );
+      if (!Array.isArray(result) || result.length !== 2) {
+        throw new Error("Redis returned an invalid rate limit response.");
+      }
+
+      const count = Number(result[0]);
+      const ttlMilliseconds = Number(result[1]);
+      return {
+        success: count <= requests,
+        limit: requests,
+        remaining: Math.max(0, requests - count),
+        resetAt: Date.now() + Math.max(0, ttlMilliseconds),
+      };
+    },
+  };
+}

package/template/packages/cache/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts"]
+}

package/template/packages/core/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@clubedge/core",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/template/packages/core/src/client-ip.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { getClientIp } from "./client-ip";
+
+describe("getClientIp", () => {
+  it("uses the first x-forwarded-for address", () => {
+    expect(getClientIp(new Headers({ "x-forwarded-for": "203.0.113.1, 10.0.0.1" }))).toBe(
+      "203.0.113.1",
+    );
+  });
+
+  it("falls back to x-real-ip, then to unknown", () => {
+    expect(getClientIp(new Headers({ "x-real-ip": "198.51.100.7" }))).toBe("198.51.100.7");
+    expect(getClientIp(new Headers())).toBe("unknown");
+  });
+
+  it("bounds the identifier length", () => {
+    expect(getClientIp(new Headers({ "x-forwarded-for": "a".repeat(500) }))).toHaveLength(64);
+  });
+});

package/template/packages/core/src/client-ip.ts

@@ -0,0 +1,11 @@
+/**
+ * Best-effort client address for rate limiting. Forwarded headers are only trustworthy
+ * behind a proxy that overwrites them (Vercel, Cloudflare, most load balancers).
+ */
+export function getClientIp(headers: Pick<Headers, "get">): string {
+  const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  if (forwarded) return forwarded.slice(0, 64);
+  const realIp = headers.get("x-real-ip")?.trim();
+  if (realIp) return realIp.slice(0, 64);
+  return "unknown";
+}

package/template/packages/core/src/errors.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it, vi } from "vitest";
+import { AppError, errorResponse } from "./errors";
+
+describe("errorResponse", () => {
+  it("returns a safe structured response for application errors", async () => {
+    const response = errorResponse(new AppError("Not found", "NOT_FOUND", 404));
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ error: { code: "NOT_FOUND", message: "Not found" } });
+  });
+
+  it("hides unexpected error details from clients", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const response = errorResponse(new Error("database password leaked"));
+    expect(response.status).toBe(500);
+    expect(await response.json()).toEqual({
+      error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." },
+    });
+    vi.restoreAllMocks();
+  });
+});

package/template/packages/core/src/errors.ts

@@ -0,0 +1,20 @@
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly status = 400,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "AppError";
+  }
+}
+
+export function errorResponse(error: unknown) {
+  const known = error instanceof AppError;
+  const status = known ? error.status : 500;
+  const message = known ? error.message : "An unexpected error occurred.";
+  const code = known ? error.code : "INTERNAL_ERROR";
+  if (!known) console.error("Unhandled application error", error);
+  return Response.json({ error: { code, message } }, { status });
+}

package/template/packages/core/src/index.ts

@@ -0,0 +1,4 @@
+export { AppError, errorResponse } from "./errors";
+export { getClientIp } from "./client-ip";
+export { safeRedirectPath } from "./redirect";
+export { err, ok, type Result } from "./result";

package/template/packages/core/src/redirect.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { safeRedirectPath } from "./redirect";
+
+describe("safeRedirectPath", () => {
+  it("keeps same-origin paths with query and hash", () => {
+    expect(safeRedirectPath("/dashboard")).toBe("/dashboard");
+    expect(safeRedirectPath("/projects/1?tab=a#top")).toBe("/projects/1?tab=a#top");
+  });
+
+  it.each([
+    undefined,
+    null,
+    "",
+    "dashboard",
+    "https://evil.example",
+    "//evil.example",
+    "/\\evil.example",
+    "\\\\evil.example",
+    "javascript:alert(1)",
+  ])("falls back for %j", (value) => {
+    expect(safeRedirectPath(value)).toBe("/dashboard");
+  });
+
+  it("uses the provided fallback", () => {
+    expect(safeRedirectPath("https://evil.example", "/")).toBe("/");
+  });
+});

package/template/packages/core/src/redirect.ts

@@ -0,0 +1,20 @@
+const placeholderOrigin = "http://localhost";
+
+/**
+ * Returns a same-origin path for post-authentication redirects. Anything that could leave
+ * the site (absolute URLs, protocol-relative URLs, backslash tricks) falls back.
+ */
+export function safeRedirectPath(value: unknown, fallback = "/dashboard"): string {
+  if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) {
+    return fallback;
+  }
+  if (value.includes("\\")) return fallback;
+
+  try {
+    const url = new URL(value, placeholderOrigin);
+    if (url.origin !== placeholderOrigin) return fallback;
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return fallback;
+  }
+}

package/template/packages/core/src/result.ts

@@ -0,0 +1,10 @@
+/** Expected failures are returned as values; exceptions are reserved for the unexpected. */
+export type Result<T, E extends string = string> = { ok: true; value: T } | { ok: false; error: E };
+
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function err<E extends string>(error: E): Result<never, E> {
+  return { ok: false, error };
+}

package/template/packages/core/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts"]
+}

package/template/packages/db/drizzle/0000_initial.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS "users" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"auth_user_id" uuid,
+	"email" text NOT NULL,
+	"display_name" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "users_auth_user_id_unique" UNIQUE("auth_user_id"),
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);

package/template/packages/db/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1791417600000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/template/packages/db/drizzle.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "drizzle-kit";
+import { requireDatabaseUrl } from "./scripts/load-env";
+
+export default defineConfig({
+  schema: "./src/schema/index.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+  dbCredentials: { url: requireDatabaseUrl("run drizzle-kit") },
+});

package/template/packages/db/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@clubedge/db",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "tsx scripts/migrate.ts",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:check": "drizzle-kit check",
+    "db:seed": "tsx scripts/seed.ts"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.4",
+    "postgres": "^3.4.7"
+  },
+  "devDependencies": {
+    "dotenv": "^16.6.1",
+    "drizzle-kit": "^0.31.4",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/template/packages/db/scripts/load-env.ts

@@ -0,0 +1,14 @@
+import { config } from "dotenv";
+import { resolve } from "node:path";
+
+// Database commands run from packages/db and share the app's environment file, so a project
+// has one place for secrets. Variables already set in the shell take precedence.
+for (const file of ["../../apps/web/.env.local", ".env.local"]) {
+  config({ path: resolve(process.cwd(), file), quiet: true });
+}
+
+export function requireDatabaseUrl(purpose: string): string {
+  const url = process.env.DATABASE_URL;
+  if (!url) throw new Error(`DATABASE_URL is required to ${purpose}.`);
+  return url;
+}

package/template/packages/db/scripts/migrate.ts

@@ -0,0 +1,11 @@
+import { migrate } from "drizzle-orm/postgres-js/migrator";
+import { createDb } from "../src/client";
+import { requireDatabaseUrl } from "./load-env";
+
+const db = createDb({ url: requireDatabaseUrl("run migrations") });
+try {
+  await migrate(db, { migrationsFolder: "./drizzle" });
+  console.info("Database migrations applied.");
+} finally {
+  await db.$client.end();
+}

package/template/packages/db/scripts/seed.ts

@@ -0,0 +1,14 @@
+import { createDb } from "../src/client";
+import { users } from "../src/schema";
+import { requireDatabaseUrl } from "./load-env";
+
+const db = createDb({ url: requireDatabaseUrl("seed the database") });
+try {
+  await db
+    .insert(users)
+    .values({ email: "hello@example.com", displayName: "Starter User" })
+    .onConflictDoNothing();
+  console.info("Seed complete.");
+} finally {
+  await db.$client.end();
+}

package/template/packages/db/src/client.ts

@@ -0,0 +1,22 @@
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+import * as schema from "./schema";
+
+export interface DatabaseConfig {
+  url: string;
+  /** Pool size. Keep it small for serverless and transaction poolers. */
+  maxConnections?: number;
+}
+
+export function createDb({ url, maxConnections = 1 }: DatabaseConfig) {
+  const client = postgres(url, {
+    // Required for Supabase transaction pooling and other PgBouncer-style poolers.
+    prepare: false,
+    max: maxConnections,
+    idle_timeout: 20,
+    connect_timeout: 10,
+  });
+  return drizzle({ client, schema });
+}
+
+export type Database = ReturnType<typeof createDb>;

package/template/packages/db/src/index.ts

@@ -0,0 +1,4 @@
+export { createDb, type Database, type DatabaseConfig } from "./client";
+export * as schema from "./schema";
+export * from "./schema";
+export { upsertUserProfile } from "./users";

package/template/packages/db/src/schema/index.ts

@@ -0,0 +1 @@
+export * from "./users";

package/template/packages/db/src/schema/users.ts

@@ -0,0 +1,14 @@
+import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+/** App-owned profile data. Authentication credentials remain in Supabase Auth. */
+export const users = pgTable("users", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  authUserId: uuid("auth_user_id").unique(),
+  email: text("email").notNull().unique(),
+  displayName: text("display_name"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;

package/template/packages/db/src/users.ts

@@ -0,0 +1,16 @@
+import type { Database } from "./client";
+import { users } from "./schema";
+
+/** Creates or updates the app-owned profile row for an identity-provider user. */
+export async function upsertUserProfile(
+  db: Database,
+  profile: { authUserId: string; email: string },
+): Promise<void> {
+  await db
+    .insert(users)
+    .values(profile)
+    .onConflictDoUpdate({
+      target: users.authUserId,
+      set: { email: profile.email, updatedAt: new Date() },
+    });
+}

package/template/packages/db/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts", "scripts/**/*.ts", "drizzle.config.ts"]
+}

package/template/packages/storage/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@clubedge/storage",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./s3": "./src/s3.ts",
+    "./supabase": "./src/supabase.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.850.0",
+    "@aws-sdk/s3-request-presigner": "^3.850.0",
+    "@supabase/supabase-js": "^2.57.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/template/packages/storage/src/index.ts

@@ -0,0 +1 @@
+export type { SignedUrlOptions, StorageProvider, UploadInput } from "./types";