@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-architecture-variants/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Over-engineering | Wrong variant choice | Start simpler |
+| Performance issues | Wrong layer | Add caching/async |
+| Team friction | Complex architecture | Simplify or train |
+| Deployment complexity | Microservice overhead | Consider service layer |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-architecture-variants/references/examples.md

@@ -0,0 +1,12 @@
+## Examples
+
+### Quick Variant Check
+
+```bash
+# Count team size and DAU to select variant
+echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
+echo "DAU: Check analytics dashboard"
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-architecture-variants/references/serverless-and-multi-tenant.md

@@ -0,0 +1,251 @@
+## Serverless (Edge Functions) and Multi-Tenant Patterns
+
+### Edge Functions with Per-Request Clients
+
+Edge Functions create a new Supabase client per request, extracting the user's JWT from the Authorization header. This ensures proper RLS scoping.
+
+```typescript
+// supabase/functions/api/index.ts
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  // Per-request client with the user's JWT for RLS
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,
+    {
+      global: {
+        headers: { Authorization: req.headers.get('Authorization')! },
+      },
+    }
+  )
+
+  // This client respects RLS using the user's JWT
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 })
+  }
+
+  // Queries are scoped to the authenticated user via RLS
+  const { data, error } = await supabase
+    .from('todos')
+    .select('id, title, is_complete')
+    .order('created_at', { ascending: false })
+
+  if (error) {
+    return new Response(JSON.stringify({ error: error.message }), { status: 500 })
+  }
+
+  return new Response(JSON.stringify(data), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+### Edge Function with Admin Operations
+
+```typescript
+// supabase/functions/admin-task/index.ts
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  // Verify the request has a valid admin JWT first
+  const userClient = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,
+    { global: { headers: { Authorization: req.headers.get('Authorization')! } } }
+  )
+
+  const { data: { user } } = await userClient.auth.getUser()
+  if (!user) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  // Check if user is admin
+  const { data: profile } = await userClient
+    .from('profiles')
+    .select('role')
+    .eq('id', user.id)
+    .single()
+
+  if (profile?.role !== 'admin') {
+    return new Response('Forbidden', { status: 403 })
+  }
+
+  // Now use service_role for admin operations
+  const adminClient = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+
+  // Admin operation: get all users
+  const { data, error } = await adminClient.auth.admin.listUsers()
+  if (error) {
+    return new Response(JSON.stringify({ error: error.message }), { status: 500 })
+  }
+
+  return new Response(JSON.stringify({ users: data.users.length }))
+})
+```
+
+### Multi-Tenant: RLS-Based Isolation (Recommended)
+
+The simplest multi-tenant approach uses a single database with RLS policies scoping all queries to the tenant.
+
+```sql
+-- Schema for RLS-based multi-tenancy
+CREATE TABLE public.tenants (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  name text NOT NULL,
+  slug text UNIQUE NOT NULL,
+  plan text DEFAULT 'free',
+  created_at timestamptz DEFAULT now()
+);
+
+CREATE TABLE public.tenant_members (
+  tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE,
+  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE,
+  role text NOT NULL DEFAULT 'member' CHECK (role IN ('owner', 'admin', 'member')),
+  PRIMARY KEY (tenant_id, user_id)
+);
+
+-- Store current tenant in user's JWT claims (set via custom claims hook)
+-- Or look up from tenant_members table
+
+CREATE TABLE public.projects (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id),
+  name text NOT NULL,
+  created_at timestamptz DEFAULT now()
+);
+
+ALTER TABLE public.projects ENABLE ROW LEVEL SECURITY;
+
+-- RLS: users can only see projects belonging to their tenant
+CREATE POLICY "tenant_isolation" ON public.projects
+  FOR ALL USING (
+    tenant_id IN (
+      SELECT tenant_id FROM public.tenant_members
+      WHERE user_id = auth.uid()
+    )
+  );
+
+CREATE INDEX idx_projects_tenant_id ON public.projects(tenant_id);
+CREATE INDEX idx_tenant_members_user_id ON public.tenant_members(user_id);
+```
+
+```typescript
+// lib/supabase-tenant.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
+
+const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+)
+
+// All queries are automatically scoped to the user's tenant via RLS
+export async function getTenantProjects() {
+  const { data, error } = await supabase
+    .from('projects')
+    .select('id, name, created_at, tenant_id')
+    .order('created_at', { ascending: false })
+
+  if (error) throw new Error(`Failed to load projects: ${error.message}`)
+  return data  // Only returns projects for the authenticated user's tenant(s)
+}
+
+// Switch active tenant (for users in multiple tenants)
+export async function getUserTenants() {
+  const { data, error } = await supabase
+    .from('tenant_members')
+    .select(`
+      role,
+      tenants:tenant_id (id, name, slug, plan)
+    `)
+
+  if (error) throw new Error(`Failed to load tenants: ${error.message}`)
+  return data
+}
+
+// Create project in a specific tenant
+export async function createProject(tenantId: string, name: string) {
+  const { data, error } = await supabase
+    .from('projects')
+    .insert({ tenant_id: tenantId, name })
+    .select('id, name, tenant_id, created_at')
+    .single()
+
+  if (error) throw new Error(`Failed to create project: ${error.message}`)
+  return data
+}
+```
+
+## Output
+
+- Next.js SSR setup with server client (cookies-based auth), browser client, and middleware
+- Server Actions using admin client with service_role for privileged operations
+- SPA pattern with singleton client, React Query integration, and auth state listener
+- React Native setup with AsyncStorage, deep link OAuth, and in-app browser
+- Edge Function patterns for per-request auth and admin escalation
+- Multi-tenant RLS isolation with tenant_members lookup and scoped queries
+- Decision matrix for choosing the right architecture per stack
+
+## Error Handling
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `AuthSessionMissingError` in Server Component | Cookies not passed to Supabase client | Use `createServerClient` from `@supabase/ssr` with cookie handlers |
+| OAuth redirect fails in React Native | Missing deep link scheme | Add `scheme` to app.json and configure Supabase redirect URL |
+| service_role key in client bundle | Wrong env var prefix (`NEXT_PUBLIC_`) | Remove `NEXT_PUBLIC_` prefix; only server code should access it |
+| Multi-tenant data leak | Missing RLS policy or missing tenant_id filter | Verify RLS is enabled and policies check `tenant_members` |
+| Edge Function `auth.getUser()` returns null | Missing Authorization header | Forward user's JWT from the client call |
+| Session not persisting on mobile | AsyncStorage not configured | Pass `AsyncStorage` in auth config; ensure package is installed |
+
+## Examples
+
+### Test Auth Flow End-to-End (Next.js)
+
+```typescript
+// app/auth/callback/route.ts
+import { createSupabaseServer } from '@/lib/supabase/server'
+import { NextResponse } from 'next/server'
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const code = searchParams.get('code')
+
+  if (code) {
+    const supabase = await createSupabaseServer()
+    const { error } = await supabase.auth.exchangeCodeForSession(code)
+    if (error) {
+      return NextResponse.redirect(new URL('/login?error=auth_failed', request.url))
+    }
+  }
+
+  return NextResponse.redirect(new URL('/dashboard', request.url))
+}
+```
+
+### Verify Tenant Isolation
+
+```sql
+-- Test that RLS properly isolates tenants
+SET request.jwt.claims = '{"sub": "user-uuid-1"}';
+
+-- Should only return projects for user-uuid-1's tenant
+SELECT * FROM public.projects;
+```
+
+## Resources
+
+- [Supabase SSR (Next.js)](https://supabase.com/docs/guides/auth/server-side/nextjs)
+- [Supabase React Native](https://supabase.com/docs/guides/getting-started/tutorials/with-expo-react-native)
+- [Supabase Edge Functions](https://supabase.com/docs/guides/functions)
+- [Multi-Tenant with RLS](https://supabase.com/docs/guides/database/postgres/row-level-security)
+- [Supabase Auth Deep Linking](https://supabase.com/docs/guides/auth/native-mobile-deep-linking)
+- [@supabase/ssr Package](https://supabase.com/docs/guides/auth/server-side/overview)
+
+## Next Steps
+
+For common mistakes and anti-patterns to avoid, see `supabase-known-pitfalls`.

package/skills/supabase-architecture-variants/references/variant-a-monolith-(simple).md

@@ -0,0 +1,44 @@
+# Variant A: Monolith (Simple)
+
+## Variant A: Monolith (Simple)
+
+**Best for:** MVPs, small teams, < 10K daily active users
+
+```
+my-app/
+├── src/
+│   ├── supabase/
+│   │   ├── client.ts          # Singleton client
+│   │   ├── types.ts           # Types
+│   │   └── middleware.ts      # Express middleware
+│   ├── routes/
+│   │   └── api/
+│   │       └── supabase.ts    # API routes
+│   └── index.ts
+├── tests/
+│   └── supabase.test.ts
+└── package.json
+```
+
+### Key Characteristics
+
+- Single deployment unit
+- Synchronous Supabase calls in request path
+- In-memory caching
+- Simple error handling
+
+### Code Pattern
+
+```typescript
+// Direct integration in route handler
+app.post('/api/create', async (req, res) => {
+  try {
+    const result = await supabaseClient.create(req.body);
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+---

package/skills/supabase-architecture-variants/references/variant-b-service-layer-(moderate).md

@@ -0,0 +1,72 @@
+# Variant B: Service Layer (Moderate)
+
+## Variant B: Service Layer (Moderate)
+
+**Best for:** Growing startups, 10K-100K DAU, multiple integrations
+
+```
+my-app/
+├── src/
+│   ├── services/
+│   │   ├── supabase/
+│   │   │   ├── client.ts      # Client wrapper
+│   │   │   ├── service.ts     # Business logic
+│   │   │   ├── repository.ts  # Data access
+│   │   │   └── types.ts
+│   │   └── index.ts           # Service exports
+│   ├── controllers/
+│   │   └── supabase.ts
+│   ├── routes/
+│   ├── middleware/
+│   ├── queue/
+│   │   └── supabase-processor.ts  # Async processing
+│   └── index.ts
+├── config/
+│   └── supabase/
+└── package.json
+```
+
+### Key Characteristics
+
+- Separation of concerns
+- Background job processing
+- Redis caching
+- Circuit breaker pattern
+- Structured error handling
+
+### Code Pattern
+
+```typescript
+// Service layer abstraction
+class SupabaseService {
+  constructor(
+    private client: SupabaseClient,
+    private cache: CacheService,
+    private queue: QueueService
+  ) {}
+
+  async createResource(data: CreateInput): Promise<Resource> {
+    // Business logic before API call
+    const validated = this.validate(data);
+
+    // Check cache
+    const cached = await this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    // API call with retry
+    const result = await this.withRetry(() =>
+      this.client.create(validated)
+    );
+
+    // Cache result
+    await this.cache.set(cacheKey, result, 300);
+
+    // Async follow-up
+    await this.queue.enqueue('supabase.post-create', result);
+
+    return result;
+  }
+}
+```
+
+---

package/skills/supabase-architecture-variants/references/variant-c-microservice-(complex).md

@@ -0,0 +1,81 @@
+# Variant C: Microservice (Complex)
+
+## Variant C: Microservice (Complex)
+
+**Best for:** Enterprise, 100K+ DAU, strict SLAs
+
+```
+supabase-service/              # Dedicated microservice
+├── src/
+│   ├── api/
+│   │   ├── grpc/
+│   │   │   └── supabase.proto
+│   │   └── rest/
+│   │       └── routes.ts
+│   ├── domain/
+│   │   ├── entities/
+│   │   ├── events/
+│   │   └── services/
+│   ├── infrastructure/
+│   │   ├── supabase/
+│   │   │   ├── client.ts
+│   │   │   ├── mapper.ts
+│   │   │   └── circuit-breaker.ts
+│   │   ├── cache/
+│   │   ├── queue/
+│   │   └── database/
+│   └── index.ts
+├── config/
+├── k8s/
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   └── hpa.yaml
+└── package.json
+
+other-services/
+├── order-service/       # Calls supabase-service
+├── payment-service/
+└── notification-service/
+```
+
+### Key Characteristics
+
+- Dedicated Supabase microservice
+- gRPC for internal communication
+- Event-driven architecture
+- Database per service
+- Kubernetes autoscaling
+- Distributed tracing
+- Circuit breaker per service
+
+### Code Pattern
+
+```typescript
+// Event-driven with domain isolation
+class SupabaseAggregate {
+  private events: DomainEvent[] = [];
+
+  process(command: SupabaseCommand): void {
+    // Domain logic
+    const result = this.execute(command);
+
+    // Emit domain event
+    this.events.push(new SupabaseProcessedEvent(result));
+  }
+
+  getUncommittedEvents(): DomainEvent[] {
+    return [...this.events];
+  }
+}
+
+// Event handler
+@EventHandler(SupabaseProcessedEvent)
+class SupabaseEventHandler {
+  async handle(event: SupabaseProcessedEvent): Promise<void> {
+    // Saga orchestration
+    await this.sagaOrchestrator.continue(event);
+  }
+}
+```
+
+---