@intentsolutionsio/supabase-pack 1.0.0

package/skills/supabase-schema-from-requirements/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: supabase-schema-from-requirements
+description: |
+  Execute Supabase primary workflow: Schema from Requirements.
+  Use when Starting a new project with defined data requirements,
+  Refactoring an existing schema based on new features, or Creating migrations from specification documents.
+  Trigger with phrases like "supabase schema from requirements",
+  "generate database schema with supabase".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Schema from Requirements
+
+## Overview
+Generate Supabase database schema from natural language requirements.
+This is the primary workflow for starting new Supabase projects.
+
+
+## Prerequisites
+- Completed `supabase-install-auth` setup
+- Understanding of Supabase core concepts
+- Valid API credentials configured
+
+## Instructions
+
+### Step 1: Initialize
+```typescript
+// Step 1 implementation
+```
+
+### Step 2: Execute
+```typescript
+// Step 2 implementation
+```
+
+### Step 3: Finalize
+```typescript
+// Step 3 implementation
+```
+
+## Output
+- Completed Schema from Requirements execution
+- Expected results from Supabase API
+- Success confirmation or error details
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Error 1 | Cause | Solution |
+| Error 2 | Cause | Solution |
+
+## Examples
+
+### Complete Workflow
+```typescript
+// Complete workflow example
+```
+
+### Common Variations
+- Variation 1: Description
+- Variation 2: Description
+
+## Resources
+- [Supabase Documentation](https://supabase.com/docs)
+- [Supabase API Reference](https://supabase.com/docs/api)
+
+## Next Steps
+For secondary workflow, see `supabase-auth-storage-realtime-core`.

package/skills/supabase-sdk-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: supabase-sdk-patterns
+description: |
+  Apply production-ready Supabase SDK patterns for TypeScript and Python.
+  Use when implementing Supabase integrations, refactoring SDK usage,
+  or establishing team coding standards for Supabase.
+  Trigger with phrases like "supabase SDK patterns", "supabase best practices",
+  "supabase code patterns", "idiomatic supabase".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase SDK Patterns
+
+## Overview
+Production-ready patterns for Supabase SDK usage in TypeScript and Python.
+
+## Prerequisites
+- Completed `supabase-install-auth` setup
+- Familiarity with async/await patterns
+- Understanding of error handling best practices
+
+## Instructions
+
+### Step 1: Implement Singleton Pattern (Recommended)
+```typescript
+// src/supabase/client.ts
+import { SupabaseClient } from '@supabase/supabase-js';
+
+let instance: SupabaseClient | null = null;
+
+export function getSupabaseClient(): SupabaseClient {
+  if (!instance) {
+    instance = new SupabaseClient({
+      apiKey: process.env.SUPABASE_API_KEY!,
+      // Additional options
+    });
+  }
+  return instance;
+}
+```
+
+### Step 2: Add Error Handling Wrapper
+```typescript
+import { SupabaseError } from '@supabase/supabase-js';
+
+async function safeSupabaseCall<T>(
+  operation: () => Promise<T>
+): Promise<{ data: T | null; error: Error | null }> {
+  try {
+    const data = await operation();
+    return { data, error: null };
+  } catch (err) {
+    if (err instanceof SupabaseError) {
+      console.error({
+        code: err.code,
+        message: err.message,
+      });
+    }
+    return { data: null, error: err as Error };
+  }
+}
+```
+
+### Step 3: Implement Retry Logic
+```typescript
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  backoffMs = 1000
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (err) {
+      if (attempt === maxRetries) throw err;
+      const delay = backoffMs * Math.pow(2, attempt - 1);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+## Output
+- Type-safe client singleton
+- Robust error handling with structured logging
+- Automatic retry with exponential backoff
+- Runtime validation for API responses
+
+## Error Handling
+| Pattern | Use Case | Benefit |
+|---------|----------|---------|
+| Safe wrapper | All API calls | Prevents uncaught exceptions |
+| Retry logic | Transient failures | Improves reliability |
+| Type guards | Response validation | Catches API changes |
+| Logging | All operations | Debugging and monitoring |
+
+## Examples
+
+### Factory Pattern (Multi-tenant)
+```typescript
+const clients = new Map<string, SupabaseClient>();
+
+export function getClientForTenant(tenantId: string): SupabaseClient {
+  if (!clients.has(tenantId)) {
+    const apiKey = getTenantApiKey(tenantId);
+    clients.set(tenantId, new SupabaseClient({ apiKey }));
+  }
+  return clients.get(tenantId)!;
+}
+```
+
+### Python Context Manager
+```python
+from contextlib import asynccontextmanager
+from supabase import SupabaseClient
+
+@asynccontextmanager
+async def get_supabase_client():
+    client = SupabaseClient()
+    try:
+        yield client
+    finally:
+        await client.close()
+```
+
+### Zod Validation
+```typescript
+import { z } from 'zod';
+
+const supabaseResponseSchema = z.object({
+  id: z.string(),
+  status: z.enum(['active', 'inactive']),
+  createdAt: z.string().datetime(),
+});
+```
+
+## Resources
+- [Supabase SDK Reference](https://supabase.com/docs/sdk)
+- [Supabase API Types](https://supabase.com/docs/types)
+- [Zod Documentation](https://zod.dev/)
+
+## Next Steps
+Apply patterns in `supabase-core-workflow-a` for real-world usage.

package/skills/supabase-security-basics/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: supabase-security-basics
+description: |
+  Apply Supabase security best practices for secrets and access control.
+  Use when securing API keys, implementing least privilege access,
+  or auditing Supabase security configuration.
+  Trigger with phrases like "supabase security", "supabase secrets",
+  "secure supabase", "supabase API key security".
+allowed-tools: Read, Write, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Security Basics
+
+## Overview
+Security best practices for Supabase API keys, tokens, and access control.
+
+## Prerequisites
+- Supabase SDK installed
+- Understanding of environment variables
+- Access to Supabase dashboard
+
+## Instructions
+
+### Step 1: Configure Environment Variables
+```bash
+# .env (NEVER commit to git)
+SUPABASE_API_KEY=sk_live_***
+SUPABASE_SECRET=***
+
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+### Step 2: Implement Secret Rotation
+```bash
+# 1. Generate new key in Supabase dashboard
+# 2. Update environment variable
+export SUPABASE_API_KEY="new_key_here"
+
+# 3. Verify new key works
+curl -H "Authorization: Bearer ${SUPABASE_API_KEY}" \
+  https://api.supabase.com/health
+
+# 4. Revoke old key in dashboard
+```
+
+### Step 3: Apply Least Privilege
+| Environment | Recommended Scopes |
+|-------------|-------------------|
+| Development | `read, write` |
+| Staging | `read, write, admin` |
+| Production | `read, write` |
+
+## Output
+- Secure API key storage
+- Environment-specific access controls
+- Audit logging enabled
+
+## Error Handling
+| Security Issue | Detection | Mitigation |
+|----------------|-----------|------------|
+| Exposed API key | Git scanning | Rotate immediately |
+| Excessive scopes | Audit logs | Reduce permissions |
+| Missing rotation | Key age check | Schedule rotation |
+
+## Examples
+
+### Service Account Pattern
+```typescript
+const clients = {
+  reader: new SupabaseClient({
+    apiKey: process.env.SUPABASE_READ_KEY,
+  }),
+  writer: new SupabaseClient({
+    apiKey: process.env.SUPABASE_WRITE_KEY,
+  }),
+};
+```
+
+### Webhook Signature Verification
+```typescript
+import crypto from 'crypto';
+
+function verifyWebhookSignature(
+  payload: string, signature: string, secret: string
+): boolean {
+  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+### Security Checklist
+- [ ] API keys in environment variables
+- [ ] `.env` files in `.gitignore`
+- [ ] Different keys for dev/staging/prod
+- [ ] Minimal scopes per environment
+- [ ] Webhook signatures validated
+- [ ] Audit logging enabled
+
+### Audit Logging
+```typescript
+interface AuditEntry {
+  timestamp: Date;
+  action: string;
+  userId: string;
+  resource: string;
+  result: 'success' | 'failure';
+  metadata?: Record<string, any>;
+}
+
+async function auditLog(entry: Omit<AuditEntry, 'timestamp'>): Promise<void> {
+  const log: AuditEntry = { ...entry, timestamp: new Date() };
+
+  // Log to Supabase analytics
+  await supabaseClient.track('audit', log);
+
+  // Also log locally for compliance
+  console.log('[AUDIT]', JSON.stringify(log));
+}
+
+// Usage
+await auditLog({
+  action: 'supabase.api.call',
+  userId: currentUser.id,
+  resource: '/v1/resource',
+  result: 'success',
+});
+```
+
+## Resources
+- [Supabase Security Guide](https://supabase.com/docs/security)
+- [Supabase API Scopes](https://supabase.com/docs/scopes)
+
+## Next Steps
+For production deployment, see `supabase-prod-checklist`.

package/skills/supabase-upgrade-migration/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: supabase-upgrade-migration
+description: |
+  Analyze, plan, and execute Supabase SDK upgrades with breaking change detection.
+  Use when upgrading Supabase SDK versions, detecting deprecations,
+  or migrating to new API versions.
+  Trigger with phrases like "upgrade supabase", "supabase migration",
+  "supabase breaking changes", "update supabase SDK", "analyze supabase version".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Upgrade & Migration
+
+## Overview
+Guide for upgrading Supabase SDK versions and handling breaking changes.
+
+## Prerequisites
+- Current Supabase SDK installed
+- Git for version control
+- Test suite available
+- Staging environment
+
+## Instructions
+
+### Step 1: Check Current Version
+```bash
+npm list @supabase/supabase-js
+npm view @supabase/supabase-js version
+```
+
+### Step 2: Review Changelog
+```bash
+open https://github.com/supabase/sdk/releases
+```
+
+### Step 3: Create Upgrade Branch
+```bash
+git checkout -b upgrade/supabase-sdk-vX.Y.Z
+npm install @supabase/supabase-js@latest
+npm test
+```
+
+### Step 4: Handle Breaking Changes
+Update import statements, configuration, and method signatures as needed.
+
+## Output
+- Updated SDK version
+- Fixed breaking changes
+- Passing test suite
+- Documented rollback procedure
+
+## Error Handling
+| SDK Version | API Version | Node.js | Breaking Changes |
+|-------------|-------------|---------|------------------|
+| 3.x | 2024-01 | 18+ | Major refactor |
+| 2.x | 2023-06 | 16+ | Auth changes |
+| 1.x | 2022-01 | 14+ | Initial release |
+
+## Examples
+
+### Import Changes
+```typescript
+// Before (v1.x)
+import { Client } from '@supabase/supabase-js';
+
+// After (v2.x)
+import { SupabaseClient } from '@supabase/supabase-js';
+```
+
+### Configuration Changes
+```typescript
+// Before (v1.x)
+const client = new Client({ key: 'xxx' });
+
+// After (v2.x)
+const client = new SupabaseClient({
+  apiKey: 'xxx',
+});
+```
+
+### Rollback Procedure
+```bash
+npm install @supabase/supabase-js@1.x.x --save-exact
+```
+
+### Deprecation Handling
+```typescript
+// Monitor for deprecation warnings in development
+if (process.env.NODE_ENV === 'development') {
+  process.on('warning', (warning) => {
+    if (warning.name === 'DeprecationWarning') {
+      console.warn('[Supabase]', warning.message);
+      // Log to tracking system for proactive updates
+    }
+  });
+}
+
+// Common deprecation patterns to watch for:
+// - Renamed methods: client.oldMethod() -> client.newMethod()
+// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
+// - Removed features: Check release notes before upgrading
+```
+
+## Resources
+- [Supabase Changelog](https://github.com/supabase/sdk/releases)
+- [Supabase Migration Guide](https://supabase.com/docs/migration)
+
+## Next Steps
+For CI integration during upgrades, see `supabase-ci-integration`.

package/skills/supabase-webhooks-events/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: supabase-webhooks-events
+description: |
+  Implement Supabase webhook signature validation and event handling.
+  Use when setting up webhook endpoints, implementing signature verification,
+  or handling Supabase event notifications securely.
+  Trigger with phrases like "supabase webhook", "supabase events",
+  "supabase webhook signature", "handle supabase events", "supabase notifications".
+allowed-tools: Read, Write, Edit, Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Webhooks & Events
+
+## Overview
+Securely handle Supabase webhooks with signature validation and replay protection.
+
+## Prerequisites
+- Supabase webhook secret configured
+- HTTPS endpoint accessible from internet
+- Understanding of cryptographic signatures
+- Redis or database for idempotency (optional)
+
+## Webhook Endpoint Setup
+
+### Express.js
+```typescript
+import express from 'express';
+import crypto from 'crypto';
+
+const app = express();
+
+// IMPORTANT: Raw body needed for signature verification
+app.post('/webhooks/supabase',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    const signature = req.headers['x-supabase-signature'] as string;
+    const timestamp = req.headers['x-supabase-timestamp'] as string;
+
+    if (!verifySupabaseSignature(req.body, signature, timestamp)) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    const event = JSON.parse(req.body.toString());
+    await handleSupabaseEvent(event);
+
+    res.status(200).json({ received: true });
+  }
+);
+```
+
+## Signature Verification
+
+```typescript
+function verifySupabaseSignature(
+  payload: Buffer,
+  signature: string,
+  timestamp: string
+): boolean {
+  const secret = process.env.SUPABASE_WEBHOOK_SECRET!;
+
+  // Reject old timestamps (replay attack protection)
+  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
+  if (timestampAge > 300000) { // 5 minutes
+    console.error('Webhook timestamp too old');
+    return false;
+  }
+
+  // Compute expected signature
+  const signedPayload = `${timestamp}.${payload.toString()}`;
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Timing-safe comparison
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  );
+}
+```
+
+## Event Handler Pattern
+
+```typescript
+type SupabaseEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
+
+interface SupabaseEvent {
+  id: string;
+  type: SupabaseEventType;
+  data: Record<string, any>;
+  created: string;
+}
+
+const eventHandlers: Record<SupabaseEventType, (data: any) => Promise<void>> = {
+  'resource.created': async (data) => { /* handle */ },
+  'resource.updated': async (data) => { /* handle */ },
+  'resource.deleted': async (data) => { /* handle */ }
+};
+
+async function handleSupabaseEvent(event: SupabaseEvent): Promise<void> {
+  const handler = eventHandlers[event.type];
+
+  if (!handler) {
+    console.log(`Unhandled event type: ${event.type}`);
+    return;
+  }
+
+  try {
+    await handler(event.data);
+    console.log(`Processed ${event.type}: ${event.id}`);
+  } catch (error) {
+    console.error(`Failed to process ${event.type}: ${event.id}`, error);
+    throw error; // Rethrow to trigger retry
+  }
+}
+```
+
+## Idempotency Handling
+
+```typescript
+import { Redis } from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+async function isEventProcessed(eventId: string): Promise<boolean> {
+  const key = `supabase:event:${eventId}`;
+  const exists = await redis.exists(key);
+  return exists === 1;
+}
+
+async function markEventProcessed(eventId: string): Promise<void> {
+  const key = `supabase:event:${eventId}`;
+  await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
+}
+```
+
+## Webhook Testing
+
+```bash
+# Use Supabase CLI to send test events
+supabase functions invoke webhook-handler
+
+# Or use webhook.site for debugging
+curl -X POST https://webhook.site/your-uuid \
+  -H "Content-Type: application/json" \
+  -d '{"type": "resource.created", "data": {}}'
+```
+
+## Instructions
+
+### Step 1: Register Webhook Endpoint
+Configure your webhook URL in the Supabase dashboard.
+
+### Step 2: Implement Signature Verification
+Use the signature verification code to validate incoming webhooks.
+
+### Step 3: Handle Events
+Implement handlers for each event type your application needs.
+
+### Step 4: Add Idempotency
+Prevent duplicate processing with event ID tracking.
+
+## Output
+- Secure webhook endpoint
+- Signature validation enabled
+- Event handlers implemented
+- Replay attack protection active
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Invalid signature | Wrong secret | Verify webhook secret |
+| Timestamp rejected | Clock drift | Check server time sync |
+| Duplicate events | Missing idempotency | Implement event ID tracking |
+| Handler timeout | Slow processing | Use async queue |
+
+## Examples
+
+### Testing Webhooks Locally
+```bash
+# Use ngrok to expose local server
+ngrok http 3000
+
+# Send test webhook
+curl -X POST https://your-ngrok-url/webhooks/supabase \
+  -H "Content-Type: application/json" \
+  -d '{"type": "test", "data": {}}'
+```
+
+## Resources
+- [Supabase Webhooks Guide](https://supabase.com/docs/webhooks)
+- [Webhook Security Best Practices](https://supabase.com/docs/webhooks/security)
+
+## Next Steps
+For performance optimization, see `supabase-performance-tuning`.