@ramonclaudio/create-vexpo 0.1.0

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

@@ -0,0 +1,46 @@
+// Shared constants and pure helpers.
+// Safe to import from Convex functions AND React routes.
+// Do not add imports from `convex/server`, `./_generated/*`, or React here.
+
+// ============================================================================
+// Username validation (Better Auth `username` plugin)
+// ============================================================================
+
+export const USERNAME_MIN_LENGTH = 3;
+export const USERNAME_MAX_LENGTH = 30;
+
+// Alphanumerics, underscores, dots. Must match the server-side
+// `usernameValidator` in convex/auth.ts to avoid client/server drift.
+export const USERNAME_FORMAT_REGEX = /^[a-zA-Z0-9_.]+$/;
+
+export const RESERVED_USERNAMES = [
+  "admin",
+  "administrator",
+  "root",
+  "system",
+  "moderator",
+  "mod",
+  "support",
+  "help",
+  "info",
+  "contact",
+  "api",
+  "www",
+  "mail",
+  "email",
+  "test",
+  "null",
+  "undefined",
+] as const;
+
+export function isReservedUsername(username: string): boolean {
+  return (RESERVED_USERNAMES as ReadonlyArray<string>).includes(username.toLowerCase());
+}
+
+export function isValidUsernameFormat(username: string): boolean {
+  return (
+    username.length >= USERNAME_MIN_LENGTH &&
+    username.length <= USERNAME_MAX_LENGTH &&
+    USERNAME_FORMAT_REGEX.test(username)
+  );
+}

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

@@ -0,0 +1,11 @@
+import { defineApp } from "convex/server";
+import betterAuth from "@convex-dev/better-auth/convex.config";
+import resend from "@convex-dev/resend/convex.config";
+import rateLimiter from "@convex-dev/rate-limiter/convex.config";
+
+const app = defineApp();
+app.use(betterAuth);
+app.use(resend);
+app.use(rateLimiter);
+
+export default app;

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

@@ -0,0 +1,42 @@
+import { cronJobs } from "convex/server";
+
+import { components, internal } from "./_generated/api";
+import { internalMutation } from "./_generated/server";
+
+const crons = cronJobs();
+
+// Drop push tokens that haven't refreshed in 30 days (stale device or app
+// uninstalled). Bounded batches via `internal.pushTokens.cleanupStale`.
+crons.daily(
+  "cleanup stale push tokens",
+  { hourUTC: 3, minuteUTC: 0 },
+  internal.pushTokens.cleanupStale,
+);
+
+// The Resend component retains finalized (delivered, cancelled, bounced)
+// emails and it's our job to clear them. Run hourly to keep the emails table
+// bounded. See @convex-dev/resend README → "Data retention".
+crons.interval(
+  "Remove old emails from the resend component",
+  { hours: 1 },
+  internal.crons.cleanupResend,
+);
+
+const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+export const cleanupResend = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    // Delivered/cancelled/bounced: 7 day retention.
+    await ctx.scheduler.runAfter(0, components.resend.lib.cleanupOldEmails, {
+      olderThan: ONE_WEEK_MS,
+    });
+    // Abandoned emails usually indicate a bug, so keep them around longer
+    // (4 weeks) for debugging before purging.
+    await ctx.scheduler.runAfter(0, components.resend.lib.cleanupAbandonedEmails, {
+      olderThan: 4 * ONE_WEEK_MS,
+    });
+  },
+});
+
+export default crons;

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

@@ -0,0 +1,109 @@
+import type { GenericCtx } from "@convex-dev/better-auth";
+import { requireRunMutationCtx } from "@convex-dev/better-auth/utils";
+import { Resend, vOnEmailEventArgs } from "@convex-dev/resend";
+import { v } from "convex/values";
+
+import { components, internal } from "./_generated/api";
+import type { DataModel } from "./_generated/dataModel";
+import { internalMutation } from "./_generated/server";
+import { env } from "./env";
+
+// testMode defaults to true so dev can't accidentally email real users.
+// Set RESEND_TEST_MODE=false in production to send to real addresses.
+// Note: @convex-dev/resend's testMode only permits @resend.dev sandbox
+// addresses and throws otherwise. To keep dev sign-up working with real-shaped
+// emails, sendAuthOTP below short-circuits when testMode is on and logs the
+// OTP to the Convex deployment console instead of calling sendEmail.
+// Explicit `: Resend` annotation is required because `onEmailEvent` references
+// a function in this same module, which would otherwise cause TS inference to
+// loop on itself.
+const testMode = process.env.RESEND_TEST_MODE !== "false";
+
+export const resend: Resend = new Resend(components.resend, {
+  testMode,
+  onEmailEvent: internal.email.handleEmailEvent,
+});
+
+/**
+ * Receives delivery events from the Resend webhook (mounted in convex/http.ts).
+ * The event payload is also automatically persisted to the component's
+ * `deliveryEvents` table for inspection in the Convex dashboard.
+ *
+ * Logs the 4 actionable failure events (bounced, complained, suppressed,
+ * failed). Extend this handler to flag the user's email as unreachable if
+ * you want to stop sending auth OTPs to addresses that will never arrive.
+ */
+const ACTIONABLE_FAILURE_EVENTS = new Set([
+  "email.bounced",
+  "email.complained",
+  "email.suppressed",
+  "email.failed",
+]);
+
+export const handleEmailEvent = internalMutation({
+  args: vOnEmailEventArgs,
+  returns: v.null(),
+  handler: async (_ctx, args) => {
+    if (ACTIONABLE_FAILURE_EVENTS.has(args.event.type)) {
+      console.warn(`[resend] ${args.event.type} for email ${args.id}`, args.event.data);
+    }
+    return null;
+  },
+});
+
+type OTPType = "sign-in" | "email-verification" | "forget-password" | "change-email";
+
+const OTP_COPY: Record<OTPType, { subject: string; heading: string; body: string }> = {
+  "sign-in": {
+    subject: "Your sign-in code",
+    heading: "Sign in",
+    body: "Use this code to sign in.",
+  },
+  "email-verification": {
+    subject: "Verify your email",
+    heading: "Verify your email",
+    body: "Enter this code to confirm your email address.",
+  },
+  "forget-password": {
+    subject: "Reset your password",
+    heading: "Reset your password",
+    body: "Use this code to reset your password. Ignore this email if you didn't request it.",
+  },
+  "change-email": {
+    subject: "Confirm your new email",
+    heading: "Confirm your new email",
+    body: "Enter this code to confirm the email change.",
+  },
+};
+
+/**
+ * Send an auth OTP email via Resend. Used by Better Auth's emailOTP plugin
+ * inside the `sendVerificationOTP` callback in convex/auth.ts.
+ *
+ * In test mode (dev default), logs the OTP to the Convex deployment console
+ * instead of calling Resend. Read it from `bunx convex dev` output or the
+ * deployment logs in the Convex dashboard. Production sets RESEND_TEST_MODE
+ * to "false" and sends real emails.
+ */
+export async function sendAuthOTP(
+  ctx: GenericCtx<DataModel>,
+  { email, otp, type }: { email: string; otp: string; type: OTPType },
+) {
+  if (testMode) {
+    console.log(`[otp] ${type} for ${email}: ${otp}`);
+    return;
+  }
+
+  const { subject, heading, body } = OTP_COPY[type];
+  await resend.sendEmail(requireRunMutationCtx(ctx), {
+    from: `${env.appName} <${env.email.from}>`,
+    to: email,
+    subject: `${env.appName}: ${subject} (${otp})`,
+    html: renderHtml(heading, body, otp),
+    text: `${heading}\n\n${body}\n\nCode: ${otp}\n\nThis code expires in 5 minutes.`,
+  });
+}
+
+function renderHtml(heading: string, body: string, otp: string): string {
+  return `<!doctype html><html><body style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;padding:32px;color:#111"><h1 style="font-size:20px;margin:0 0 16px">${heading}</h1><p style="margin:0 0 24px">${body}</p><div style="font-size:28px;letter-spacing:6px;font-weight:600;padding:16px;background:#f5f5f5;border-radius:8px;text-align:center">${otp}</div><p style="margin:24px 0 0;color:#666;font-size:13px">This code expires in 5 minutes.</p></body></html>`;
+}

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

@@ -0,0 +1,31 @@
+const optional = (key: string, fallback: string): string => process.env[key] ?? fallback;
+
+const required = (key: string): string => {
+  const value = process.env[key];
+  if (!value) throw new Error(`Missing required env var: ${key}`);
+  return value;
+};
+
+const bool = (key: string, fallback: boolean): boolean => {
+  const v = process.env[key];
+  if (v === undefined) return fallback;
+  return v === "true" || v === "1";
+};
+
+export const env = {
+  get convexSiteUrl() {
+    return required("CONVEX_SITE_URL");
+  },
+  siteUrl: optional("SITE_URL", "vexpo://"),
+  appName: optional("APP_NAME", "Vexpo"),
+  email: {
+    get from() {
+      return required("EMAIL_FROM");
+    },
+  },
+  // Email verification policy. Default `false` (minimal-tier setup, no Resend
+  // configured). sign-up creates verified-immediately accounts so the user
+  // can sign in without ever seeing an OTP. `bunx vexpo full` flips
+  // this to `true` on the Convex env when it provisions Resend.
+  requireEmailVerification: bool("REQUIRE_EMAIL_VERIFICATION", false),
+} as const;

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

@@ -0,0 +1,33 @@
+/**
+ * Structured Errors
+ *
+ * Error factories emit ConvexError with a stable code so clients can
+ * branch on `error.data.code` without parsing messages.
+ */
+
+import { ConvexError } from "convex/values";
+
+export const ErrorCode = {
+  UNAUTHENTICATED: "AUTH_1001",
+  VALIDATION_ERROR: "VAL_3001",
+} as const;
+
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+type AppErrorData = {
+  code: ErrorCodeValue;
+  message: string;
+  field?: string;
+};
+
+function createError(code: ErrorCodeValue, message: string, options?: { field?: string }) {
+  return new ConvexError({ code, message, ...options } as AppErrorData);
+}
+
+export function authenticationRequired(message = "Authentication required") {
+  return createError(ErrorCode.UNAUTHENTICATED, message);
+}
+
+export function validationError(message: string, field?: string) {
+  return createError(ErrorCode.VALIDATION_ERROR, message, { field });
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Custom Function Wrappers
+ *
+ * Authenticated query/mutation wrappers that inject the current user into
+ * the context. Uses the centralized helpers from auth.ts to avoid duplication.
+ */
+
+import { customCtx, customMutation, customQuery } from "convex-helpers/server/customFunctions";
+
+import { mutation, query } from "./_generated/server";
+import { requireAuthenticatedUser, safeGetAuthenticatedUser } from "./auth";
+import type { AuthUser } from "./auth";
+
+// Re-export AuthUser type for convenience
+export type { AuthUser };
+
+// ============================================================================
+// Query Wrappers
+// ============================================================================
+
+/**
+ * Authenticated query - throws ConvexError if user is not logged in.
+ */
+export const authQuery = customQuery(
+  query,
+  customCtx(async (ctx) => ({
+    user: await requireAuthenticatedUser(ctx),
+  })),
+);
+
+/**
+ * Optional auth query - user may be undefined.
+ * Use for endpoints that work for both authenticated and anonymous users.
+ */
+export const optionalAuthQuery = customQuery(
+  query,
+  customCtx(async (ctx) => ({
+    user: await safeGetAuthenticatedUser(ctx),
+  })),
+);
+
+// ============================================================================
+// Mutation Wrappers
+// ============================================================================
+
+/**
+ * Authenticated mutation - throws ConvexError if user is not logged in.
+ */
+export const authMutation = customMutation(
+  mutation,
+  customCtx(async (ctx) => ({
+    user: await requireAuthenticatedUser(ctx),
+  })),
+);

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

@@ -0,0 +1,176 @@
+import { httpRouter } from "convex/server";
+
+import { httpAction } from "./_generated/server";
+import { authComponent, createAuth } from "./auth";
+import { resend } from "./email";
+import { log, newRequestId } from "./log";
+import { withWebhook } from "./webhook";
+
+const http = httpRouter();
+
+// Register Better Auth routes lazily so Better Auth is not initialized at
+// module load. Reduces http.ts memory footprint during `convex deploy`.
+authComponent.registerRoutesLazy(http, createAuth);
+
+// Resend delivery events webhook. `@convex-dev/resend` ships its own Svix
+// signature verification + idempotency, so we just forward the raw request.
+// Configure the Resend dashboard webhook at
+// https://<your-deployment>.convex.site/resend-webhook and set
+// RESEND_WEBHOOK_SECRET on the Convex deployment.
+// `@convex-dev/resend`'s `handleResendEventWebhook` throws if
+// `RESEND_WEBHOOK_SECRET` is unset, and Convex's default error handling
+// serializes the stack trace into the 503 body (including absolute-ish
+// module paths). Wrap to short-circuit with a clean 503 before the library
+// runs, and wrap the library call itself so its other internal errors don't
+// leak source paths either.
+http.route({
+  path: "/resend-webhook",
+  method: "POST",
+  handler: httpAction(async (ctx, req) => {
+    if (!process.env.RESEND_WEBHOOK_SECRET) {
+      return new Response(JSON.stringify({ error: "RESEND_WEBHOOK_SECRET not configured" }), {
+        status: 503,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    try {
+      return await resend.handleResendEventWebhook(ctx, req);
+    } catch (err) {
+      log.warn({
+        event: "resend.handler_error",
+        message: err instanceof Error ? err.message : String(err),
+      });
+      return new Response(JSON.stringify({ error: "webhook handler error" }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+  }),
+});
+
+// EAS Build / Submit webhook receiver.
+//
+// Wire it up once with:
+//   bunx eas webhook:create --event BUILD  --url https://<your-deployment>.convex.site/eas-webhook --secret <strong-secret>
+//   bunx eas webhook:create --event SUBMIT --url https://<your-deployment>.convex.site/eas-webhook --secret <strong-secret>
+//   bunx convex env set EAS_WEBHOOK_SECRET <strong-secret>
+//
+// Per https://docs.expo.dev/eas/webhooks/, EAS signs every POST with
+// HMAC-SHA1 in `expo-signature: sha1=<hex>`. The factory below handles
+// the signature + body cap + structured access log; the handler here just
+// dispatches on payload shape.
+type EasWebhookPayload = {
+  id?: string;
+  status?: string;
+  platform?: string;
+  buildDetailsPageUrl?: string;
+  appId?: string;
+  metadata?: { appName?: string };
+};
+
+http.route({
+  path: "/eas-webhook",
+  method: "POST",
+  handler: httpAction(
+    withWebhook<EasWebhookPayload>(
+      {
+        source: "eas-webhook",
+        signatureHeader: "expo-signature",
+        signaturePrefix: "sha1=",
+        secretEnv: "EAS_WEBHOOK_SECRET",
+        algorithm: "sha1",
+      },
+      (_ctx, payload, { requestId }) => {
+        log.info({
+          event: "eas.received",
+          requestId,
+          easId: payload.id,
+          platform: payload.platform,
+          status: payload.status,
+          appName: payload.metadata?.appName,
+          detailsUrl: payload.buildDetailsPageUrl,
+        });
+        // Extend: dispatch on `payload.status === "errored"` to a Slack
+        // notifier, persist the build/submit row to a Convex table, etc.
+        return new Response(JSON.stringify({ ok: true, requestId }), {
+          status: 200,
+          headers: { "Content-Type": "application/json", "X-Request-Id": requestId },
+        });
+      },
+    ),
+  ),
+});
+
+// Apple universal link association file.
+//
+// Served on every cold-launch of every installed copy of the app. high
+// fanout, fully static body, cheapest possible payload wins. We:
+//   1. Construct the body deterministically from env so the ETag is stable.
+//   2. Cache for 1h with `must-revalidate` so a bundle-id change still
+//      converges within that window. Apple itself caches AASA aggressively
+//      on-device; the public CDN cache is the only tier that matters for
+//      first-install latency.
+//   3. Honor conditional GETs (`If-None-Match`) with 304s so warm callers
+//      pay only the round-trip.
+// `appID` is `<APPLE_TEAM_ID>.<BUNDLE_ID>`. Both env vars are pushed to
+// the Convex deployment by `setup:convex` (or `setup:apple`).
+http.route({
+  path: "/.well-known/apple-app-site-association",
+  method: "GET",
+  handler: httpAction(async (_ctx, req) => {
+    const requestId = newRequestId();
+    const teamId = process.env.APPLE_TEAM_ID;
+    const bundleId = process.env.APP_BUNDLE_ID;
+    if (!teamId || !bundleId) {
+      log.error({
+        event: "aasa.misconfigured",
+        requestId,
+        hasTeamId: !!teamId,
+        hasBundleId: !!bundleId,
+      });
+      return jsonError(503, "APPLE_TEAM_ID and APP_BUNDLE_ID must be set", requestId);
+    }
+    const body = JSON.stringify({
+      applinks: {
+        details: [{ appID: `${teamId}.${bundleId}`, paths: ["*"] }],
+      },
+    });
+    const etag = `"${await sha256Hex(body)}"`;
+    const ifNoneMatch = req.headers.get("if-none-match");
+    if (ifNoneMatch === etag) {
+      log.info({ event: "aasa.not_modified", requestId });
+      return new Response(null, {
+        status: 304,
+        headers: {
+          ETag: etag,
+          "Cache-Control": "public, max-age=3600, must-revalidate",
+          "X-Request-Id": requestId,
+        },
+      });
+    }
+    log.info({ event: "aasa.served", requestId, bytes: body.length });
+    return new Response(body, {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=3600, must-revalidate",
+        ETag: etag,
+        "X-Request-Id": requestId,
+      },
+    });
+  }),
+});
+
+async function sha256Hex(s: string): Promise<string> {
+  const sig = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function jsonError(status: number, message: string, requestId: string): Response {
+  return new Response(JSON.stringify({ error: message, requestId }), {
+    status,
+    headers: { "Content-Type": "application/json", "X-Request-Id": requestId },
+  });
+}
+
+export default http;

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

@@ -0,0 +1,81 @@
+// Structured one-line JSON logger for Convex HTTP handlers.
+//
+// Convex's web dashboard renders `console.log` output line-by-line. Plain
+// strings work for narrative logs but lose context once volume grows. The
+// helpers below emit single-line JSON with a stable shape so dashboards
+// and log aggregators can filter on fields directly:
+//
+//   { "ts": "...", "level": "info", "event": "webhook.ok", "requestId": "...",
+//     "durationMs": 12, "platform": "ios", "status": "finished" }
+//
+// Keep the field set small and predictable:
+//   - ts           ISO timestamp (UTC)
+//   - level        info | warn | error
+//   - event        dot-namespaced verb ("webhook.ok", "aasa.served")
+//   - requestId    set per HTTP request via `newRequestId()`
+//   - durationMs   numeric (preferred over Date arithmetic in queries)
+//   - err          { message, name, stack? } when level === "error"
+//
+// Anything else is merged in as-is. Field order is alphabetical except `ts`
+// and `level` come first for readability when scrolling raw log output.
+
+export type LogLevel = "info" | "warn" | "error";
+
+export type LogFields = Record<string, unknown> & {
+  event: string;
+  requestId?: string;
+};
+
+function emit(level: LogLevel, fields: LogFields): void {
+  const { event, ...rest } = fields;
+  const payload = {
+    ts: new Date().toISOString(),
+    level,
+    event,
+    ...rest,
+  };
+  const line = JSON.stringify(payload, replacer);
+  if (level === "error") {
+    console.error(line);
+  } else if (level === "warn") {
+    console.warn(line);
+  } else {
+    console.log(line);
+  }
+}
+
+// JSON.stringify replacer: errors don't serialize by default. Pull
+// `message`, `name`, and (only in development) `stack`.
+function replacer(_key: string, value: unknown): unknown {
+  if (value instanceof Error) {
+    return {
+      message: value.message,
+      name: value.name,
+      ...(process.env.NODE_ENV !== "production" && value.stack ? { stack: value.stack } : {}),
+    };
+  }
+  return value;
+}
+
+export const log = {
+  info(fields: LogFields): void {
+    emit("info", fields);
+  },
+  warn(fields: LogFields): void {
+    emit("warn", fields);
+  },
+  error(fields: LogFields & { err?: unknown }): void {
+    emit("error", fields);
+  },
+};
+
+// Cryptographically-random short request ID. Web crypto is available in
+// Convex's runtime. 9 bytes → 12-char base64url, plenty for correlation
+// without bloating every log line.
+export function newRequestId(): string {
+  const bytes = new Uint8Array(9);
+  crypto.getRandomValues(bytes);
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}