anhedral 0.1.7 → 0.1.9

package/README.md

@@ -39,6 +39,7 @@ pnpm install
 ├─ packages/
 │  ├─ api-client/   shared typed API client
 │  ├─ config/       shared config helpers
+│  ├─ contracts/    shared Zod request/response contracts
 │  ├─ db/           Drizzle schema, Neon client, migrations
 │  └─ types/        shared TypeScript types
 ├─ PRODUCTION.md    deployment checklist
@@ -69,6 +70,30 @@ Anhedral supports one carefully maintained stack:
 
 The goal is stability. The generated project avoids framework sprawl, duplicate schemas, and separate frontend/backend/extension repositories.
 
+## Why This Stack
+
+Anhedral is built around one idea: a startup should be able to launch every major client from one repository without committing to infrastructure that becomes expensive, fragmented, or hard to change later.
+
+The stack is intentionally narrow:
+
+| Choice | Why Anhedral uses it |
+| --- | --- |
+| Expo | One React Native codebase targets web browsers, iOS, and Android. Compared with separate web and native apps, Expo keeps product iteration faster and avoids rebuilding shared screens, auth flows, and client logic three times. |
+| React Native Reusables | It brings shadcn-style primitives to React Native and Expo without locking the app into a heavy design system. Compared with bespoke component scaffolds, it gives teams accessible primitives they can replace or extend as the product becomes specific. |
+| Fastify | Fastify is small, fast, TypeScript-friendly, and works well as a central API layer on Vercel. Compared with pushing logic into many frontend routes, serverless functions, or client SDK calls, a Fastify backend centralizes auth, billing, storage, database access, webhooks, and internal APIs in one place. |
+| TypeScript | The whole stack shares types, contracts, and API clients. Compared with untyped template code, this catches frontend/backend drift before deploy and makes the generated app safer to evolve. |
+| Zod contracts | Request and response schemas live in shared packages. Compared with duplicating interfaces across clients, Zod lets the backend validate inputs while the frontend parses responses from the same source of truth. |
+| Neon + Drizzle | Neon gives serverless Postgres that can start free and scale with usage; Drizzle keeps schema and queries close to TypeScript. Compared with proprietary document databases or opaque ORMs, this keeps the data layer portable, SQL-native, and easy to inspect. |
+| Cloudflare R2/CDN | R2 provides S3-compatible object storage without S3-style egress fees. Compared with storing files in the database or coupling uploads to one app client, signed storage routes give every client the same upload/download primitive. |
+| Clerk | Clerk handles modern auth across web, native, and extension clients. Compared with hand-rolled auth, it removes a high-risk surface area while still letting the backend own authorization decisions. |
+| RevenueCat + Stripe | RevenueCat coordinates native subscriptions and Stripe web billing behind one entitlement model. Compared with separate payment implementations per platform, the backend can ask one question: what is this user allowed to access? |
+| WXT | WXT gives the Chrome extension a modern TypeScript/Vite workflow and supports the Side Panel API. Compared with hand-maintained manifest scaffolds, it reduces extension build and packaging mistakes. |
+| Vercel | Vercel deploys the Expo web app and Fastify API from the same Git repository with separate project roots. Compared with manually wiring CI/CD early, teams get preview deployments and production deploys from normal commits. |
+
+Every part of the stack can be started on free tiers and scales automatically as traffic grows. That matters because the first production architecture should not force a team to choose between moving quickly and being able to handle success.
+
+The bigger advantage is architectural: Anhedral creates all target clients plus one backend that can serve internal and external requests. Product logic, auth decisions, subscription entitlements, storage access, database writes, and webhooks have a central home. That helps startups avoid the common failure mode where every client invents its own rules, and the team later cannot respond quickly when the product needs to shift.
+
 ## Local Development
 
 From the generated project root:

package/dist/dependencies.d.ts

@@ -13,6 +13,7 @@ export declare const TOOLCHAIN_DEPENDENCIES: {
 export declare const ROOT_DEPENDENCIES: DependencyGroup;
 export declare const SHARED_DB_DEPENDENCIES: DependencyGroup;
 export declare const SHARED_PACKAGE_DEPENDENCIES: DependencyGroup;
+export declare const CONTRACTS_DEPENDENCIES: DependencyGroup;
 export declare const API_CLIENT_DEPENDENCIES: DependencyGroup;
 export declare const BACKEND_DEPENDENCIES: DependencyGroup;
 export declare const EXTENSION_DEPENDENCIES: DependencyGroup;
@@ -27,6 +28,7 @@ export declare function dependencyManifest(): {
         readonly wxt: "0.20.25";
     };
     root: DependencyGroup;
+    contracts: DependencyGroup;
     sharedDb: DependencyGroup;
     sharedPackages: DependencyGroup;
     backend: DependencyGroup;

package/dist/dependencies.js

@@ -40,16 +40,26 @@ export const SHARED_PACKAGE_DEPENDENCIES = {
         typescript: '5.9.3',
     },
 };
+export const CONTRACTS_DEPENDENCIES = {
+    dependencies: {
+        // renovate: datasource=npm depName=zod
+        zod: '4.2.1',
+    },
+    ...SHARED_PACKAGE_DEPENDENCIES,
+};
 export const API_CLIENT_DEPENDENCIES = {
     dependencies: {
-        '@anhedral/config': 'workspace:*',
-        '@anhedral/types': 'workspace:*',
+        '@shared/config': 'workspace:*',
+        '@shared/contracts': 'workspace:*',
+        '@shared/types': 'workspace:*',
+        zod: CONTRACTS_DEPENDENCIES.dependencies.zod,
     },
     ...SHARED_PACKAGE_DEPENDENCIES,
 };
 export const BACKEND_DEPENDENCIES = {
     dependencies: {
-        '@anhedral/db': 'workspace:*',
+        '@shared/contracts': 'workspace:*',
+        '@shared/db': 'workspace:*',
         // renovate: datasource=npm depName=fastify
         fastify: '5.6.2',
         // renovate: datasource=npm depName=fastify-plugin
@@ -81,6 +91,7 @@ export const BACKEND_DEPENDENCIES = {
         // renovate: datasource=npm depName=@aws-sdk/s3-request-presigner
         '@aws-sdk/s3-request-presigner': '3.1047.0',
         dotenv: SHARED_DB_DEPENDENCIES.dependencies.dotenv,
+        zod: CONTRACTS_DEPENDENCIES.dependencies.zod,
     },
     devDependencies: {
         typescript: SHARED_DB_DEPENDENCIES.devDependencies.typescript,
@@ -105,7 +116,7 @@ export const BACKEND_DEPENDENCIES = {
 };
 export const EXTENSION_DEPENDENCIES = {
     dependencies: {
-        '@anhedral/api-client': 'workspace:*',
+        '@shared/api-client': 'workspace:*',
         // renovate: datasource=npm depName=@clerk/chrome-extension
         '@clerk/chrome-extension': '3.1.25',
         // renovate: datasource=npm depName=react
@@ -141,7 +152,7 @@ export const EXTENSION_DEPENDENCIES = {
     },
 };
 export const FRONTEND_ADDON_DEPENDENCIES = {
-    '@anhedral/api-client': 'workspace:*',
+    '@shared/api-client': 'workspace:*',
     // renovate: datasource=npm depName=@clerk/expo
     '@clerk/expo': '3.2.11',
     // renovate: datasource=npm depName=react-native-purchases
@@ -164,6 +175,7 @@ export function dependencyManifest() {
         packageManager: PACKAGE_MANAGER,
         toolchain: TOOLCHAIN_DEPENDENCIES,
         root: ROOT_DEPENDENCIES,
+        contracts: CONTRACTS_DEPENDENCIES,
         sharedDb: SHARED_DB_DEPENDENCIES,
         sharedPackages: SHARED_PACKAGE_DEPENDENCIES,
         backend: BACKEND_DEPENDENCIES,

package/dist/scaffold.js

@@ -4,7 +4,7 @@ import { env } from 'node:process';
 import { anhedralPrint } from './print.js';
 import { appendGitignore, writeFile } from './util.js';
 import { getSkillCommands } from './commands.js';
-import { API_CLIENT_DEPENDENCIES, PACKAGE_MANAGER, ROOT_DEPENDENCIES, SHARED_DB_DEPENDENCIES, SHARED_PACKAGE_DEPENDENCIES, dependencyManifest, } from './dependencies.js';
+import { API_CLIENT_DEPENDENCIES, CONTRACTS_DEPENDENCIES, PACKAGE_MANAGER, ROOT_DEPENDENCIES, SHARED_DB_DEPENDENCIES, SHARED_PACKAGE_DEPENDENCIES, dependencyManifest, } from './dependencies.js';
 import { resolveToolchain } from './toolchain.js';
 import { scaffoldBackend } from './templates/backend.js';
 import { scaffoldExtension } from './templates/extension.js';
@@ -259,6 +259,7 @@ The generated app is one pnpm monorepo:
 ├─ packages/
 │  ├─ api-client/   shared typed API client
 │  ├─ config/       shared config constants/helpers
+│  ├─ contracts/    shared Zod request/response contracts
 │  ├─ db/           Drizzle schema, Neon client, migrations
 │  └─ types/        shared TypeScript types
 ├─ PRODUCTION.md    development and deployment guide
@@ -292,7 +293,7 @@ Important files:
 - \`Backend/src/index.ts\`: Vercel Fastify entrypoint
 - \`Backend/src/app.ts\`: Fastify app construction
 - \`Backend/vercel.json\`: minimal Vercel config
-- \`Backend/src/routes\`: health/auth/subscription routes
+- \`Backend/src/routes\`: health/auth/subscription/storage routes
 
 ## Extension
 
@@ -337,6 +338,8 @@ Database workflow:
 \`\`\`sh
 pnpm db:generate
 pnpm db:migrate
+pnpm db:studio
+pnpm db:check
 \`\`\`
 
 Local demo mode is enabled through generated \`.env\` files. Real provider behavior needs Clerk, RevenueCat/Stripe, Neon, and R2 credentials.
@@ -419,7 +422,8 @@ Steps:
 1. Create an R2 bucket.
 2. Create a least-privilege API token for that bucket.
 3. Set \`R2_ACCOUNT_ID\`, \`R2_ACCESS_KEY_ID\`, \`R2_SECRET_ACCESS_KEY\`, and \`R2_BUCKET\` only in Backend envs.
-4. Configure a public bucket URL or custom domain if uploaded assets need public CDN delivery.
+4. Use \`POST /storage/uploads\` to create signed upload URLs, then \`GET /storage/files/:key\` or \`DELETE /storage/files/:key\` for user-owned objects.
+5. Configure a public bucket URL or custom domain if uploaded assets need public CDN delivery.
 
 ## Deploy
 
@@ -462,7 +466,7 @@ Upload \`Extension/.output/*-chrome.zip\` to the Chrome Web Store Developer Dash
 - Confirm Clerk works on local web, Vercel web, iOS, Android, and the Chrome extension.
 - Confirm RevenueCat returns the \`pro\` entitlement after Stripe web purchase and native store purchase.
 - Confirm \`pnpm db:migrate\` has run against the production Neon database.
-- Confirm R2 upload and signed URL retrieval work from the deployed Backend domain if you expose storage routes.
+- Confirm R2 upload, signed URL retrieval, and deletion work from the deployed Backend domain.
 - Confirm both Vercel projects can resolve \`packages/*\` workspace packages.
 - Confirm the Chrome extension ZIP is tested locally with \`chrome://extensions\` before Chrome Web Store upload.
 
@@ -492,7 +496,7 @@ function writeStackFile(root, stack) {
 function writeSharedPackages(root) {
     const dbRoot = path.join(root, 'packages/db');
     writeFile(path.join(dbRoot, 'package.json'), JSON.stringify({
-        name: '@anhedral/db',
+        name: '@shared/db',
         version: '0.1.0',
         private: true,
         type: 'module',
@@ -507,6 +511,8 @@ function writeSharedPackages(root) {
             typecheck: 'tsc --noEmit',
             'db:generate': 'drizzle-kit generate',
             'db:migrate': 'tsx --env-file=../../.env src/migrate.ts',
+            'db:studio': 'drizzle-kit studio',
+            'db:check': 'drizzle-kit check',
         },
         dependencies: SHARED_DB_DEPENDENCIES.dependencies,
         devDependencies: SHARED_DB_DEPENDENCIES.devDependencies,
@@ -780,46 +786,104 @@ console.log('Migrations completed in', Date.now() - start, 'ms');
 `);
     writeFile(path.join(dbRoot, 'migrations/.gitkeep'), '');
     const simplePackages = [
-        ['types', { exports: { '.': './src/index.ts' } }, `export type ApiEnvelope<T> = { data: T } | { error: string; message: string };
-export type ClientPlatform = 'frontend' | 'extension';
-export type SubscriptionEntitlements = {
-  pro: boolean;
-  inTrial: boolean;
-  trialEndsAt?: string;
-  expiresAt?: string;
-  periodStart?: string;
-  periodEnd?: string;
-  method?: 'trialing' | 'redeemed' | 'paid' | null;
-  managementUrl?: string;
-  cancelAtPeriodEnd?: boolean;
-};
-export type AuthMeResponse = {
-  user: {
-    id: string;
-    email: string;
-    firstName?: string | null;
-    lastName?: string | null;
-    displayName: string;
-    imageUrl?: string | null;
-  };
-};
-export type PricingResponse = {
-  tiers: Array<{
-    tier: 'free' | 'pro';
-    displayName: string;
-    description: string;
-    priceMonthly: number | null;
-    priceYearly: number | null;
-    currency: string;
-    limits: {
-      dailyLimit: number | null;
-    };
-    paymentInfo?: {
-      revenueCatEntitlementId: string;
-      revenueCatOfferingId: string;
-    };
-  }>;
-};
+        ['contracts', {
+                exports: { '.': './src/index.ts' },
+                dependencies: CONTRACTS_DEPENDENCIES.dependencies,
+            }, `import { z } from 'zod';
+
+export const ClientPlatformSchema = z.enum(['frontend', 'extension']);
+export type ClientPlatform = z.infer<typeof ClientPlatformSchema>;
+
+export const ApiErrorSchema = z.object({
+  error: z.string(),
+  message: z.string(),
+});
+export type ApiError = z.infer<typeof ApiErrorSchema>;
+
+export const AuthMeResponseSchema = z.object({
+  user: z.object({
+    id: z.string(),
+    email: z.string().email(),
+    firstName: z.string().nullable().optional(),
+    lastName: z.string().nullable().optional(),
+    displayName: z.string(),
+    imageUrl: z.string().url().nullable().optional(),
+  }),
+});
+export type AuthMeResponse = z.infer<typeof AuthMeResponseSchema>;
+
+export const PricingResponseSchema = z.object({
+  tiers: z.array(z.object({
+    tier: z.enum(['free', 'pro']),
+    displayName: z.string(),
+    description: z.string(),
+    priceMonthly: z.number().nullable(),
+    priceYearly: z.number().nullable(),
+    currency: z.string(),
+    limits: z.object({
+      dailyLimit: z.number().nullable(),
+    }),
+    paymentInfo: z.object({
+      revenueCatEntitlementId: z.string(),
+      revenueCatOfferingId: z.string(),
+    }).optional(),
+  })),
+});
+export type PricingResponse = z.infer<typeof PricingResponseSchema>;
+
+export const SubscriptionEntitlementsSchema = z.object({
+  pro: z.boolean(),
+  inTrial: z.boolean(),
+  trialEndsAt: z.string().optional(),
+  expiresAt: z.string().optional(),
+  periodStart: z.string().optional(),
+  periodEnd: z.string().optional(),
+  method: z.enum(['trialing', 'redeemed', 'paid']).nullable().optional(),
+  managementUrl: z.string().url().optional(),
+  cancelAtPeriodEnd: z.boolean().optional(),
+});
+export type SubscriptionEntitlements = z.infer<typeof SubscriptionEntitlementsSchema>;
+
+export const SignOutResponseSchema = z.object({
+  success: z.boolean(),
+});
+export type SignOutResponse = z.infer<typeof SignOutResponseSchema>;
+
+export const CreateUploadRequestSchema = z.object({
+  fileName: z.string().min(1).max(200).optional(),
+  contentType: z.string().min(1).max(200),
+});
+export type CreateUploadRequest = z.infer<typeof CreateUploadRequestSchema>;
+
+export const CreateUploadResponseSchema = z.object({
+  objectKey: z.string(),
+  uploadUrl: z.string().url(),
+  expiresIn: z.number(),
+  headers: z.record(z.string(), z.string()),
+});
+export type CreateUploadResponse = z.infer<typeof CreateUploadResponseSchema>;
+
+export const StorageFileResponseSchema = z.object({
+  objectKey: z.string(),
+  downloadUrl: z.string().url(),
+  expiresIn: z.number(),
+});
+export type StorageFileResponse = z.infer<typeof StorageFileResponseSchema>;
+`],
+        ['types', {
+                exports: { '.': './src/index.ts' },
+                dependencies: { '@shared/contracts': 'workspace:*' },
+            }, `export type ApiEnvelope<T> = { data: T } | { error: string; message: string };
+export type {
+  AuthMeResponse,
+  ClientPlatform,
+  CreateUploadRequest,
+  CreateUploadResponse,
+  PricingResponse,
+  SignOutResponse,
+  StorageFileResponse,
+  SubscriptionEntitlements,
+} from '@shared/contracts';
 `],
         ['config', { exports: { '.': './src/index.ts' } }, `export const DEFAULT_API_PATH_PREFIX = '/api';
 export const DEFAULT_LOCAL_API_URL = 'http://localhost:8787';
@@ -835,8 +899,24 @@ export function joinApiUrl(baseUrl: string, path: string) {
         ['api-client', {
                 exports: { '.': './src/index.ts' },
                 dependencies: API_CLIENT_DEPENDENCIES.dependencies,
-            }, `import { joinApiUrl } from '@anhedral/config';
-import type { AuthMeResponse, ClientPlatform, PricingResponse, SubscriptionEntitlements } from '@anhedral/types';
+            }, `import type { ZodType } from 'zod';
+import { joinApiUrl } from '@shared/config';
+import {
+  AuthMeResponseSchema,
+  CreateUploadResponseSchema,
+  PricingResponseSchema,
+  SignOutResponseSchema,
+  StorageFileResponseSchema,
+  SubscriptionEntitlementsSchema,
+  type AuthMeResponse,
+  type ClientPlatform,
+  type CreateUploadRequest,
+  type CreateUploadResponse,
+  type PricingResponse,
+  type SignOutResponse,
+  type StorageFileResponse,
+  type SubscriptionEntitlements,
+} from '@shared/contracts';
 
 export class APIRequestError extends Error {
   constructor(
@@ -858,10 +938,12 @@ export type ApiClientOptions = {
 export class ApiClient {
   constructor(private readonly options: ApiClientOptions) {}
 
-  async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+  async request<T>(path: string, init: RequestInit = {}, schema?: ZodType<T>): Promise<T> {
     const token = await this.options.getToken?.();
     const headers = new Headers(init.headers);
-    headers.set('Content-Type', headers.get('Content-Type') ?? 'application/json');
+    if (init.body != null) {
+      headers.set('Content-Type', headers.get('Content-Type') ?? 'application/json');
+    }
     headers.set('X-Platform', this.options.platform);
     if (token) headers.set('Authorization', \`Bearer \${token}\`);
 
@@ -881,15 +963,16 @@ export class ApiClient {
     }
 
     if (response.status === 204) return {} as T;
-    return response.json() as Promise<T>;
+    const data = await response.json();
+    return schema ? schema.parse(data) : data as T;
   }
 
   getMe() {
-    return this.request<AuthMeResponse>('/auth/me');
+    return this.request<AuthMeResponse>('/auth/me', {}, AuthMeResponseSchema);
   }
 
   getPricing() {
-    return this.request<PricingResponse>('/subscriptions/pricing');
+    return this.request<PricingResponse>('/subscriptions/pricing', {}, PricingResponseSchema);
   }
 
   getSubscriptionPricing() {
@@ -899,13 +982,15 @@ export class ApiClient {
   getSubscriptionEntitlements(options?: { refresh?: boolean }) {
     return this.request<SubscriptionEntitlements>(
       options?.refresh ? '/subscriptions/entitlements/me?refresh=true' : '/subscriptions/entitlements/me',
+      {},
+      SubscriptionEntitlementsSchema,
     );
   }
 
   signOut() {
-    return this.request<{ success: boolean }>('/auth/signout', {
+    return this.request<SignOutResponse>('/auth/signout', {
       method: 'POST',
-    });
+    }, SignOutResponseSchema);
   }
 
   deleteAccount() {
@@ -913,13 +998,34 @@ export class ApiClient {
       method: 'DELETE',
     });
   }
+
+  createUpload(input: CreateUploadRequest) {
+    return this.request<CreateUploadResponse>('/storage/uploads', {
+      method: 'POST',
+      body: JSON.stringify(input),
+    }, CreateUploadResponseSchema);
+  }
+
+  getStorageFile(objectKey: string) {
+    return this.request<StorageFileResponse>(
+      \`/storage/files/\${encodeURIComponent(objectKey)}\`,
+      {},
+      StorageFileResponseSchema,
+    );
+  }
+
+  deleteStorageFile(objectKey: string) {
+    return this.request<void>(\`/storage/files/\${encodeURIComponent(objectKey)}\`, {
+      method: 'DELETE',
+    });
+  }
 }
 `],
     ];
     for (const [name, packageFields, source] of simplePackages) {
         const packageRoot = path.join(root, `packages/${name}`);
         writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({
-            name: `@anhedral/${name}`,
+            name: `@shared/${name}`,
             version: '0.1.0',
             private: true,
             type: 'module',
@@ -1068,8 +1174,10 @@ function writeFullstackRootFiles(root, options) {
         'verify:frontend': 'pnpm --filter ./Frontend exec expo install --check && pnpm --filter ./Frontend build:web',
         'verify:backend': 'pnpm --filter ./Backend test && pnpm --filter ./Backend build',
         'verify:extension': 'pnpm --filter ./Extension typecheck && pnpm --filter ./Extension zip',
-        'db:generate': 'pnpm --filter @anhedral/db db:generate',
-        'db:migrate': 'pnpm --filter @anhedral/db db:migrate',
+        'db:generate': 'pnpm --filter @shared/db db:generate',
+        'db:migrate': 'pnpm --filter @shared/db db:migrate',
+        'db:studio': 'pnpm --filter @shared/db db:studio',
+        'db:check': 'pnpm --filter @shared/db db:check',
     };
     scripts['dev:frontend'] = 'pnpm --filter ./Frontend dev';
     scripts['dev:extension'] = 'pnpm --filter ./Extension dev';
@@ -1114,7 +1222,7 @@ async function scaffoldFullstack(root, options) {
     writeFullstackRootFiles(root, options);
     anhedralPrint.done('Root config written');
     anhedralPrint.section('Shared packages');
-    anhedralPrint.step('Writing @anhedral/db, types, config, api-client');
+    anhedralPrint.step('Writing @shared/db, types, config, api-client');
     writeSharedPackages(root);
     anhedralPrint.done('Shared packages written');
     const frontendUrl = 'http://localhost:8081';

package/dist/templates/backend.js

@@ -52,8 +52,9 @@ function writePackageJson(dir, projectName) {
             build: 'pnpm typecheck',
             typecheck: 'tsc --noEmit',
             'db:generate': 'drizzle-kit generate',
-            'db:migrate': 'pnpm --filter @anhedral/db db:migrate',
+            'db:migrate': 'pnpm --filter @shared/db db:migrate',
             'db:studio': 'drizzle-kit studio',
+            'db:check': 'drizzle-kit check',
             'db:push': 'drizzle-kit push',
             lint: 'eslint . --ext .js,.ts',
             test: 'vitest run',
@@ -273,12 +274,12 @@ export {};
 // Database
 // ═══════════════════════════════════════════════════════════════════════════
 function writeDbFiles(dir) {
-    writeFile(path.join(dir, 'src/db/index.ts'), `export { db } from '@anhedral/db';
-export type { Database } from '@anhedral/db';
+    writeFile(path.join(dir, 'src/db/index.ts'), `export { db } from '@shared/db';
+export type { Database } from '@shared/db';
 `);
-    writeFile(path.join(dir, 'src/db/schema.ts'), `export * from '@anhedral/db/schema';
+    writeFile(path.join(dir, 'src/db/schema.ts'), `export * from '@shared/db/schema';
 `);
-    writeFile(path.join(dir, 'src/db/migrate.ts'), `import '@anhedral/db/migrate';
+    writeFile(path.join(dir, 'src/db/migrate.ts'), `import '@shared/db/migrate';
 `);
 }
 // ═══════════════════════════════════════════════════════════════════════════
@@ -763,12 +764,11 @@ export function verifyRevenueCatWebhookAuthorization(authHeader: string | undefi
   return normalize(authHeader) === normalize(secret);
 }
 `);
-    writeFile(path.join(dir, 'src/lib/r2.ts'), `import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+    writeFile(path.join(dir, 'src/lib/r2.ts'), `import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
-type UploadAvatarInput = {
+type UploadObjectInput = {
   objectKey: string;
-  body: Buffer;
   contentType: string;
 };
 
@@ -808,29 +808,40 @@ export function isR2Configured() {
   return hasR2Config();
 }
 
-export async function uploadAvatarToR2(input: UploadAvatarInput) {
+export async function createSignedUploadUrl(input: UploadObjectInput, expiresIn = 60 * 10) {
   const client = getR2Client();
   const bucket = getBucket();
 
-  await client.send(new PutObjectCommand({
+  const uploadUrl = await getSignedUrl(client, new PutObjectCommand({
     Bucket: bucket,
     Key: input.objectKey,
-    Body: input.body,
     ContentType: input.contentType,
-  }));
+  }), { expiresIn });
 
   return {
     bucket,
     objectKey: input.objectKey,
+    uploadUrl,
+    expiresIn,
   };
 }
 
-export async function createSignedAvatarUrl(objectKey: string) {
+export async function createSignedDownloadUrl(objectKey: string, expiresIn = 60 * 10) {
   const client = getR2Client();
-  return getSignedUrl(client, new GetObjectCommand({
+  const downloadUrl = await getSignedUrl(client, new GetObjectCommand({
     Bucket: getBucket(),
     Key: objectKey,
-  }), { expiresIn: 60 * 10 });
+  }), { expiresIn });
+
+  return { objectKey, downloadUrl, expiresIn };
+}
+
+export async function deleteObjectFromR2(objectKey: string) {
+  const client = getR2Client();
+  await client.send(new DeleteObjectCommand({
+    Bucket: getBucket(),
+    Key: objectKey,
+  }));
 }
 `);
     writeFile(path.join(dir, 'src/services/SubscriptionService.ts'), `import type { FastifyInstance, FastifyRequest } from 'fastify';
@@ -1349,12 +1360,13 @@ export class CorsConfig {
 // Repositories
 // ═══════════════════════════════════════════════════════════════════════════
 function writeRepositories(dir) {
-    writeFile(path.join(dir, 'src/repositories/UserRepository.ts'), `import { eq } from 'drizzle-orm';
+    writeFile(path.join(dir, 'src/repositories/UserRepository.ts'), `import crypto from 'node:crypto';
+import { eq } from 'drizzle-orm';
 import type { Database } from '../db/index.js';
 import { users } from '../db/schema.js';
 import type { NewUsers, SubscriptionStatus, SubscriptionTier } from '../db/schema.js';
 import { LRUCache } from '../lib/lruCache.js';
-import { subscriptions } from '../db/schema.js';
+import { subscriptions, uploads } from '../db/schema.js';
 
 export type UserAuthData = {
   id: string;
@@ -1436,6 +1448,19 @@ export class UserRepository {
     authPluginCache.invalidate(\`auth:\${userId}\`);
   }
 
+  async createUploadRecord(
+    userId: string,
+    input: { objectKey: string; bucket: string; contentType: string | null },
+  ): Promise<void> {
+    await this.db.insert(uploads).values({
+      id: crypto.randomUUID(),
+      userId,
+      objectKey: input.objectKey,
+      bucket: input.bucket,
+      contentType: input.contentType,
+    });
+  }
+
   async deleteById(userId: string): Promise<void> {
     await this.db.delete(users).where(eq(users.id, userId));
     authPluginCache.invalidate(\`auth:\${userId}\`);
@@ -1815,12 +1840,100 @@ const subscriptionRoutes: FastifyPluginAsync = async (fastify: FastifyInstance)
 };
 
 export default subscriptionRoutes;
+`);
+    writeFile(path.join(dir, 'src/routes/storage.ts'), `import crypto from 'node:crypto';
+import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { CreateUploadRequestSchema } from '@shared/contracts';
+import { AuthError, ServerError, ValidationError } from '../errors/index.js';
+import { createAuthHook } from '../lib/routeHelpers.js';
+import { createSignedDownloadUrl, createSignedUploadUrl, deleteObjectFromR2, isR2Configured } from '../lib/r2.js';
+
+const SIGNED_URL_EXPIRES_IN = 60 * 10;
+
+function sanitizeFileName(fileName: string | undefined) {
+  const fallback = 'upload';
+  const cleaned = (fileName ?? fallback)
+    .normalize('NFKD')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 120);
+  return cleaned || fallback;
+}
+
+function objectKeyForUser(userId: string, fileName: string | undefined) {
+  const safeUserId = userId.replace(/[^a-zA-Z0-9_-]+/g, '_');
+  return \`\${safeUserId}--\${crypto.randomUUID()}--\${sanitizeFileName(fileName)}\`;
+}
+
+function assertUserOwnsObject(userId: string, objectKey: string) {
+  const safeUserId = userId.replace(/[^a-zA-Z0-9_-]+/g, '_');
+  if (!objectKey.startsWith(\`\${safeUserId}--\`)) {
+    throw AuthError.forbidden();
+  }
+}
+
+const storageRoutes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
+  fastify.post('/uploads', {
+    preHandler: createAuthHook(fastify),
+  }, async (req, reply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    if (!isR2Configured()) throw ServerError.missingConfiguration('R2');
+
+    const parsed = CreateUploadRequestSchema.safeParse(req.body);
+    if (!parsed.success) throw ValidationError.invalidFormat('body', 'CreateUploadRequest');
+    const input = parsed.data;
+    const objectKey = objectKeyForUser(req.user.id, input.fileName);
+    const signed = await createSignedUploadUrl({
+      objectKey,
+      contentType: input.contentType,
+    }, SIGNED_URL_EXPIRES_IN);
+
+    await fastify.repos.users.createUploadRecord(req.user.id, {
+      objectKey,
+      bucket: signed.bucket,
+      contentType: input.contentType,
+    });
+
+    return reply.send({
+      objectKey,
+      uploadUrl: signed.uploadUrl,
+      expiresIn: signed.expiresIn,
+      headers: { 'Content-Type': input.contentType },
+    });
+  });
+
+  fastify.get<{ Params: { key: string } }>('/files/:key', {
+    preHandler: createAuthHook(fastify),
+  }, async (req, reply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    if (!isR2Configured()) throw ServerError.missingConfiguration('R2');
+
+    const objectKey = decodeURIComponent(req.params.key);
+    assertUserOwnsObject(req.user.id, objectKey);
+    return reply.send(await createSignedDownloadUrl(objectKey, SIGNED_URL_EXPIRES_IN));
+  });
+
+  fastify.delete<{ Params: { key: string } }>('/files/:key', {
+    preHandler: createAuthHook(fastify),
+  }, async (req, reply) => {
+    if (!req.user?.id) throw AuthError.unauthorized();
+    if (!isR2Configured()) throw ServerError.missingConfiguration('R2');
+
+    const objectKey = decodeURIComponent(req.params.key);
+    assertUserOwnsObject(req.user.id, objectKey);
+    await deleteObjectFromR2(objectKey);
+    return reply.code(204).send();
+  });
+};
+
+export default storageRoutes;
 `);
     writeFile(path.join(dir, 'src/routes/index.ts'), `import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
 import clerkAuthPlugin from '../plugins/clerkAuth.js';
 import health from './health.js';
 import auth from './auth.js';
 import subscriptions from './subscriptions.js';
+import storage from './storage.js';
 import cors from '@fastify/cors';
 
 const routes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
@@ -1848,6 +1961,12 @@ const routes: FastifyPluginAsync = async (fastify: FastifyInstance) => {
     await app.register(cors, { origin: restrictedCorsOrigin, maxAge: 86_400, methods: ['GET', 'POST', 'OPTIONS'], allowedHeaders: ['Authorization', 'Content-Type', 'X-Platform', 'X-RevenueCat-Signature'] });
     await app.register(subscriptions);
   }, { prefix: '/subscriptions' });
+
+  await fastify.register(async (app) => {
+    await app.register(cors, { origin: restrictedCorsOrigin, maxAge: 86_400, methods: ['GET', 'POST', 'DELETE', 'OPTIONS'], allowedHeaders: ['Authorization', 'Content-Type', 'X-Platform'] });
+    await app.register(clerkAuthPlugin);
+    await app.register(storage);
+  }, { prefix: '/storage' });
 };
 
 export default routes;

package/dist/templates/extension.js

@@ -452,7 +452,7 @@ export { WEBSITE_URL };
 `);
 }
 function writeApiClient(dir) {
-    writeFile(path.join(dir, 'src/lib/api.ts'), `import { ApiClient } from '@anhedral/api-client';
+    writeFile(path.join(dir, 'src/lib/api.ts'), `import { ApiClient } from '@shared/api-client';
 
 export class APIClient {
   constructor(private getToken: () => Promise<string | null>) {}

package/dist/templates/frontend.js

@@ -61,7 +61,7 @@ function patchFrontendPackageJson(dir) {
     const packageJson = JSON.parse(fs.readFileSync(filePath, 'utf8'));
     packageJson.dependencies = {
         ...(packageJson.dependencies ?? {}),
-        '@anhedral/api-client': FRONTEND_ADDON_DEPENDENCIES['@anhedral/api-client'],
+        '@shared/api-client': FRONTEND_ADDON_DEPENDENCIES['@shared/api-client'],
         '@clerk/expo': FRONTEND_ADDON_DEPENDENCIES['@clerk/expo'],
         'react-native-purchases': FRONTEND_ADDON_DEPENDENCIES['react-native-purchases'],
         'react-native-purchases-ui': FRONTEND_ADDON_DEPENDENCIES['react-native-purchases-ui'],
@@ -113,7 +113,7 @@ function patchExpoAppConfig(dir) {
     writeFile(filePath, JSON.stringify(appJson, null, 2) + '\n');
 }
 function writeApiClient(dir) {
-    writeFile(path.join(dir, 'api/client.ts'), `import { ApiClient, APIRequestError } from '@anhedral/api-client';
+    writeFile(path.join(dir, 'api/client.ts'), `import { ApiClient, APIRequestError } from '@shared/api-client';
 
 export class APIClient extends ApiClient {
   constructor(baseUrl: string, getToken: () => Promise<string | null>) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anhedral",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Opinionated init CLI for Expo, Fastify, WXT, shared packages, Neon, Drizzle, Clerk, RevenueCat, Stripe, R2, and Vercel.",
   "type": "module",
   "bin": {