@codaijs/keel 0.1.0

package/sails/rate-limiting/install.ts

@@ -0,0 +1,300 @@
+/**
+ * API Rate Limiting Sail Installer
+ *
+ * Adds in-memory sliding window rate limiting to your API routes.
+ * No external dependencies required.
+ *
+ * Usage:
+ *   npx tsx sails/rate-limiting/install.ts
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { input, confirm, select } from "@inquirer/prompts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const SAIL_DIR = dirname(new URL(import.meta.url).pathname);
+const PROJECT_ROOT = resolve(SAIL_DIR, "../..");
+const BACKEND_ROOT = join(PROJECT_ROOT, "packages/backend");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface SailManifest {
+  name: string;
+  displayName: string;
+  version: string;
+  requiredEnvVars: { key: string; description: string }[];
+  dependencies: { backend: Record<string, string>; frontend: Record<string, string> };
+}
+
+function loadManifest(): SailManifest {
+  return JSON.parse(readFileSync(join(SAIL_DIR, "addon.json"), "utf-8"));
+}
+
+function insertAtMarker(filePath: string, marker: string, code: string): void {
+  if (!existsSync(filePath)) {
+    console.warn(`  Warning: File not found: ${filePath}`);
+    return;
+  }
+  let content = readFileSync(filePath, "utf-8");
+  if (!content.includes(marker)) {
+    console.warn(`  Warning: Marker "${marker}" not found in ${filePath}`);
+    return;
+  }
+  if (content.includes(code.trim())) {
+    console.log(`  Skipped (already present) -> ${filePath}`);
+    return;
+  }
+  content = content.replace(marker, `${marker}\n${code}`);
+  writeFileSync(filePath, content, "utf-8");
+  console.log(`  Modified -> ${filePath}`);
+}
+
+function copyFile(src: string, dest: string, label: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`  Copied -> ${label}`);
+}
+
+function appendToEnvFiles(entries: Record<string, string>, section: string): void {
+  for (const envFile of [".env.example", ".env"]) {
+    const envPath = join(PROJECT_ROOT, envFile);
+    if (!existsSync(envPath)) continue;
+    let content = readFileSync(envPath, "utf-8");
+    const lines: string[] = [];
+    for (const [key, val] of Object.entries(entries)) {
+      if (!content.includes(key)) lines.push(`${key}=${val}`);
+    }
+    if (lines.length > 0) {
+      content += `\n# ${section}\n${lines.join("\n")}\n`;
+      writeFileSync(envPath, content, "utf-8");
+      console.log(`  Updated ${envFile}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const manifest = loadManifest();
+
+  // -- Step 1: Welcome -------------------------------------------------------
+  console.log("\n------------------------------------------------------------");
+  console.log(`  API Rate Limiting Sail Installer (v${manifest.version})`);
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  This sail adds rate limiting to protect your API endpoints:");
+  console.log("    - In-memory sliding window algorithm (no Redis needed)");
+  console.log("    - Per-IP or per-user request tracking");
+  console.log("    - Preset limiters for auth, general API, and sensitive routes");
+  console.log("    - Automatic 429 Too Many Requests with Retry-After header");
+  console.log("    - Periodic cleanup of expired entries");
+  console.log();
+
+  const pkgPath = join(PROJECT_ROOT, "package.json");
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    console.log(`  Template version: ${pkg.version ?? "unknown"}`);
+    console.log();
+  }
+
+  // -- Step 2: Configure defaults -------------------------------------------
+  console.log("  Configure rate limit defaults:");
+  console.log("  (You can always adjust these later in your code or via env vars)");
+  console.log();
+
+  const windowInput = await input({
+    message: "Default rate limit window in minutes:",
+    default: "15",
+    validate: (value) => {
+      const n = Number(value);
+      if (isNaN(n) || n <= 0) return "Please enter a positive number.";
+      return true;
+    },
+  });
+  const windowMinutes = Number(windowInput);
+
+  const maxRequestsInput = await input({
+    message: "Default max requests per window:",
+    default: "100",
+    validate: (value) => {
+      const n = Number(value);
+      if (isNaN(n) || n <= 0) return "Please enter a positive number.";
+      return true;
+    },
+  });
+  const maxRequests = Number(maxRequestsInput);
+
+  // -- Step 3: Choose protection scope --------------------------------------
+  console.log();
+
+  const scope = await select({
+    message: "Which routes should be rate limited?",
+    choices: [
+      {
+        name: "All API routes (recommended)",
+        value: "all",
+        description: "Apply apiLimiter globally + authLimiter on auth routes",
+      },
+      {
+        name: "Auth routes only",
+        value: "auth-only",
+        description: "Only protect login, signup, and password reset endpoints",
+      },
+      {
+        name: "Custom (I will configure manually)",
+        value: "custom",
+        description: "Copy the middleware files; you wire them up yourself",
+      },
+    ],
+  });
+
+  // -- Step 4: Summary ------------------------------------------------------
+  console.log();
+  console.log("  Summary of changes:");
+  console.log("  -------------------");
+  console.log("  Files to create:");
+  console.log("    + packages/backend/src/middleware/rate-limit.ts");
+  console.log("    + packages/backend/src/middleware/rate-limit-store.ts");
+  console.log();
+  console.log("  Files to modify:");
+
+  if (scope !== "custom") {
+    console.log("    ~ packages/backend/src/index.ts  (import + apply middleware)");
+  }
+
+  if (windowMinutes !== 15 || maxRequests !== 100) {
+    console.log("    ~ packages/backend/src/env.ts    (add optional env vars)");
+    console.log("    ~ .env.example / .env");
+  }
+
+  console.log();
+  console.log("  Configuration:");
+  console.log(`    Window:        ${windowMinutes} minutes`);
+  console.log(`    Max requests:  ${maxRequests} per window`);
+  console.log(`    Scope:         ${scope === "all" ? "All API routes" : scope === "auth-only" ? "Auth routes only" : "Manual"}`);
+  console.log();
+
+  // -- Step 5: Confirm ------------------------------------------------------
+  const proceed = await confirm({ message: "Proceed with installation?", default: true });
+  if (!proceed) {
+    console.log("\n  Installation cancelled.\n");
+    process.exit(0);
+  }
+
+  // -- Step 6: Execute -------------------------------------------------------
+  console.log();
+  console.log("  Installing...");
+  console.log();
+
+  console.log("  Copying backend files...");
+  copyFile(
+    join(SAIL_DIR, "files/backend/middleware/rate-limit-store.ts"),
+    join(BACKEND_ROOT, "src/middleware/rate-limit-store.ts"),
+    "src/middleware/rate-limit-store.ts",
+  );
+  copyFile(
+    join(SAIL_DIR, "files/backend/middleware/rate-limit.ts"),
+    join(BACKEND_ROOT, "src/middleware/rate-limit.ts"),
+    "src/middleware/rate-limit.ts",
+  );
+
+  console.log();
+  console.log("  Modifying backend files...");
+
+  // Insert imports and route middleware based on scope
+  if (scope === "all") {
+    insertAtMarker(
+      join(BACKEND_ROOT, "src/index.ts"),
+      "// [SAIL_IMPORTS]",
+      'import { apiLimiter, authLimiter } from "./middleware/rate-limit.js";',
+    );
+    insertAtMarker(
+      join(BACKEND_ROOT, "src/index.ts"),
+      "// [SAIL_ROUTES]",
+      '// Rate limiting\napp.use("/api/auth", authLimiter);\napp.use("/api", apiLimiter);',
+    );
+  } else if (scope === "auth-only") {
+    insertAtMarker(
+      join(BACKEND_ROOT, "src/index.ts"),
+      "// [SAIL_IMPORTS]",
+      'import { authLimiter } from "./middleware/rate-limit.js";',
+    );
+    insertAtMarker(
+      join(BACKEND_ROOT, "src/index.ts"),
+      "// [SAIL_ROUTES]",
+      '// Rate limiting (auth routes)\napp.use("/api/auth", authLimiter);',
+    );
+  }
+  // scope === "custom": no marker insertions
+
+  // Add optional env vars if defaults were customised
+  if (windowMinutes !== 15 || maxRequests !== 100) {
+    insertAtMarker(
+      join(BACKEND_ROOT, "src/env.ts"),
+      "// [SAIL_ENV_VARS]",
+      `  RATE_LIMIT_WINDOW_MS: z.coerce.number().default(${windowMinutes * 60 * 1000}),\n  RATE_LIMIT_MAX_REQUESTS: z.coerce.number().default(${maxRequests}),`,
+    );
+
+    console.log();
+    console.log("  Updating environment files...");
+    appendToEnvFiles(
+      {
+        RATE_LIMIT_WINDOW_MS: String(windowMinutes * 60 * 1000),
+        RATE_LIMIT_MAX_REQUESTS: String(maxRequests),
+      },
+      "Rate Limiting",
+    );
+  }
+
+  // -- Step 7: Next steps ----------------------------------------------------
+  console.log();
+  console.log("------------------------------------------------------------");
+  console.log("  API Rate Limiting installed successfully!");
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  Next steps:");
+  console.log();
+  console.log("  1. Start your dev server:");
+  console.log("       npm run dev");
+  console.log();
+  console.log("  2. Test rate limiting:");
+  console.log("       Make rapid requests to an API endpoint and verify");
+  console.log("       you get a 429 response after the limit is exceeded.");
+  console.log();
+  console.log("  Customising per-route limits:");
+  console.log();
+  console.log('    import { createRateLimiter } from "./middleware/rate-limit.js";');
+  console.log();
+  console.log("    const uploadLimiter = createRateLimiter({");
+  console.log("      windowMs: 60 * 60 * 1000,  // 1 hour");
+  console.log("      maxRequests: 20,");
+  console.log("    });");
+  console.log('    app.use("/api/uploads", uploadLimiter);');
+  console.log();
+  console.log("  Swapping to Redis (distributed deployments):");
+  console.log();
+  console.log("    Implement the RateLimitStore interface from");
+  console.log("    rate-limit-store.ts and pass it as the `store` option:");
+  console.log();
+  console.log("    createRateLimiter({ store: new RedisStore(redisClient) });");
+  console.log();
+}
+
+main().catch((err) => {
+  console.error("Installation failed:", err);
+  process.exit(1);
+});

package/sails/registry.json

@@ -0,0 +1,107 @@
+{
+  "version": "1.0.0",
+  "sails": [
+    {
+      "name": "google-oauth",
+      "displayName": "Google OAuth",
+      "description": "Google OAuth provider for BetterAuth — adds Google sign-in button",
+      "category": "auth",
+      "version": "1.0.0",
+      "routes": [],
+      "envVars": ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"],
+      "conflicts": []
+    },
+    {
+      "name": "stripe",
+      "displayName": "Stripe Payments",
+      "description": "Stripe subscriptions with checkout, webhooks, and customer portal",
+      "category": "payments",
+      "version": "1.0.0",
+      "routes": ["/api/stripe"],
+      "envVars": ["STRIPE_SECRET_KEY", "STRIPE_PUBLISHABLE_KEY", "STRIPE_WEBHOOK_SECRET"],
+      "conflicts": []
+    },
+    {
+      "name": "r2-storage",
+      "displayName": "Cloudflare R2 Storage",
+      "description": "File uploads via Cloudflare R2 with presigned URLs. Adds profile picture upload.",
+      "category": "storage",
+      "version": "1.0.0",
+      "routes": [],
+      "envVars": ["R2_ACCOUNT_ID", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_BUCKET_NAME", "R2_PUBLIC_URL"],
+      "conflicts": ["file-uploads"]
+    },
+    {
+      "name": "push-notifications",
+      "displayName": "Push Notifications",
+      "description": "Push notifications via Capacitor + Firebase Cloud Messaging with device token management and server-side sending",
+      "category": "mobile",
+      "version": "1.0.0",
+      "routes": ["/api/notifications"],
+      "envVars": ["FIREBASE_PROJECT_ID", "FIREBASE_PRIVATE_KEY", "FIREBASE_CLIENT_EMAIL"],
+      "conflicts": []
+    },
+    {
+      "name": "analytics",
+      "displayName": "PostHog Analytics",
+      "description": "Privacy-friendly analytics with PostHog — auto page views, user identification, and custom event tracking",
+      "category": "tracking",
+      "version": "1.0.0",
+      "routes": [],
+      "envVars": ["VITE_POSTHOG_KEY", "VITE_POSTHOG_HOST"],
+      "conflicts": []
+    },
+    {
+      "name": "admin-dashboard",
+      "displayName": "Admin Dashboard",
+      "description": "Admin dashboard for user management, metrics, and basic analytics",
+      "category": "admin",
+      "version": "1.0.0",
+      "routes": ["/api/admin"],
+      "envVars": ["ADMIN_EMAILS"],
+      "conflicts": []
+    },
+    {
+      "name": "i18n",
+      "displayName": "Internationalization",
+      "description": "Multi-language support with i18next, react-i18next, and language detection",
+      "category": "localization",
+      "version": "1.0.0",
+      "routes": [],
+      "envVars": [],
+      "conflicts": []
+    },
+    {
+      "name": "rate-limiting",
+      "displayName": "Rate Limiting",
+      "description": "API rate limiting middleware",
+      "category": "security",
+      "version": "1.0.0",
+      "status": "planned",
+      "routes": [],
+      "envVars": [],
+      "conflicts": []
+    },
+    {
+      "name": "file-uploads",
+      "displayName": "File Uploads",
+      "description": "Generic file upload system with R2/S3 storage",
+      "category": "storage",
+      "version": "1.0.0",
+      "status": "planned",
+      "routes": ["/api/files"],
+      "envVars": ["S3_ENDPOINT", "S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY", "S3_BUCKET_NAME", "S3_PUBLIC_URL", "S3_REGION"],
+      "conflicts": ["r2-storage"]
+    },
+    {
+      "name": "gdpr",
+      "displayName": "GDPR/DSGVO Compliance",
+      "description": "Full GDPR compliance: consent tracking, data export, account deletion (30-day grace period), privacy policy page",
+      "category": "compliance",
+      "version": "1.0.0",
+      "routes": ["/api/gdpr"],
+      "envVars": ["DELETION_CRON_SECRET"],
+      "conflicts": []
+    }
+  ]
+}

package/sails/stripe/README.md

@@ -0,0 +1,214 @@
+# Stripe Payments Sail
+
+Adds subscription management to your keel application using Stripe Checkout, webhooks, and the Customer Portal.
+
+## Features
+
+- Stripe Checkout for subscription payments
+- Webhook handling for subscription lifecycle events
+- Customer Portal for self-service subscription management
+- Pricing page with plan cards
+- Subscription status component for dashboards and settings
+- Drizzle ORM schema for customers and subscriptions
+
+## Prerequisites
+
+- A Stripe account (https://stripe.com)
+- Stripe CLI (for local webhook testing)
+
+## Installation
+
+```bash
+npx tsx sails/stripe/install.ts
+```
+
+The installer will prompt for your Stripe API keys and configure everything automatically.
+
+## Manual Setup: Stripe Dashboard
+
+### 1. Get API Keys
+
+1. Go to https://dashboard.stripe.com/test/apikeys
+2. Copy the **Publishable key** (pk_test_...)
+3. Copy the **Secret key** (sk_test_...)
+4. Add both to your `.env` file
+
+### 2. Create Products and Prices
+
+1. Go to https://dashboard.stripe.com/test/products
+2. Click **Add product**
+3. Create your subscription plans (e.g., "Pro" and "Enterprise")
+4. For each product, add a **Recurring price** (e.g., $19/month)
+5. Copy the Price IDs (price_...) and update `src/pages/Pricing.tsx`
+
+### 3. Set Up Webhooks
+
+#### Development (using Stripe CLI)
+
+```bash
+# Install Stripe CLI: https://stripe.com/docs/stripe-cli
+stripe login
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+```
+
+The CLI will output a webhook signing secret (whsec_...). Add it to your `.env` as `STRIPE_WEBHOOK_SECRET`.
+
+#### Production
+
+1. Go to https://dashboard.stripe.com/webhooks
+2. Click **Add endpoint**
+3. Set the URL to `https://yourdomain.com/api/stripe/webhook`
+4. Select events:
+   - `checkout.session.completed`
+   - `customer.subscription.updated`
+   - `customer.subscription.deleted`
+5. Click **Add endpoint**
+6. Copy the **Signing secret** and set it as `STRIPE_WEBHOOK_SECRET`
+
+### 4. Configure Customer Portal
+
+1. Go to https://dashboard.stripe.com/test/settings/billing/portal
+2. Enable the features you want (cancel, update payment method, etc.)
+3. Save changes
+
+### 5. Environment Variables
+
+```env
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## Architecture
+
+### Database Schema
+
+**stripe_customers**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | uuid | Primary key |
+| user_id | text | FK to users table |
+| stripe_customer_id | text | Stripe Customer ID |
+| created_at | timestamp | Creation time |
+| updated_at | timestamp | Last update time |
+
+**stripe_subscriptions**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | uuid | Primary key |
+| customer_id | uuid | FK to stripe_customers |
+| stripe_subscription_id | text | Stripe Subscription ID |
+| status | text | active, trialing, past_due, canceled, etc. |
+| stripe_price_id | text | The Stripe Price ID |
+| current_period_start | timestamp | Current billing period start |
+| current_period_end | timestamp | Current billing period end |
+| cancel_at_period_end | boolean | Whether sub cancels at period end |
+| created_at | timestamp | Creation time |
+| updated_at | timestamp | Last update time |
+
+### API Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /api/stripe/create-checkout-session | Yes | Create a Checkout session |
+| POST | /api/stripe/create-portal-session | Yes | Create a Customer Portal session |
+| POST | /api/stripe/webhook | No | Stripe webhook handler |
+| GET | /api/stripe/subscription | Yes | Get current subscription |
+
+### Webhook Flow
+
+1. Stripe fires an event (e.g., `checkout.session.completed`)
+2. Express receives the raw body at `/api/stripe/webhook`
+3. Signature is verified using `STRIPE_WEBHOOK_SECRET`
+4. The event handler updates the database accordingly
+5. Returns 200 to acknowledge receipt
+
+### Important: Raw Body Middleware
+
+The webhook endpoint requires the raw request body for signature verification. Make sure your Express app has this middleware **before** `express.json()`:
+
+```typescript
+app.use("/api/stripe/webhook", express.raw({ type: "application/json" }));
+```
+
+The installer adds this automatically.
+
+## Frontend Components
+
+### Pricing Page (`/pricing`)
+
+Displays plan cards with features and subscribe buttons. Redirects to Stripe Checkout when a plan is selected.
+
+### Checkout Page (`/checkout/success`, `/checkout/cancel`)
+
+Post-checkout landing pages for successful payments and cancellations.
+
+### SubscriptionStatus Component
+
+Drop-in component showing the current subscription status with a "Manage" button that opens the Stripe Customer Portal. Use it in settings or dashboard pages:
+
+```tsx
+import { SubscriptionStatus } from "@/components/stripe/SubscriptionStatus";
+
+function SettingsPage() {
+  return (
+    <div>
+      <h2>Subscription</h2>
+      <SubscriptionStatus />
+    </div>
+  );
+}
+```
+
+### useSubscription Hook
+
+```tsx
+import { useSubscription, isSubscriptionActive } from "@/hooks/useSubscription";
+
+function MyComponent() {
+  const { subscription, isLoading } = useSubscription();
+
+  if (isSubscriptionActive(subscription)) {
+    return <PremiumContent />;
+  }
+
+  return <UpgradePrompt />;
+}
+```
+
+## Testing
+
+### Test Cards
+
+Use Stripe's test card numbers:
+
+| Card | Number | Scenario |
+|------|--------|----------|
+| Visa | 4242 4242 4242 4242 | Successful payment |
+| Visa (declined) | 4000 0000 0000 0002 | Card declined |
+| Visa (3D Secure) | 4000 0025 0000 3155 | Requires authentication |
+
+Use any future expiry date, any 3-digit CVC, and any ZIP code.
+
+### Testing Webhooks Locally
+
+```bash
+# Terminal 1: Start your dev server
+npm run dev
+
+# Terminal 2: Forward Stripe events
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+
+# Terminal 3: Trigger test events
+stripe trigger checkout.session.completed
+stripe trigger customer.subscription.updated
+stripe trigger customer.subscription.deleted
+```
+
+## Going to Production
+
+1. Switch from test keys to live keys in your environment
+2. Create live products/prices and update Price IDs
+3. Set up the production webhook endpoint
+4. Configure the Customer Portal for live mode
+5. Test the full flow with a real card

package/sails/stripe/addon.json

@@ -0,0 +1,24 @@
+{
+  "name": "stripe",
+  "displayName": "Stripe Payments",
+  "description": "Adds Stripe subscription management with checkout, webhooks, and customer portal",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "STRIPE_SECRET_KEY", "description": "Stripe secret key (sk_test_... or sk_live_...)" },
+    { "key": "STRIPE_PUBLISHABLE_KEY", "description": "Stripe publishable key (pk_test_... or pk_live_...)" },
+    { "key": "STRIPE_WEBHOOK_SECRET", "description": "Stripe webhook signing secret (whsec_...)" }
+  ],
+  "dependencies": {
+    "backend": { "stripe": "^17.0.0" },
+    "frontend": { "@stripe/react-stripe-js": "^3.0.0", "@stripe/stripe-js": "^5.0.0" }
+  },
+  "modifies": {
+    "backend": ["src/index.ts", "src/db/schema/index.ts", "src/env.ts"],
+    "frontend": ["src/router.tsx"]
+  },
+  "adds": {
+    "backend": ["src/db/schema/stripe.ts", "src/routes/stripe.ts", "src/services/stripe.ts"],
+    "frontend": ["src/pages/Pricing.tsx", "src/pages/Checkout.tsx", "src/components/stripe/SubscriptionStatus.tsx", "src/hooks/useSubscription.ts"]
+  }
+}