@intentsolutionsio/supabase-pack 1.0.0

package/skills/supabase-auth-storage-realtime-core/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: supabase-auth-storage-realtime-core
+description: |
+  Execute Supabase secondary workflow: Auth + Storage + Realtime.
+  Use when implementing secondary use case,
+  or complementing primary workflow.
+  Trigger with phrases like "supabase auth storage realtime",
+  "implement full stack features with supabase".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Auth + Storage + Realtime
+
+## Overview
+Implement the core Supabase trifecta: authentication, file storage,
+and real-time subscriptions in a single cohesive setup.
+
+
+## Prerequisites
+- Completed `supabase-install-auth` setup
+- Familiarity with `supabase-schema-from-requirements`
+- Valid API credentials configured
+
+## Instructions
+
+### Step 1: Setup
+```typescript
+// Step 1 implementation
+```
+
+### Step 2: Process
+```typescript
+// Step 2 implementation
+```
+
+### Step 3: Complete
+```typescript
+// Step 3 implementation
+```
+
+## Output
+- Completed Auth + Storage + Realtime execution
+- Results from Supabase API
+- Success confirmation or error details
+
+## Error Handling
+| Aspect | Schema from Requirements | Auth + Storage + Realtime |
+|--------|------------|------------|
+| Use Case | Starting a new project with defined data requirements | Secondary |
+| Complexity | Medium | Lower |
+| Performance | Standard | Optimized |
+
+## Examples
+
+### Complete Workflow
+```typescript
+// Complete workflow example
+```
+
+### Error Recovery
+```typescript
+// Error handling code
+```
+
+## Resources
+- [Supabase Documentation](https://supabase.com/docs)
+- [Supabase API Reference](https://supabase.com/docs/api)
+
+## Next Steps
+For common errors, see `supabase-common-errors`.

package/skills/supabase-ci-integration/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: supabase-ci-integration
+description: |
+  Configure Supabase CI/CD integration with GitHub Actions and testing.
+  Use when setting up automated testing, configuring CI pipelines,
+  or integrating Supabase tests into your build process.
+  Trigger with phrases like "supabase CI", "supabase GitHub Actions",
+  "supabase automated tests", "CI supabase".
+allowed-tools: Read, Write, Edit, Bash(gh:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase CI Integration
+
+## Overview
+Set up CI/CD pipelines for Supabase integrations with automated testing.
+
+## Prerequisites
+- GitHub repository with Actions enabled
+- Supabase test API key
+- npm/pnpm project configured
+
+## Instructions
+
+### Step 1: Create GitHub Actions Workflow
+Create `.github/workflows/supabase-integration.yml`:
+
+```yaml
+name: Supabase Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  SUPABASE_API_KEY: ${{ secrets.SUPABASE_API_KEY }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      SUPABASE_API_KEY: ${{ secrets.SUPABASE_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test -- --coverage
+      - run: npm run test:integration
+```
+
+### Step 2: Configure Secrets
+```bash
+gh secret set SUPABASE_API_KEY --body "sk_test_***"
+```
+
+### Step 3: Add Integration Tests
+```typescript
+describe('Supabase Integration', () => {
+  it.skipIf(!process.env.SUPABASE_API_KEY)('should connect', async () => {
+    const client = getSupabaseClient();
+    const result = await client.healthCheck();
+    expect(result.status).toBe('ok');
+  });
+});
+```
+
+## Output
+- Automated test pipeline
+- PR checks configured
+- Coverage reports uploaded
+- Release workflow ready
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Secret not found | Missing configuration | Add secret via `gh secret set` |
+| Tests timeout | Network issues | Increase timeout or mock |
+| Auth failures | Invalid key | Check secret value |
+
+## Examples
+
+### Release Workflow
+```yaml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      SUPABASE_API_KEY: ${{ secrets.SUPABASE_API_KEY_PROD }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Verify Supabase production readiness
+        run: npm run test:integration
+      - run: npm run build
+      - run: npm publish
+```
+
+### Branch Protection
+```yaml
+required_status_checks:
+  - "test"
+  - "supabase-integration"
+```
+
+## Resources
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Supabase CI Guide](https://supabase.com/docs/ci)
+
+## Next Steps
+For deployment patterns, see `supabase-deploy-integration`.

package/skills/supabase-common-errors/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: supabase-common-errors
+description: |
+  Diagnose and fix Supabase common errors and exceptions.
+  Use when encountering Supabase errors, debugging failed requests,
+  or troubleshooting integration issues.
+  Trigger with phrases like "supabase error", "fix supabase",
+  "supabase not working", "debug supabase".
+allowed-tools: Read, Grep, Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Common Errors
+
+## Overview
+Quick reference for the top 10 most common Supabase errors and their solutions.
+
+## Prerequisites
+- Supabase SDK installed
+- API credentials configured
+- Access to error logs
+
+## Instructions
+
+### Step 1: Identify the Error
+Check error message and code in your logs or console.
+
+### Step 2: Find Matching Error Below
+Match your error to one of the documented cases.
+
+### Step 3: Apply Solution
+Follow the solution steps for your specific error.
+
+## Output
+- Identified error cause
+- Applied fix
+- Verified resolution
+
+## Error Handling
+
+### Invalid JWT
+**Error Message:**
+```
+Invalid JWT: expired or malformed
+```
+
+**Cause:** JWT token has expired or is incorrectly formatted
+
+**Solution:**
+```bash
+Check token expiry with supabase.auth.getSession() and call refreshSession() if needed
+```
+
+---
+
+### RLS Policy Violation
+**Error Message:**
+```
+new row violates row-level security policy for table
+```
+
+**Cause:** Row Level Security (RLS) policy is blocking the operation
+
+**Solution:**
+Check RLS policies in dashboard or via pg_policies table. Ensure user has required role.
+
+---
+
+### Connection Pool Exhausted
+**Error Message:**
+```
+too many clients already
+```
+
+**Cause:** Connection pool limit reached due to too many concurrent connections
+
+**Solution:**
+```typescript
+Use connection pooling mode in Supabase dashboard. Switch to Session mode or pgBouncer.
+```
+
+## Examples
+
+### Quick Diagnostic Commands
+```bash
+# Check Supabase status
+curl -s https://status.supabase.com
+
+# Verify API connectivity
+curl -I https://api.supabase.com
+
+# Check local configuration
+env | grep SUPABASE
+```
+
+### Escalation Path
+1. Collect evidence with `supabase-debug-bundle`
+2. Check Supabase status page
+3. Contact support with request ID
+
+## Resources
+- [Supabase Status Page](https://status.supabase.com)
+- [Supabase Support](https://supabase.com/docs/support)
+- [Supabase Error Codes](https://supabase.com/docs/errors)
+
+## Next Steps
+For comprehensive debugging, see `supabase-debug-bundle`.

package/skills/supabase-cost-tuning/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: supabase-cost-tuning
+description: |
+  Optimize Supabase costs through tier selection, sampling, and usage monitoring.
+  Use when analyzing Supabase billing, reducing API costs,
+  or implementing usage monitoring and budget alerts.
+  Trigger with phrases like "supabase cost", "supabase billing",
+  "reduce supabase costs", "supabase pricing", "supabase expensive", "supabase budget".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Cost Tuning
+
+## Overview
+Optimize Supabase costs through smart tier selection, sampling, and usage monitoring.
+
+## Prerequisites
+- Access to Supabase billing dashboard
+- Understanding of current usage patterns
+- Database for usage tracking (optional)
+- Alerting system configured (optional)
+
+## Pricing Tiers
+
+| Tier | Monthly Cost | Included | Overage |
+|------|-------------|----------|---------|
+| Free | $0 | 500MB database, 1GB storage, 50K MAUs | N/A |
+| Pro | $25 | 8GB database, 100GB storage, 100K MAUs | $0.001/request |
+| Enterprise | Custom | Unlimited | Volume discounts |
+
+## Cost Estimation
+
+```typescript
+interface UsageEstimate {
+  requestsPerMonth: number;
+  tier: string;
+  estimatedCost: number;
+  recommendation?: string;
+}
+
+function estimateSupabaseCost(requestsPerMonth: number): UsageEstimate {
+  if (requestsPerMonth <= 1000) {
+    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
+  }
+
+  if (requestsPerMonth <= 100000) {
+    return { requestsPerMonth, tier: 'Pro', estimatedCost: 25 };
+  }
+
+  const proOverage = (requestsPerMonth - 100000) * 0.001;
+  const proCost = 25 + proOverage;
+
+  return {
+    requestsPerMonth,
+    tier: 'Pro (with overage)',
+    estimatedCost: proCost,
+    recommendation: proCost > 500
+      ? 'Consider Enterprise tier for volume discounts'
+      : undefined,
+  };
+}
+```
+
+## Usage Monitoring
+
+```typescript
+class SupabaseUsageMonitor {
+  private requestCount = 0;
+  private bytesTransferred = 0;
+  private alertThreshold: number;
+
+  constructor(monthlyBudget: number) {
+    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
+  }
+
+  track(request: { bytes: number }) {
+    this.requestCount++;
+    this.bytesTransferred += request.bytes;
+
+    if (this.estimatedCost() > this.alertThreshold) {
+      this.sendAlert('Approaching Supabase budget limit');
+    }
+  }
+
+  estimatedCost(): number {
+    return estimateSupabaseCost(this.requestCount).estimatedCost;
+  }
+
+  private sendAlert(message: string) {
+    // Send to Slack, email, PagerDuty, etc.
+  }
+}
+```
+
+## Cost Reduction Strategies
+
+### Step 1: Request Sampling
+```typescript
+function shouldSample(samplingRate = 0.1): boolean {
+  return Math.random() < samplingRate;
+}
+
+// Use for non-critical telemetry
+if (shouldSample(0.1)) { // 10% sample
+  await supabaseClient.trackEvent(event);
+}
+```
+
+### Step 2: Batching Requests
+```typescript
+// Instead of N individual calls
+await Promise.all(ids.map(id => supabaseClient.get(id)));
+
+// Use batch endpoint (1 call)
+await supabaseClient.batchGet(ids);
+```
+
+### Step 3: Caching (from P16)
+- Cache frequently accessed data
+- Use cache invalidation webhooks
+- Set appropriate TTLs
+
+### Step 4: Compression
+```typescript
+const client = new SupabaseClient({
+  compression: true, // Enable gzip
+});
+```
+
+## Budget Alerts
+
+```bash
+# Set up billing alerts in Supabase dashboard
+# Or use API if available:
+# Check Supabase documentation for billing APIs
+```
+
+## Cost Dashboard Query
+
+```sql
+-- If tracking usage in your database
+SELECT
+  DATE_TRUNC('day', created_at) as date,
+  COUNT(*) as requests,
+  SUM(response_bytes) as bytes,
+  COUNT(*) * 0.001 as estimated_cost
+FROM supabase_api_logs
+WHERE created_at >= NOW() - INTERVAL '30 days'
+GROUP BY 1
+ORDER BY 1;
+```
+
+## Instructions
+
+### Step 1: Analyze Current Usage
+Review Supabase dashboard for usage patterns and costs.
+
+### Step 2: Select Optimal Tier
+Use the cost estimation function to find the right tier.
+
+### Step 3: Implement Monitoring
+Add usage tracking to catch budget overruns early.
+
+### Step 4: Apply Optimizations
+Enable batching, caching, and sampling where appropriate.
+
+## Output
+- Optimized tier selection
+- Usage monitoring implemented
+- Budget alerts configured
+- Cost reduction strategies applied
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Unexpected charges | Untracked usage | Implement monitoring |
+| Overage fees | Wrong tier | Upgrade tier |
+| Budget exceeded | No alerts | Set up alerts |
+| Inefficient usage | No batching | Enable batch requests |
+
+## Examples
+
+### Quick Cost Check
+```typescript
+// Estimate monthly cost for your usage
+const estimate = estimateSupabaseCost(yourMonthlyRequests);
+console.log(`Tier: ${estimate.tier}, Cost: $${estimate.estimatedCost}`);
+if (estimate.recommendation) {
+  console.log(`💡 ${estimate.recommendation}`);
+}
+```
+
+## Resources
+- [Supabase Pricing](https://supabase.com/pricing)
+- [Supabase Billing Dashboard](https://dashboard.supabase.com/billing)
+
+## Next Steps
+For architecture patterns, see `supabase-reference-architecture`.