@ramonclaudio/create-vexpo 0.1.0

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

@@ -0,0 +1,193 @@
+// Webhook handler factory for Convex HTTP routes.
+//
+// Every webhook source we accept (EAS Build/Submit, Resend delivery events,
+// future Stripe / GitHub) follows the same shape: a signed POST with a
+// shared secret, JSON body, signature in a header. Centralising the
+// boilerplate here means each route gets:
+//
+//   - Body-size cap (defend against runaway upload eating the function budget)
+//   - Constant-time signature verification (HMAC, configurable algorithm)
+//   - Optional replay protection (timestamp window check)
+//   - Per-request correlation ID + structured access log with timing
+//   - Uniform JSON error responses with a `requestId` for grepping
+//
+// The handler the caller supplies receives the parsed JSON body, raw text
+// body (in case re-hashing is needed), and the request ID. It returns a
+// `Response`; the factory wraps timing + logging around it.
+
+import type { GenericActionCtx } from "convex/server";
+
+import { log, newRequestId } from "./log.ts";
+
+export type SignatureAlgorithm = "sha1" | "sha256";
+
+export type WithWebhookOptions = {
+  /** Stable name in logs. Example: "eas-webhook", "resend-webhook". */
+  source: string;
+  /** Request header carrying the signature. Example: "expo-signature". */
+  signatureHeader: string;
+  /** Convex env var holding the shared secret. Example: "EAS_WEBHOOK_SECRET". */
+  secretEnv: string;
+  /** HMAC algorithm. EAS uses SHA-1, Stripe uses SHA-256, Resend uses Svix's HMAC-SHA256. */
+  algorithm: SignatureAlgorithm;
+  /**
+   * Prefix expected in the signature header before the hex digest.
+   * EAS sends `sha1=<hex>`, Stripe sends `t=<ts>,v1=<hex>`, etc. Default `""`.
+   */
+  signaturePrefix?: string;
+  /** Cap the request body size in bytes. Defaults to 1 MiB. */
+  maxBodyBytes?: number;
+  /**
+   * Optional max age of the request in seconds. If set, the handler reads
+   * the timestamp from the named header and rejects if too old. Defaults
+   * to "no replay window check."
+   */
+  replay?: {
+    header: string;
+    /** Allowed clock skew in seconds. */
+    maxAgeSeconds: number;
+  };
+};
+
+export type WebhookContext = {
+  requestId: string;
+  rawBody: string;
+};
+
+export type WebhookHandler<T> = (
+  ctx: GenericActionCtx<Record<string, never>>,
+  payload: T,
+  webhookCtx: WebhookContext,
+) => Promise<Response> | Response;
+
+export function withWebhook<T = unknown>(
+  opts: WithWebhookOptions,
+  handler: WebhookHandler<T>,
+): (ctx: GenericActionCtx<Record<string, never>>, req: Request) => Promise<Response> {
+  const maxBodyBytes = opts.maxBodyBytes ?? 1024 * 1024;
+  const prefix = opts.signaturePrefix ?? "";
+
+  return async (ctx, req) => {
+    const start = Date.now();
+    const requestId = newRequestId();
+    const baseFields = { event: "webhook", requestId, source: opts.source };
+
+    const secret = process.env[opts.secretEnv];
+    if (!secret) {
+      log.error({ ...baseFields, event: "webhook.misconfigured", secretEnv: opts.secretEnv });
+      return jsonError(503, "webhook secret not configured", requestId);
+    }
+
+    const signatureHeaderValue = req.headers.get(opts.signatureHeader);
+    if (!signatureHeaderValue) {
+      log.warn({ ...baseFields, event: "webhook.missing_signature" });
+      return jsonError(401, `missing ${opts.signatureHeader}`, requestId);
+    }
+
+    if (opts.replay) {
+      const tsHeader = req.headers.get(opts.replay.header);
+      if (!tsHeader) {
+        log.warn({ ...baseFields, event: "webhook.missing_timestamp" });
+        return jsonError(401, `missing ${opts.replay.header}`, requestId);
+      }
+      const ts = Number(tsHeader);
+      if (!Number.isFinite(ts)) {
+        log.warn({ ...baseFields, event: "webhook.bad_timestamp", tsHeader });
+        return jsonError(401, "bad timestamp", requestId);
+      }
+      const ageSeconds = (Date.now() - ts) / 1000;
+      if (Math.abs(ageSeconds) > opts.replay.maxAgeSeconds) {
+        log.warn({ ...baseFields, event: "webhook.stale", ageSeconds });
+        return jsonError(401, "timestamp out of window", requestId);
+      }
+    }
+
+    const contentLength = Number(req.headers.get("content-length") ?? "0");
+    if (contentLength > maxBodyBytes) {
+      log.warn({ ...baseFields, event: "webhook.too_large", contentLength });
+      return jsonError(413, "payload too large", requestId);
+    }
+
+    const rawBody = await req.text();
+    if (rawBody.length > maxBodyBytes) {
+      log.warn({ ...baseFields, event: "webhook.too_large", bytes: rawBody.length });
+      return jsonError(413, "payload too large", requestId);
+    }
+
+    const computed = prefix + (await hmacHex(opts.algorithm, secret, rawBody));
+    if (!timingSafeEqual(computed, signatureHeaderValue)) {
+      log.warn({ ...baseFields, event: "webhook.bad_signature" });
+      return jsonError(401, "signature mismatch", requestId);
+    }
+
+    let payload: T;
+    try {
+      payload = JSON.parse(rawBody) as T;
+    } catch {
+      log.warn({ ...baseFields, event: "webhook.bad_json" });
+      return jsonError(400, "invalid json", requestId);
+    }
+
+    try {
+      const response = await handler(ctx, payload, { requestId, rawBody });
+      log.info({
+        ...baseFields,
+        event: "webhook.ok",
+        status: response.status,
+        durationMs: Date.now() - start,
+      });
+      // Always attach X-Request-Id to the response so callers can correlate
+      // logs even when the handler doesn't set it explicitly. Don't clobber
+      // a value the handler already chose.
+      if (!response.headers.get("X-Request-Id")) {
+        const headers = new Headers(response.headers);
+        headers.set("X-Request-Id", requestId);
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers,
+        });
+      }
+      return response;
+    } catch (err) {
+      log.error({
+        ...baseFields,
+        event: "webhook.handler_error",
+        durationMs: Date.now() - start,
+        err,
+      });
+      return jsonError(500, "handler error", requestId);
+    }
+  };
+}
+
+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 },
+  });
+}
+
+async function hmacHex(
+  algorithm: SignatureAlgorithm,
+  secret: string,
+  body: string,
+): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: algorithm === "sha1" ? "SHA-1" : "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/dist/templates/default/convex.json

@@ -0,0 +1,6 @@
+{
+  "bundler": {
+    "includeSourcesContent": false
+  },
+  "typescriptCompiler": "tsgo"
+}

package/dist/templates/default/eas.json

@@ -0,0 +1,56 @@
+{
+  "cli": {
+    "version": ">= 16.0.1",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "channel": "development",
+      "autoIncrement": true,
+      "env": {},
+      "cache": {
+        "paths": ["node_modules", "ios/Pods"]
+      }
+    },
+    "development:simulator": {
+      "extends": "development",
+      "env": {},
+      "ios": {
+        "simulator": true
+      }
+    },
+    "development:device": {
+      "extends": "development",
+      "env": {},
+      "ios": {
+        "simulator": false
+      }
+    },
+    "production": {
+      "autoIncrement": true,
+      "channel": "production",
+      "distribution": "store",
+      "env": {},
+      "cache": {
+        "paths": ["node_modules", "ios/Pods"]
+      },
+      "ios": {
+        "credentialsSource": "remote"
+      }
+    }
+  },
+  "submit": {
+    "testflight": {
+      "ios": {
+        "metadataPath": "./store.config.json"
+      }
+    },
+    "production": {
+      "ios": {
+        "metadataPath": "./store.config.json"
+      }
+    }
+  }
+}

package/dist/templates/default/fingerprint.config.js

@@ -0,0 +1,9 @@
+/** @type {import('expo/fingerprint').Config} */
+const config = {
+  sourceSkips: [
+    "ExpoConfigVersions",
+    "ExpoConfigRuntimeVersionIfString",
+    "PackageJsonAndroidAndIosScriptsIfNotContainRun",
+  ],
+};
+module.exports = config;

package/dist/templates/default/hooks/use-debounce.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Returns a value that lags the input by `delay` milliseconds. Useful for
+ * coalescing rapid changes (typing, scroll, etc.) before kicking off a more
+ * expensive operation downstream (filtering, fetching, rendering a big list).
+ *
+ * Each input change resets the timer, so the returned value only updates
+ * after `delay` ms have passed without further changes.
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+
+  return debounced;
+}

package/dist/templates/default/hooks/use-deep-link.ts

@@ -0,0 +1,43 @@
+import { useEffect } from "react";
+import { useURL } from "expo-linking";
+import { router, type Href } from "expo-router";
+
+import { authClient } from "@/lib/auth-client";
+import { resolveDeepLink } from "@/lib/deep-link";
+
+const ROUTES: Record<string, Href> = {
+  "/linked": "/linked" as Href,
+};
+
+/**
+ * Listens for deep link URLs and pushes to the matching route.
+ *
+ * Only runs once authenticated. Invalid or disallowed links are ignored.
+ * Query params are forwarded as route params.
+ */
+export function useDeepLinkHandler() {
+  // See note in app/_layout.tsx: Better Auth session is the canonical signal.
+  // `useConvexAuth` is unreliable due to the bridge's sessionId churn.
+  const { data: session } = authClient.useSession();
+  const isAuthenticated = !!session?.session;
+  const url = useURL();
+
+  useEffect(() => {
+    if (!isAuthenticated || !url) return;
+
+    let resolved;
+    try {
+      resolved = resolveDeepLink(url);
+    } catch (err) {
+      if (__DEV__) console.warn("[DeepLink] parse failed:", err);
+      return;
+    }
+
+    if (!resolved.path) return;
+
+    const target = ROUTES[resolved.path];
+    if (!target) return;
+
+    router.push({ pathname: target, params: resolved.params } as Href);
+  }, [isAuthenticated, url]);
+}

package/dist/templates/default/hooks/use-navigation-tracking.ts

@@ -0,0 +1,15 @@
+import { useEffect, useRef } from "react";
+import { usePathname, useSegments } from "expo-router";
+
+export function useNavigationTracking() {
+  const pathname = usePathname();
+  const segments = useSegments();
+  const prev = useRef(pathname);
+
+  useEffect(() => {
+    if (!__DEV__) return;
+    if (pathname === prev.current) return;
+    prev.current = pathname;
+    console.log("[Nav]", pathname, segments);
+  }, [pathname, segments]);
+}

package/dist/templates/default/hooks/use-network.ts

@@ -0,0 +1,11 @@
+import { useNetworkState } from "expo-network";
+
+export function useNetwork() {
+  const { isConnected, isInternetReachable } = useNetworkState();
+
+  return {
+    isConnected,
+    isInternetReachable,
+    isOffline: isConnected === false || isInternetReachable === false,
+  };
+}

package/dist/templates/default/hooks/use-notifications.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef, useState } from "react";
+import * as Notifications from "expo-notifications";
+import { useConvexAuth } from "convex/react";
+import { useMutation } from "convex/react";
+import { router } from "expo-router";
+
+import { api } from "@/convex/_generated/api";
+import { isValidDeepLink } from "@/lib/deep-link";
+import {
+  getExpoPushToken,
+  requestPermission,
+  clearLastNotificationResponse,
+} from "@/lib/notifications";
+
+interface UseNotificationsOptions {
+  onNotificationReceived?: (notification: Notifications.Notification) => void;
+  onNotificationResponse?: (response: Notifications.NotificationResponse) => void;
+  onNotificationsDropped?: () => void;
+}
+
+/**
+ * If a notification's payload includes a `url` string, route to it after
+ * deep-link validation. Add custom action handling (categories, button taps,
+ * inline replies) here when your app needs it.
+ */
+function handleNotificationResponse(response: Notifications.NotificationResponse) {
+  const url = response.notification.request.content.data?.url;
+  if (typeof url !== "string") return;
+
+  if (isValidDeepLink(url)) {
+    router.push(url as Parameters<typeof router.push>[0]);
+  } else if (__DEV__) {
+    console.warn("[Notification] Blocked navigation to:", url);
+  }
+}
+
+export function useNotifications(options?: UseNotificationsOptions) {
+  const { isAuthenticated } = useConvexAuth();
+  const upsertToken = useMutation(api.pushTokens.upsert);
+  const registered = useRef(false);
+  const [expoPushToken, setExpoPushToken] = useState<string | null>(null);
+
+  // Register push token when authenticated
+  useEffect(() => {
+    if (!isAuthenticated) {
+      registered.current = false;
+      setExpoPushToken(null);
+      return;
+    }
+    if (registered.current) return;
+    registered.current = true;
+
+    (async () => {
+      const { granted } = await requestPermission();
+      if (!granted) return;
+
+      const token = await getExpoPushToken();
+      if (!token) return;
+
+      setExpoPushToken(token);
+      await upsertToken({ token, deviceType: "ios" });
+    })();
+  }, [isAuthenticated, upsertToken]);
+
+  // Event listeners
+  useEffect(() => {
+    const receivedSub = Notifications.addNotificationReceivedListener((notification) => {
+      if (__DEV__) console.log("[Notification] Received:", notification.request.identifier);
+      options?.onNotificationReceived?.(notification);
+    });
+
+    const responseSub = Notifications.addNotificationResponseReceivedListener((response) => {
+      if (__DEV__) console.log("[Notification] Response:", response.actionIdentifier);
+      handleNotificationResponse(response);
+      options?.onNotificationResponse?.(response);
+    });
+
+    const droppedSub = Notifications.addNotificationsDroppedListener(() => {
+      if (__DEV__) console.log("[Notification] Notifications dropped");
+      options?.onNotificationsDropped?.();
+    });
+
+    const tokenSub = Notifications.addPushTokenListener(async (token) => {
+      if (__DEV__) console.log("[Notification] Token rotated:", token.data);
+      if (isAuthenticated && typeof token.data === "string") {
+        await upsertToken({ token: token.data, deviceType: "ios" });
+      }
+    });
+
+    return () => {
+      receivedSub.remove();
+      responseSub.remove();
+      droppedSub.remove();
+      tokenSub.remove();
+    };
+  }, [isAuthenticated, options, upsertToken]);
+
+  // Cold-start deep linking
+  const lastResponse = Notifications.useLastNotificationResponse();
+  useEffect(() => {
+    if (!lastResponse) return;
+    handleNotificationResponse(lastResponse);
+    clearLastNotificationResponse();
+  }, [lastResponse]);
+
+  return { expoPushToken };
+}

package/dist/templates/default/hooks/use-onboarding.ts

@@ -0,0 +1,15 @@
+import "expo-sqlite/localStorage/install";
+import { useState } from "react";
+
+const ONBOARDING_KEY = "onboarding_seen";
+
+export function useOnboarding() {
+  const [seen, setSeen] = useState<boolean>(localStorage.getItem(ONBOARDING_KEY) === "true");
+
+  const markSeen = () => {
+    localStorage.setItem(ONBOARDING_KEY, "true");
+    setSeen(true);
+  };
+
+  return { seen, markSeen };
+}

package/dist/templates/default/hooks/use-reduced-motion.ts

@@ -0,0 +1,11 @@
+import { useReducedMotion as useSystemReducedMotion } from "react-native-reanimated";
+
+import { useReduceMotionPref } from "@/lib/preferences";
+
+export function useReducedMotion(): boolean {
+  const [pref] = useReduceMotionPref();
+  const systemOn = useSystemReducedMotion();
+  if (pref === "always") return true;
+  if (pref === "never") return false;
+  return systemOn;
+}

package/dist/templates/default/hooks/use-theme.ts

@@ -0,0 +1,53 @@
+import { useSyncExternalStore } from "react";
+import { Appearance, useColorScheme as useRNColorScheme } from "react-native";
+
+import { createStorage } from "@/lib/storage";
+import { Colors, type ColorPalette } from "@/constants/theme";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+const store = createStorage<ThemeMode>("pref.theme.mode", "system");
+
+function applyToWindow(mode: ThemeMode) {
+  Appearance.setColorScheme(mode === "system" ? "unspecified" : mode);
+}
+
+applyToWindow(store.get());
+
+export function setTheme(mode: ThemeMode) {
+  store.set(mode);
+  applyToWindow(mode);
+}
+
+export function getTheme(): ThemeMode {
+  return store.get();
+}
+
+export function useColorScheme(): "light" | "dark" {
+  const mode = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const systemScheme = useRNColorScheme();
+  if (mode === "system") return systemScheme === "dark" ? "dark" : "light";
+  return mode;
+}
+
+export function useThemeMode(): {
+  mode: ThemeMode;
+  setMode: (mode: ThemeMode) => void;
+} {
+  const mode = useSyncExternalStore(store.subscribe, store.get, store.get);
+  return { mode, setMode: setTheme };
+}
+
+export function useColors(): ColorPalette {
+  return Colors;
+}
+
+// Theme-aware asset selector. Pass the light variant first, dark second.
+// Returns whichever matches the active appearance (which honors the in-app
+// override from `setTheme` in addition to the system setting).
+//
+//   const icon = useThemedAsset(assets.brandIconLight, assets.brandIconDark);
+export function useThemedAsset<L, D>(light: L, dark: D): L | D {
+  const scheme = useColorScheme();
+  return scheme === "dark" ? dark : light;
+}

package/dist/templates/default/hooks/use-updates.ts

@@ -0,0 +1,86 @@
+import { useEffect } from "react";
+
+import {
+  useUpdates,
+  isEnabled,
+  checkForUpdate as checkForUpdateFn,
+  fetchUpdate,
+  reload,
+  buildReloadScreenConfig,
+} from "@/lib/updates";
+import { haptics } from "@/lib/haptics";
+import { useColorScheme } from "@/hooks/use-theme";
+import { useReducedMotion } from "@/hooks/use-reduced-motion";
+
+type UpdatesState = ReturnType<typeof useUpdates>;
+
+function deriveStatusText(state: UpdatesState): string {
+  if (state.isRestarting) return "Restarting...";
+  if (state.isUpdatePending) return "Restarting...";
+  if (state.isDownloading) {
+    const pct =
+      state.downloadProgress != null ? ` ${Math.round(state.downloadProgress * 100)}%` : "";
+    return `Downloading...${pct}`;
+  }
+  if (state.isChecking) return "Checking...";
+  if (state.downloadError) return state.downloadError.message;
+  if (state.checkError) return state.checkError.message;
+  if (state.isUpdateAvailable) return "Update available";
+  return "Up to date";
+}
+
+const NOOP_STATE: UpdatesState = {
+  currentlyRunning: {
+    isEmbeddedLaunch: true,
+    isEmergencyLaunch: false,
+    emergencyLaunchReason: null,
+  },
+  isStartupProcedureRunning: false,
+  isUpdateAvailable: false,
+  isUpdatePending: false,
+  isChecking: false,
+  isDownloading: false,
+  isRestarting: false,
+  restartCount: 0,
+};
+
+function useUpdatesImpl(): UpdatesState {
+  const enabled = isEnabled && !__DEV__;
+  const state = useUpdates();
+  const scheme = useColorScheme();
+  const reduceMotion = useReducedMotion();
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (state.isUpdatePending) {
+      reload({ reloadScreenOptions: buildReloadScreenConfig(scheme, reduceMotion) });
+    }
+  }, [enabled, state.isUpdatePending, scheme, reduceMotion]);
+
+  return enabled ? state : NOOP_STATE;
+}
+
+export function useAppUpdates() {
+  const state = useUpdatesImpl();
+
+  const checkForUpdate = () => {
+    if (state.isChecking) return;
+    haptics.light();
+    checkForUpdateFn();
+  };
+
+  const downloadAndApply = () => {
+    if (state.isDownloading) return;
+    haptics.light();
+    fetchUpdate();
+  };
+
+  const statusText = deriveStatusText(state);
+
+  return {
+    ...state,
+    checkForUpdate,
+    downloadAndApply,
+    statusText,
+  };
+}

package/dist/templates/default/lib/a11y.ts

@@ -0,0 +1,5 @@
+import { AccessibilityInfo } from "react-native";
+
+export function announce(message: string) {
+  AccessibilityInfo.announceForAccessibility(message);
+}

package/dist/templates/default/lib/app.ts

@@ -0,0 +1,14 @@
+import { reloadAppAsync as _reloadAppAsync } from "expo";
+
+export { executionEnvironment } from "./device";
+
+/**
+ * Force-reload the app using the current JS bundle.
+ *
+ * Unlike `Updates.reloadAsync()`, this does NOT fetch or apply a new update.
+ * It simply restarts the JS runtime with the same bundle.
+ *
+ * Use for: auth state corruption, unrecoverable cache errors, language changes
+ * that require a full restart, or a manual "restart app" button in settings.
+ */
+export const reloadApp = _reloadAppAsync;

package/dist/templates/default/lib/assets.ts

@@ -0,0 +1,17 @@
+// Runtime asset registry. The five files referenced below live in ./assets/.
+// To rebrand, replace the PNGs in place with your own renders at the same
+// dimensions and file names. See DESIGN.md for the surface specs.
+//
+// Surfaces:
+//   icon           iOS bundle icon, 1024x1024 (iOS rounds the corners)
+//   brandIcon*     in-app chiclet (welcome, sign-in, sign-up, loading)
+//   splash*        expo-splash-screen image, sits on configured bg color
+export const assets = {
+  icon: require("@/assets/icon.png"),
+  brandIconLight: require("@/assets/brand-icon-light.png"),
+  brandIconDark: require("@/assets/brand-icon-dark.png"),
+  splashLight: require("@/assets/splash-image-light.png"),
+  splashDark: require("@/assets/splash-image-dark.png"),
+} as const;
+
+export const assetModules = Object.values(assets);