@ramonclaudio/create-vexpo 0.1.0

package/dist/templates/default/convex/pushTokens.ts

@@ -0,0 +1,114 @@
+import { v } from "convex/values";
+
+import { internal } from "./_generated/api";
+import { internalMutation } from "./_generated/server";
+import { authMutation, authQuery } from "./functions";
+import { deviceTypeValidator } from "./validators";
+
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+const CLEANUP_BATCH = 200;
+
+export const upsert = authMutation({
+  args: { token: v.string(), deviceType: deviceTypeValidator },
+  returns: v.id("pushTokens"),
+  handler: async (ctx, { token, deviceType }) => {
+    const now = Date.now();
+    // Token may belong to a different user (device transferred), so read it
+    // by token first and reassign if needed.
+    const existing = await ctx.db
+      .query("pushTokens")
+      .withIndex("by_token", (q) => q.eq("token", token))
+      .unique();
+
+    if (existing) {
+      if (existing.userId === ctx.user._id) {
+        await ctx.db.patch(existing._id, { updatedAt: now });
+        return existing._id;
+      }
+      // Reassign token to current user (device changed owners)
+      await ctx.db.patch(existing._id, {
+        userId: ctx.user._id,
+        deviceType,
+        updatedAt: now,
+      });
+      return existing._id;
+    }
+
+    return ctx.db.insert("pushTokens", {
+      userId: ctx.user._id,
+      token,
+      deviceType,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const remove = authMutation({
+  args: { token: v.string() },
+  returns: v.null(),
+  handler: async (ctx, { token }) => {
+    const existing = await ctx.db
+      .query("pushTokens")
+      .withIndex("by_token", (q) => q.eq("token", token))
+      .unique();
+
+    if (existing && existing.userId === ctx.user._id) {
+      await ctx.db.delete(existing._id);
+    }
+    return null;
+  },
+});
+
+export const list = authQuery({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("pushTokens"),
+      _creationTime: v.number(),
+      userId: v.string(),
+      token: v.string(),
+      deviceType: deviceTypeValidator,
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    }),
+  ),
+  handler: async (ctx) => {
+    return ctx.db
+      .query("pushTokens")
+      .withIndex("by_user", (q) => q.eq("userId", ctx.user._id))
+      .collect();
+  },
+});
+
+export const removeAll = authMutation({
+  args: {},
+  returns: v.null(),
+  handler: async (ctx) => {
+    const tokens = await ctx.db
+      .query("pushTokens")
+      .withIndex("by_user", (q) => q.eq("userId", ctx.user._id))
+      .collect();
+    await Promise.all(tokens.map((t) => ctx.db.delete(t._id)));
+    return null;
+  },
+});
+
+/**
+ * Delete push tokens older than 30 days, in bounded batches. Reschedules
+ * itself when more rows remain so we never load an unbounded set into memory.
+ */
+export const cleanupStale = internalMutation({
+  args: {},
+  returns: v.number(),
+  handler: async (ctx) => {
+    const cutoff = Date.now() - THIRTY_DAYS_MS;
+    const batch = await ctx.db.query("pushTokens").order("asc").take(CLEANUP_BATCH);
+    const stale = batch.filter((t) => t._creationTime < cutoff);
+    await Promise.all(stale.map((t) => ctx.db.delete(t._id)));
+    if (batch.length === CLEANUP_BATCH) {
+      await ctx.scheduler.runAfter(0, internal.pushTokens.cleanupStale, {});
+    }
+    return stale.length;
+  },
+});

package/dist/templates/default/convex/rateLimit.ts

@@ -0,0 +1,92 @@
+/**
+ * Rate Limiting Configuration
+ *
+ * Uses the @convex-dev/rate-limiter component for application-level rate
+ * limiting.
+ *
+ * Authentication-related rate limiting (sign-in, sign-up, password reset)
+ * is handled by Better Auth at the HTTP layer. See convex/auth.ts.
+ *
+ * @see https://www.convex.dev/components/rate-limiter
+ */
+
+import { HOUR, MINUTE, RateLimiter } from "@convex-dev/rate-limiter";
+
+import { components } from "./_generated/api";
+import type { MutationCtx } from "./_generated/server";
+
+/**
+ * Rate limiter instance using the component.
+ * Defines all application rate limits in one place.
+ */
+export const rateLimiter = new RateLimiter(components.rateLimiter, {
+  // Read operations: permissive for good UX, sharded for throughput
+  apiRead: {
+    kind: "token bucket",
+    rate: 100,
+    period: MINUTE,
+    capacity: 20,
+    shards: 2,
+  },
+
+  // Write operations: stricter to prevent abuse
+  apiWrite: {
+    kind: "token bucket",
+    rate: 30,
+    period: MINUTE,
+    capacity: 10,
+  },
+
+  // General authenticated user actions
+  userAction: {
+    kind: "token bucket",
+    rate: 60,
+    period: MINUTE,
+    capacity: 10,
+  },
+
+  // For operations that MUST eventually succeed (use with reserve: true)
+  criticalAction: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+    maxReserved: 20,
+  },
+
+  // Avatar uploads (product-specific). Generous burst capacity so users
+  // tweaking their photo a few times in a row don't trip it.
+  avatarUpload: { kind: "token bucket", rate: 30, period: HOUR, capacity: 10 },
+});
+
+export type RateLimitName =
+  | "apiRead"
+  | "apiWrite"
+  | "userAction"
+  | "criticalAction"
+  | "avatarUpload";
+
+/**
+ * Apply a rate limit and throw automatically if exceeded.
+ */
+export async function rateLimitWithThrow(
+  ctx: MutationCtx,
+  name: RateLimitName,
+  key?: string,
+  count?: number,
+) {
+  return rateLimiter.limit(ctx, name, { key, count, throws: true });
+}
+
+/**
+ * Consume rate limit tokens without throwing.
+ * Returns { ok, retryAfter } so HTTP callers can build a 429 response.
+ */
+export async function consumeLimit(
+  ctx: MutationCtx,
+  name: RateLimitName,
+  key?: string,
+  count?: number,
+) {
+  return rateLimiter.limit(ctx, name, { key, count });
+}

package/dist/templates/default/convex/schema.ts

@@ -0,0 +1,28 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema(
+  {
+    // App-specific user row mirrored from Better Auth via auth triggers.
+    // Identity fields (name, email, username, image) live on the Better Auth
+    // user component and are merged in at read time by safeGetAuthenticatedUser.
+    users: defineTable({
+      authId: v.string(),
+      bio: v.optional(v.string()),
+      avatar: v.optional(v.id("_storage")),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    }).index("authId", ["authId"]),
+
+    pushTokens: defineTable({
+      userId: v.id("users"),
+      token: v.string(),
+      deviceType: v.literal("ios"),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    })
+      .index("by_user", ["userId"])
+      .index("by_token", ["token"]),
+  },
+  { strictTableNameTypes: true },
+);

package/dist/templates/default/convex/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "strict": true,
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ESNext",
+    "lib": ["ES2021", "dom"],
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["./**/*"],
+  "exclude": ["./_generated"]
+}

package/dist/templates/default/convex/users.ts

@@ -0,0 +1,279 @@
+/**
+ * User Queries and Mutations
+ *
+ * CRUD operations for the app users table.
+ * Identity fields (name, email, username, image) live on the Better Auth user
+ * and are merged in at read time by safeGetAuthenticatedUser in auth.ts.
+ */
+
+import { v } from "convex/values";
+
+import { components } from "./_generated/api";
+import type { Id } from "./_generated/dataModel";
+import type { MutationCtx } from "./_generated/server";
+import { authComponent, authUserValidator } from "./auth";
+import { validationError } from "./errors";
+import { authMutation, optionalAuthQuery } from "./functions";
+import { rateLimitWithThrow } from "./rateLimit";
+import {
+  paginatedUsersValidator,
+  publicUserProfileValidator,
+  userProfileUpdateFields,
+  validateBio,
+} from "./validators";
+
+// ============================================================================
+// Queries
+// ============================================================================
+
+/**
+ * Get the current authenticated user's profile with resolved avatar URL.
+ * Returns null when unauthenticated.
+ */
+export const getMe = optionalAuthQuery({
+  args: {},
+  returns: v.union(authUserValidator, v.null()),
+  handler: async (ctx) => {
+    return ctx.user ?? null;
+  },
+});
+
+/**
+ * Get a user by app user id with Better Auth identity fields merged in.
+ * Accepts an arbitrary string and normalizes it via `ctx.db.normalizeId`,
+ * so untrusted inputs can be passed straight through. Returns null when the
+ * id is malformed or either record is missing.
+ */
+export const getUser = optionalAuthQuery({
+  args: { userId: v.string() },
+  returns: v.union(publicUserProfileValidator, v.null()),
+  handler: async (ctx, args) => {
+    const id = ctx.db.normalizeId("users", args.userId);
+    if (!id) return null;
+
+    const user = await ctx.db.get(id);
+    if (!user) return null;
+
+    const authUser = await authComponent.getAnyUserById(ctx, user.authId);
+    if (!authUser) return null;
+
+    const avatarUrl = user.avatar
+      ? await ctx.storage.getUrl(user.avatar)
+      : (authUser.image ?? null);
+
+    return {
+      _id: user._id,
+      _creationTime: user._creationTime,
+      name: authUser.name,
+      username:
+        (authUser as { displayUsername?: string | null }).displayUsername ??
+        (authUser as { username?: string | null }).username ??
+        null,
+      avatarUrl,
+      bio: user.bio,
+    };
+  },
+});
+
+/**
+ * List users (paginated) with Better Auth identity fields merged in.
+ * Entries with a missing Better Auth record are skipped.
+ */
+export const listUsers = optionalAuthQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  returns: paginatedUsersValidator,
+  handler: async (ctx, args) => {
+    const limit = Math.min(Math.max(args.limit ?? 20, 1), 100);
+
+    const results = await ctx.db
+      .query("users")
+      .order("desc")
+      .paginate({ cursor: args.cursor ?? null, numItems: limit });
+
+    const page = await Promise.all(
+      results.page.map(async (user) => {
+        const authUser = await authComponent.getAnyUserById(ctx, user.authId);
+        if (!authUser) return null;
+        const avatarUrl = user.avatar
+          ? await ctx.storage.getUrl(user.avatar)
+          : (authUser.image ?? null);
+        return {
+          _id: user._id,
+          _creationTime: user._creationTime,
+          name: authUser.name,
+          username:
+            (authUser as { displayUsername?: string | null }).displayUsername ??
+            (authUser as { username?: string | null }).username ??
+            null,
+          avatarUrl,
+          bio: user.bio,
+        };
+      }),
+    );
+
+    return {
+      page: page.filter((entry): entry is NonNullable<typeof entry> => entry !== null),
+      continueCursor: results.continueCursor,
+      isDone: results.isDone,
+    };
+  },
+});
+
+// ============================================================================
+// Mutations
+// ============================================================================
+
+/**
+ * Update the current user's bio. Name and username changes go through
+ * Better Auth directly via authClient.updateUser on the client.
+ */
+export const updateProfile = authMutation({
+  args: userProfileUpdateFields,
+  returns: v.id("users"),
+  handler: async (ctx, args): Promise<Id<"users">> => {
+    await rateLimitWithThrow(ctx, "userAction", ctx.user._id.toString());
+
+    if (args.bio !== undefined) {
+      const result = validateBio(args.bio);
+      if (!result.valid) throw validationError(result.error!, "bio");
+    }
+
+    await ctx.db.patch(ctx.user._id, {
+      bio: args.bio,
+      updatedAt: Date.now(),
+    });
+
+    return ctx.user._id;
+  },
+});
+
+/**
+ * Generate an upload URL for avatar images.
+ * The URL expires in 1 hour.
+ */
+export const generateAvatarUploadUrl = authMutation({
+  args: {},
+  returns: v.string(),
+  handler: async (ctx) => {
+    await rateLimitWithThrow(ctx, "avatarUpload", ctx.user._id.toString());
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+
+/**
+ * Update the current user's avatar with a storage id.
+ * Deletes the previous uploaded avatar from storage if one exists.
+ * Does not touch Better Auth's image field - that's for provider-supplied URLs.
+ */
+export const updateAvatar = authMutation({
+  args: { storageId: v.id("_storage") },
+  returns: v.object({ avatarUrl: v.union(v.string(), v.null()) }),
+  handler: async (ctx, args) => {
+    await rateLimitWithThrow(ctx, "userAction", ctx.user._id.toString());
+
+    if (ctx.user.avatar) await ctx.storage.delete(ctx.user.avatar);
+
+    await ctx.db.patch(ctx.user._id, {
+      avatar: args.storageId,
+      updatedAt: Date.now(),
+    });
+
+    return { avatarUrl: await ctx.storage.getUrl(args.storageId) };
+  },
+});
+
+/**
+ * Delete the current user's uploaded avatar.
+ * Removes the file from storage and clears the avatar field. After deletion,
+ * Better Auth's image (e.g. OAuth provider avatar) is used as the fallback.
+ */
+export const deleteAvatar = authMutation({
+  args: {},
+  returns: v.object({ success: v.boolean() }),
+  handler: async (ctx) => {
+    await rateLimitWithThrow(ctx, "userAction", ctx.user._id.toString());
+
+    if (ctx.user.avatar) await ctx.storage.delete(ctx.user.avatar);
+
+    await ctx.db.patch(ctx.user._id, {
+      avatar: undefined,
+      updatedAt: Date.now(),
+    });
+
+    return { success: true };
+  },
+});
+
+/**
+ * Delete the current user's account.
+ * Removes app-owned data (push tokens) and all Better Auth records.
+ * The `users` row is dropped by the auth `onDelete` trigger.
+ */
+export const deleteAccount = authMutation({
+  args: {},
+  returns: v.object({ success: v.boolean() }),
+  handler: async (ctx) => {
+    const authUserId = ctx.user.authUserId;
+
+    const pushTokens = await ctx.db
+      .query("pushTokens")
+      .withIndex("by_user", (q) => q.eq("userId", ctx.user._id))
+      .collect();
+    await Promise.all(pushTokens.map((t) => ctx.db.delete(t._id)));
+
+    const authUser = await authComponent.safeGetAuthUser(ctx);
+
+    await deleteAllByUserId(ctx, "session", authUserId);
+    await deleteAllByUserId(ctx, "account", authUserId);
+    await deleteAllByUserId(ctx, "twoFactor", authUserId);
+    await deleteAllByUserId(ctx, "oauthAccessToken", authUserId);
+    await deleteAllByUserId(ctx, "oauthConsent", authUserId);
+    await deleteAllByUserId(ctx, "oauthApplication", authUserId);
+    if (authUser?.email) await deleteVerificationByIdentifier(ctx, authUser.email);
+
+    // Deleting the Better Auth user fires the `onDelete` trigger which
+    // removes the matching app users row and frees the avatar blob.
+    await ctx.runMutation(components.betterAuth.adapter.deleteOne, {
+      input: { model: "user", where: [{ field: "_id", value: authUserId }] },
+    });
+
+    return { success: true };
+  },
+});
+
+type UserIdModel =
+  | "session"
+  | "account"
+  | "twoFactor"
+  | "oauthAccessToken"
+  | "oauthConsent"
+  | "oauthApplication";
+
+const deleteAllByUserId = async (ctx: MutationCtx, model: UserIdModel, userId: string) => {
+  let cursor: string | null = null;
+  let isDone = false;
+  while (!isDone) {
+    const result = (await ctx.runMutation(components.betterAuth.adapter.deleteMany, {
+      input: { model, where: [{ field: "userId", value: userId }] },
+      paginationOpts: { numItems: 100, cursor },
+    })) as { isDone: boolean; continueCursor: string };
+    isDone = result.isDone;
+    cursor = result.continueCursor;
+  }
+};
+
+const deleteVerificationByIdentifier = async (ctx: MutationCtx, identifier: string) => {
+  let cursor: string | null = null;
+  let isDone = false;
+  while (!isDone) {
+    const result = (await ctx.runMutation(components.betterAuth.adapter.deleteMany, {
+      input: { model: "verification", where: [{ field: "identifier", value: identifier }] },
+      paginationOpts: { numItems: 100, cursor },
+    })) as { isDone: boolean; continueCursor: string };
+    isDone = result.isDone;
+    cursor = result.continueCursor;
+  }
+};

package/dist/templates/default/convex/validators.ts

@@ -0,0 +1,74 @@
+/**
+ * Validator Utilities
+ *
+ * Function argument and return-type validators.
+ * Schema-level field validators live in schema.ts.
+ */
+
+import { literals } from "convex-helpers/validators";
+import { v } from "convex/values";
+
+/**
+ * Paginated response structure.
+ * Spread into a v.object() alongside the page shape.
+ */
+export const paginatedResponseFields = {
+  continueCursor: v.string(),
+  isDone: v.boolean(),
+};
+
+// ============================================================================
+// User Profile Validators
+// ============================================================================
+
+/**
+ * User profile fields accepted by updateProfile.
+ * Name changes go through Better Auth (authClient.updateUser) directly.
+ */
+export const userProfileUpdateFields = {
+  bio: v.optional(v.string()),
+};
+
+/**
+ * Public user profile returned by api.users.getUser and in listUsers pages.
+ * Merges app-owned fields (bio, avatar storage resolved to URL) with Better
+ * Auth identity fields (name, username).
+ */
+export const publicUserProfileValidator = v.object({
+  _id: v.id("users"),
+  _creationTime: v.number(),
+  name: v.string(),
+  username: v.union(v.string(), v.null()),
+  avatarUrl: v.union(v.string(), v.null()),
+  bio: v.optional(v.string()),
+});
+
+/**
+ * Paginated user list response.
+ */
+export const paginatedUsersValidator = v.object({
+  page: v.array(publicUserProfileValidator),
+  ...paginatedResponseFields,
+});
+
+// ============================================================================
+// Mobile Validators
+// ============================================================================
+
+export const deviceTypeValidator = literals("ios");
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+const BIO_MAX_LENGTH = 500;
+
+/**
+ * Validate a bio field.
+ */
+export function validateBio(bio: string): { valid: boolean; error?: string } {
+  if (bio.length > BIO_MAX_LENGTH) {
+    return { valid: false, error: `Bio must be ${BIO_MAX_LENGTH} characters or less` };
+  }
+  return { valid: true };
+}