@donotdev/functions 0.0.10 → 0.0.11

package/src/supabase/baseFunction.ts

@@ -0,0 +1,302 @@
+// packages/functions/src/supabase/baseFunction.ts
+
+/**
+ * @fileoverview Base Supabase Edge Function handler
+ * @description Handles auth verification, request validation, and error responses
+ * for Supabase Edge Functions. Mirrors the Firebase/Vercel base function pattern.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import * as v from 'valibot';
+
+import { hasRoleAccess } from '@donotdev/core/server';
+import type { UserRole, SecurityContext } from '@donotdev/core/server';
+import type { SupabaseClient } from '@supabase/supabase-js';
+
+import {
+  checkRateLimitWithPostgres,
+  DEFAULT_RATE_LIMITS,
+} from './utils/rateLimiter.js';
+import type { RateLimitConfig } from './utils/rateLimiter.js';
+import { recordOperationMetrics } from './utils/monitoring.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Context passed to Supabase Edge Function business logic
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export interface SupabaseHandlerContext {
+  /** Authenticated user ID (from JWT verification) */
+  uid: string;
+  /** User role extracted from app_metadata.role */
+  userRole: UserRole;
+  /** Supabase admin client (service role — full access) */
+  supabaseAdmin: SupabaseClient;
+}
+
+// =============================================================================
+// Base Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler with built-in auth, validation, role checking, and error handling.
+ *
+ * @param operationName - Operation name for logging
+ * @param schema - Valibot schema for request body validation
+ * @param handler - Business logic function
+ * @param requiredRole - Minimum role required (default: 'user')
+ * @returns A `(req: Request) => Promise<Response>` handler for Deno.serve
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { createSupabaseHandler } from '@donotdev/functions/supabase';
+ *
+ * const schema = v.object({ userId: v.string() });
+ *
+ * export default createSupabaseHandler('delete-account', schema, async (data, ctx) => {
+ *   await ctx.supabaseAdmin.auth.admin.deleteUser(data.userId);
+ *   return { success: true };
+ * }, 'admin');
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createSupabaseHandler<TReq, TRes>(
+  operationName: string,
+  schema: v.BaseSchema<unknown, TReq, v.BaseIssue<unknown>>,
+  handler: (data: TReq, context: SupabaseHandlerContext) => Promise<TRes>,
+  requiredRole: UserRole = 'user',
+  security?: SecurityContext
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    try {
+      // CORS preflight
+      // C3: CORS origin is configurable via ALLOWED_ORIGIN env var.
+      // Default '*' is acceptable for pure-token-auth edge functions where credentials
+      // (cookies) are never used. Consumers that need credentialed requests must set
+      // ALLOWED_ORIGIN to their specific frontend origin.
+      //
+      // Architecture decision — CORS wildcard (`*`) as framework default:
+      // This is an intentional development-convenience default, not a security oversight.
+      // Consumer apps override it by setting the ALLOWED_ORIGIN environment variable
+      // (e.g. ALLOWED_ORIGIN=https://myapp.example) in their Supabase Edge Function config.
+      // The framework documents this in the deployment guide.
+      const allowedOrigin = getEnv('ALLOWED_ORIGIN', '*');
+      // Local wrapper so all responses in this closure carry the correct origin
+      const respond = (data: unknown, status: number) =>
+        jsonResponse(data, status, allowedOrigin);
+
+      if (req.method === 'OPTIONS') {
+        return new Response(null, {
+          status: 204,
+          headers: {
+            'Access-Control-Allow-Origin': allowedOrigin,
+            'Access-Control-Allow-Methods': 'POST, OPTIONS',
+            'Access-Control-Allow-Headers': 'authorization, content-type, x-client-info, apikey',
+          },
+        });
+      }
+
+      // Method check
+      if (req.method !== 'POST') {
+        return respond({ error: 'Method not allowed' }, 405);
+      }
+
+      // Extract and verify auth token
+      const authHeader = req.headers.get('authorization');
+      if (!authHeader?.startsWith('Bearer ')) {
+        return respond({ error: 'Missing or invalid authorization header' }, 401);
+      }
+      const token = authHeader.slice(7);
+
+      // Create admin client
+      const supabaseUrl = getEnvOrThrow('SUPABASE_URL');
+      const secretKey = getEnvOrThrow('SUPABASE_SECRET_KEY') || getEnvOrThrow('SUPABASE_SERVICE_ROLE_KEY'); // New: sb_secret_..., Legacy: service_role
+      const supabaseAdmin = createClient(supabaseUrl, secretKey, {
+        auth: { autoRefreshToken: false, persistSession: false },
+      });
+
+      // Verify JWT and extract user
+      const { data: { user }, error: authError } = await supabaseAdmin.auth.getUser(token);
+      if (authError || !user) {
+        return respond({ error: 'Invalid or expired token' }, 401);
+      }
+
+      // Extract user role from app_metadata (Supabase stores custom claims here)
+      const appMetadata = (user.app_metadata ?? {}) as Record<string, unknown>;
+      const userRole: UserRole = (appMetadata.role as UserRole) || 'user';
+
+      // Role-based access control
+      if (requiredRole === 'guest') {
+        // Guest access: no additional check needed
+      } else {
+        // Non-guest access: verify user has required role level
+        if (!hasRoleAccess(userRole, requiredRole)) {
+          return respond(
+            { error: `Access denied. Required role: ${requiredRole}, your role: ${userRole}` },
+            403
+          );
+        }
+      }
+
+      // Rate limiting (on by default, set DISABLE_RATE_LIMITING=true to opt out)
+      const disableRateLimiting = getEnv('DISABLE_RATE_LIMITING') === 'true';
+      if (!disableRateLimiting) {
+        // Use IP-based key for guest operations, UID-based for authenticated
+        const rateLimitIdentifier =
+          requiredRole === 'guest' && user.id === 'guest'
+            ? `ip_${getClientIp(req)}`
+            : `uid_${user.id}`;
+        const rateLimitKey = `${operationName}_${rateLimitIdentifier}`;
+        const rateLimitConfig: RateLimitConfig =
+          (DEFAULT_RATE_LIMITS as Record<string, RateLimitConfig>)[operationName] ||
+          DEFAULT_RATE_LIMITS.api;
+
+        const rateLimitResult = await checkRateLimitWithPostgres(
+          supabaseAdmin,
+          rateLimitKey,
+          rateLimitConfig
+        );
+
+        if (!rateLimitResult.allowed) {
+          security?.audit({
+            type: 'rate_limit.exceeded',
+            userId: user.id,
+            metadata: { operation: operationName, remaining: 0 },
+          });
+          return respond(
+            {
+              error: `Rate limit exceeded. Try again in ${rateLimitResult.blockRemainingSeconds} seconds.`,
+            },
+            429
+          );
+        }
+      }
+
+      // Parse and validate request body
+      const body = await req.json().catch(() => ({}));
+      const validationResult = v.safeParse(schema, body);
+      if (!validationResult.success) {
+        const issues = validationResult.issues.map((i) => i.message).join(', ');
+        return respond({ error: `Validation failed: ${issues}` }, 400);
+      }
+
+      // Record metrics (only if enabled via ENABLE_METRICS env var)
+      const enableMetrics = getEnv('ENABLE_METRICS') === 'true';
+      const startTime = enableMetrics ? Date.now() : 0;
+
+      // Execute business logic
+      let result: TRes;
+      let error: Error | null = null;
+      try {
+        result = await handler(validationResult.output, {
+          uid: user.id,
+          userRole,
+          supabaseAdmin,
+        });
+      } catch (handlerError) {
+        error = handlerError instanceof Error ? handlerError : new Error(String(handlerError));
+        throw handlerError;
+      } finally {
+        // Record metrics if enabled
+        if (enableMetrics) {
+          const durationMs = Date.now() - startTime;
+          await recordOperationMetrics(supabaseAdmin, {
+            operation: operationName,
+            userId: user.id,
+            status: error ? 'failed' : 'success',
+            durationMs,
+            metadata: {
+              requestId: req.headers.get('x-request-id') || undefined,
+            },
+            errorCode: error ? getErrorCode(error.message) : undefined,
+            errorMessage: error ? error.message : undefined,
+          });
+        }
+      }
+
+      return respond(result, 200);
+    } catch (error) {
+      console.error(`[${operationName}] Error:`, error);
+      const message = error instanceof Error ? error.message : 'Internal server error';
+      const status = getErrorStatus(message);
+      // allowedOrigin may not be set if error occurred before that line; fall back to '*'
+      const origin = getEnv('ALLOWED_ORIGIN', '*');
+      return jsonResponse({ error: message }, status, origin);
+    }
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function jsonResponse(data: unknown, status: number, allowedOrigin = '*'): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Control-Allow-Origin': allowedOrigin,
+    },
+  });
+}
+
+function getEnvOrThrow(key: string): string {
+  const value = (typeof Deno !== 'undefined' ? Deno.env.get(key) : process.env[key]) as string | undefined;
+  if (!value) throw new Error(`Missing environment variable: ${key}`);
+  return value;
+}
+
+function getEnv(key: string, defaultValue: string = ''): string {
+  return (typeof Deno !== 'undefined' ? Deno.env.get(key) : process.env[key]) as string | undefined || defaultValue;
+}
+
+function getClientIp(req: Request): string {
+  // Try X-Forwarded-For first (common for proxied requests)
+  const forwardedFor = req.headers.get('x-forwarded-for');
+  if (forwardedFor) {
+    // W19: Take the rightmost (last) IP — the leftmost entry is client-supplied
+    // and trivially spoofable. The last entry is appended by the nearest trusted
+    // reverse proxy and is the most reliable.
+    const ips = forwardedFor.split(',').map((ip) => ip.trim()).filter(Boolean);
+    const lastIp = ips[ips.length - 1];
+    if (lastIp) return lastIp;
+  }
+
+  // Fallback to CF-Connecting-IP (Cloudflare) or other headers
+  const cfIp = req.headers.get('cf-connecting-ip');
+  if (cfIp) return cfIp;
+
+  return 'unknown';
+}
+
+function getErrorCode(message: string): string {
+  if (message.includes('Rate limit')) return 'rate-limit-exceeded';
+  if (message.includes('not found') || message.includes('No active')) return 'not-found';
+  if (message.includes('permission') || message.includes('denied') || message.includes('Forbidden')) return 'permission-denied';
+  if (message.includes('mismatch') || message.includes('Invalid') || message.includes('Missing')) return 'invalid-argument';
+  if (message.includes('already-exists') || message.includes('Duplicate')) return 'already-exists';
+  return 'internal';
+}
+
+function getErrorStatus(message: string): number {
+  if (message.includes('Rate limit')) return 429;
+  if (message.includes('not found') || message.includes('No active')) return 404;
+  if (message.includes('permission') || message.includes('denied') || message.includes('Forbidden')) return 403;
+  if (message.includes('mismatch') || message.includes('Invalid') || message.includes('Missing')) return 400;
+  return 500;
+}
+
+// Deno global type declaration for env access
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;

package/src/supabase/billing/cancelSubscription.ts

@@ -0,0 +1,57 @@
+// packages/functions/src/supabase/billing/cancelSubscription.ts
+
+/**
+ * @fileoverview Cancel Subscription — Supabase Edge Function
+ * @description Wraps the shared `cancelUserSubscription` for Supabase.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { cancelUserSubscription } from '../../shared/billing/helpers/subscriptionManagement.js';
+import { initStripe } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import { createSupabaseAuthProvider } from '../helpers/authProvider.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const cancelSubscriptionSchema = v.object({
+  userId: v.pipe(v.string(), v.minLength(1, 'User ID is required')),
+});
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for subscription cancellation.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createCancelSubscription() {
+  return createSupabaseHandler(
+    'cancel-subscription',
+    cancelSubscriptionSchema,
+    async (data, ctx) => {
+      initStripe(getStripeKey());
+      const authProvider = createSupabaseAuthProvider(ctx.supabaseAdmin);
+      return cancelUserSubscription(data.userId, authProvider);
+    },
+  );
+}
+
+function getStripeKey(): string {
+  const key = (typeof Deno !== 'undefined' ? Deno.env.get('STRIPE_SECRET_KEY') : process.env.STRIPE_SECRET_KEY) as string | undefined;
+  if (!key) throw new Error('Missing STRIPE_SECRET_KEY environment variable');
+  return key;
+}
+
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;

package/src/supabase/billing/changePlan.ts

@@ -0,0 +1,62 @@
+// packages/functions/src/supabase/billing/changePlan.ts
+
+/**
+ * @fileoverview Change Plan — Supabase Edge Function
+ * @description Wraps the shared `changeUserPlan` for Supabase.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import type { StripeBackConfig } from '@donotdev/core/server';
+
+import { changeUserPlan } from '../../shared/billing/helpers/subscriptionManagement.js';
+import { initStripe } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import { createSupabaseAuthProvider } from '../helpers/authProvider.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const changePlanSchema = v.object({
+  userId: v.pipe(v.string(), v.minLength(1, 'User ID is required')),
+  newPriceId: v.pipe(v.string(), v.minLength(1, 'Price ID is required')),
+  billingConfigKey: v.pipe(v.string(), v.minLength(1, 'Billing config key is required')),
+});
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for plan changes.
+ *
+ * @param billingConfig - Billing configuration with product definitions
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createChangePlan(billingConfig: StripeBackConfig) {
+  return createSupabaseHandler(
+    'change-plan',
+    changePlanSchema,
+    async (data, ctx) => {
+      initStripe(getStripeKey());
+      const authProvider = createSupabaseAuthProvider(ctx.supabaseAdmin);
+      return changeUserPlan(data.userId, data.newPriceId, data.billingConfigKey, billingConfig, authProvider);
+    },
+  );
+}
+
+function getStripeKey(): string {
+  const key = (typeof Deno !== 'undefined' ? Deno.env.get('STRIPE_SECRET_KEY') : process.env.STRIPE_SECRET_KEY) as string | undefined;
+  if (!key) throw new Error('Missing STRIPE_SECRET_KEY environment variable');
+  return key;
+}
+
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;

package/src/supabase/billing/createCheckoutSession.ts

@@ -0,0 +1,82 @@
+// packages/functions/src/supabase/billing/createCheckoutSession.ts
+
+/**
+ * @fileoverview Create Checkout Session — Supabase Edge Function
+ * @description Wraps the shared `createCheckoutAlgorithm` for Supabase.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import type { StripeBackConfig } from '@donotdev/core/server';
+import { CreateCheckoutSessionRequestSchema } from '@donotdev/core/server';
+
+import { createCheckoutAlgorithm } from '../../shared/billing/createCheckout.js';
+import { initStripe, stripe, validateStripeEnvironment } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import { createSupabaseAuthProvider } from '../helpers/authProvider.js';
+
+import type { CreateCheckoutSessionRequest } from '@donotdev/core/server';
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for Stripe checkout session creation.
+ *
+ * @param billingConfig - Billing configuration with product definitions
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createCheckoutSession(billingConfig: StripeBackConfig) {
+  return createSupabaseHandler(
+    'create-checkout-session',
+    CreateCheckoutSessionRequestSchema,
+    async (data: CreateCheckoutSessionRequest, ctx) => {
+      initStripe(getStripeKey());
+      validateStripeEnvironment();
+
+      const authProvider = createSupabaseAuthProvider(ctx.supabaseAdmin);
+
+      const stripeProvider = {
+        async createCheckoutSession(params: {
+          priceId: string;
+          customerEmail?: string;
+          metadata: Record<string, string>;
+          allowPromotionCodes: boolean;
+          successUrl: string;
+          cancelUrl: string;
+          mode?: 'payment' | 'subscription';
+        }) {
+          const session = await stripe.checkout.sessions.create({
+            mode: params.mode || 'payment',
+            line_items: [{ price: params.priceId, quantity: 1 }],
+            customer_email: params.customerEmail || undefined,
+            success_url: params.successUrl,
+            cancel_url: params.cancelUrl,
+            allow_promotion_codes: params.allowPromotionCodes,
+            metadata: params.metadata,
+            ...(params.mode === 'subscription' && {
+              subscription_data: { metadata: params.metadata },
+            }),
+          });
+          return { id: session.id, url: session.url };
+        },
+      };
+
+      return createCheckoutAlgorithm(data, stripeProvider, authProvider, billingConfig);
+    },
+  );
+}
+
+function getStripeKey(): string {
+  const key = (typeof Deno !== 'undefined' ? Deno.env.get('STRIPE_SECRET_KEY') : process.env.STRIPE_SECRET_KEY) as string | undefined;
+  if (!key) throw new Error('Missing STRIPE_SECRET_KEY environment variable');
+  return key;
+}
+
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;

package/src/supabase/billing/createCustomerPortal.ts

@@ -0,0 +1,58 @@
+// packages/functions/src/supabase/billing/createCustomerPortal.ts
+
+/**
+ * @fileoverview Create Customer Portal — Supabase Edge Function
+ * @description Wraps the shared `createCustomerPortalSession` for Supabase.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createCustomerPortalSession } from '../../shared/billing/helpers/subscriptionManagement.js';
+import { initStripe } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import { createSupabaseAuthProvider } from '../helpers/authProvider.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const customerPortalSchema = v.object({
+  userId: v.pipe(v.string(), v.minLength(1, 'User ID is required')),
+  returnUrl: v.optional(v.pipe(v.string(), v.url())),
+});
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for Stripe Customer Portal.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createCustomerPortal() {
+  return createSupabaseHandler(
+    'create-customer-portal',
+    customerPortalSchema,
+    async (data, ctx) => {
+      initStripe(getStripeKey());
+      const authProvider = createSupabaseAuthProvider(ctx.supabaseAdmin);
+      return createCustomerPortalSession(data.userId, authProvider, data.returnUrl);
+    },
+  );
+}
+
+function getStripeKey(): string {
+  const key = (typeof Deno !== 'undefined' ? Deno.env.get('STRIPE_SECRET_KEY') : process.env.STRIPE_SECRET_KEY) as string | undefined;
+  if (!key) throw new Error('Missing STRIPE_SECRET_KEY environment variable');
+  return key;
+}
+
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;

package/src/supabase/billing/refreshSubscriptionStatus.ts

@@ -0,0 +1,89 @@
+// packages/functions/src/supabase/billing/refreshSubscriptionStatus.ts
+
+/**
+ * @fileoverview Refresh Subscription Status — Supabase Edge Function
+ * @description Direct Stripe lookup + claim update via Supabase Admin.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import Stripe from 'stripe';
+import * as v from 'valibot';
+
+import { initStripe, stripe, validateStripeEnvironment } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import { createSupabaseAuthProvider } from '../helpers/authProvider.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const refreshSubscriptionSchema = v.object({
+  userId: v.pipe(v.string(), v.minLength(1, 'User ID is required')),
+});
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for refreshing subscription status.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createRefreshSubscriptionStatus() {
+  return createSupabaseHandler(
+    'refresh-subscription-status',
+    refreshSubscriptionSchema,
+    async (data, ctx) => {
+      initStripe(getStripeKey());
+      validateStripeEnvironment();
+
+      const authProvider = createSupabaseAuthProvider(ctx.supabaseAdmin);
+      const user = await authProvider.getUser(data.userId);
+      const currentClaims = user.customClaims || {};
+
+      const subscriptionId = (currentClaims.subscription as { subscriptionId?: string } | undefined)?.subscriptionId;
+      if (!subscriptionId) {
+        throw new Error('No active subscription found');
+      }
+
+      const subscription = await stripe.subscriptions.retrieve(subscriptionId) as Stripe.Subscription;
+
+      // Update claims via auth provider
+      const updatedClaims = {
+        ...currentClaims,
+        subscription: {
+          ...(currentClaims.subscription as Record<string, unknown>),
+          status: subscription.status,
+          currentPeriodStart: new Date((subscription as any).current_period_start * 1000).toISOString(),
+          currentPeriodEnd: new Date((subscription as any).current_period_end * 1000).toISOString(),
+          cancelAtPeriodEnd: (subscription as any).cancel_at_period_end,
+        },
+      };
+
+      await authProvider.setCustomUserClaims(data.userId, updatedClaims);
+
+      return {
+        success: true,
+        userId: data.userId,
+        status: subscription.status,
+        currentPeriodEnd: new Date((subscription as any).current_period_end * 1000).toISOString(),
+        cancelAtPeriodEnd: (subscription as any).cancel_at_period_end,
+      };
+    },
+  );
+}
+
+function getStripeKey(): string {
+  const key = (typeof Deno !== 'undefined' ? Deno.env.get('STRIPE_SECRET_KEY') : process.env.STRIPE_SECRET_KEY) as string | undefined;
+  if (!key) throw new Error('Missing STRIPE_SECRET_KEY environment variable');
+  return key;
+}
+
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;