@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

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

@@ -1,290 +1,285 @@
 ---
 name: supabase-reliability-patterns
-description: |
-  Implement Supabase reliability patterns including circuit breakers, idempotency, and graceful degradation.
-  Use when building fault-tolerant Supabase integrations, implementing retry strategies,
-  or adding resilience to production Supabase services.
-  Trigger with phrases like "supabase reliability", "supabase circuit breaker",
-  "supabase idempotent", "supabase resilience", "supabase fallback", "supabase bulkhead".
-allowed-tools: Read, Write, Edit
-version: 1.0.0
-license: MIT
-author: Jeremy Longshore <jeremy@intentsolutions.io>
----
+description: 'Build resilient Supabase integrations: circuit breakers wrapping createClient
 
-# Supabase Reliability Patterns
+  calls, offline queue with IndexedDB, graceful degradation with cached fallbacks,
 
-## Overview
-Production-grade reliability patterns for Supabase integrations.
+  health check endpoints, retry with exponential backoff and jitter,
 
-## Prerequisites
-- Understanding of circuit breaker pattern
-- opossum or similar library installed
-- Queue infrastructure for DLQ
-- Caching layer for fallbacks
+  and dual-write patterns for critical data.
 
-## Circuit Breaker
+  Use when building fault-tolerant apps, handling Supabase outages gracefully,
 
-```typescript
-import CircuitBreaker from 'opossum';
-
-const supabaseBreaker = new CircuitBreaker(
-  async (operation: () => Promise<any>) => operation(),
-  {
-    timeout: 30000,
-    errorThresholdPercentage: 50,
-    resetTimeout: 30000,
-    volumeThreshold: 10,
-  }
-);
+  implementing offline-first patterns, or adding retry logic to SDK calls.
 
-// Events
-supabaseBreaker.on('open', () => {
-  console.warn('Supabase circuit OPEN - requests failing fast');
-  alertOps('Supabase circuit breaker opened');
-});
+  Trigger with phrases like "supabase circuit breaker", "supabase offline",
 
-supabaseBreaker.on('halfOpen', () => {
-  console.info('Supabase circuit HALF-OPEN - testing recovery');
-});
+  "supabase retry", "supabase health check", "supabase fallback",
 
-supabaseBreaker.on('close', () => {
-  console.info('Supabase circuit CLOSED - normal operation');
-});
+  "supabase resilience", "supabase dual write", "supabase outage".
 
-// Usage
-async function safeSupabaseCall<T>(fn: () => Promise<T>): Promise<T> {
-  return supabaseBreaker.fire(fn);
-}
-```
+  '
+allowed-tools: Read, Write, Edit, Bash(supabase:*), Bash(curl:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- reliability
+- resilience
+- circuit-breaker
+- offline
+- retry
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
+---
+# Supabase Reliability Patterns
 
-## Idempotency Keys
+## Overview
 
-```typescript
-import { v4 as uuidv4 } from 'uuid';
-import crypto from 'crypto';
-
-// Generate deterministic idempotency key from input
-function generateIdempotencyKey(
-  operation: string,
-  params: Record<string, any>
-): string {
-  const data = JSON.stringify({ operation, params });
-  return crypto.createHash('sha256').update(data).digest('hex');
-}
+Production Supabase apps need six reliability layers: **circuit breakers** (stop calling Supabase when it's down to prevent cascading failures), **offline queue** (buffer writes when the network is unavailable and replay when reconnected), **graceful degradation** (serve cached or fallback data during outages), **health checks** (detect Supabase availability before routing traffic), **retry with exponential backoff** (handle transient errors without overwhelming the service), and **dual-write** (write critical data to both Supabase and a backup store). All patterns use real `createClient` from `@supabase/supabase-js`.
 
-// Or use random key with storage
-class IdempotencyManager {
-  private store: Map<string, { key: string; expiresAt: Date }> = new Map();
+## Prerequisites
 
-  getOrCreate(operationId: string): string {
-    const existing = this.store.get(operationId);
-    if (existing && existing.expiresAt > new Date()) {
-      return existing.key;
-    }
+- `@supabase/supabase-js` v2+ installed
+- TypeScript project with Supabase client configured
+- For offline queue: browser environment with IndexedDB or server with Redis
+- For dual-write: secondary data store (Redis, DynamoDB, or local SQLite)
 
-    const key = uuidv4();
-    this.store.set(operationId, {
-      key,
-      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
-    });
-    return key;
-  }
-}
-```
+## Step 1 — Circuit Breaker and Retry with Exponential Backoff
+
+A circuit breaker tracks failures per Supabase service (database, auth, storage) and stops making calls when a threshold is exceeded. Combined with retry logic, it prevents both cascading failures and unnecessary retries during extended outages.
 
-## Bulkhead Pattern
+### Circuit Breaker Implementation
 
 ```typescript
-import PQueue from 'p-queue';
-
-// Separate queues for different operations
-const supabaseQueues = {
-  critical: new PQueue({ concurrency: 10 }),
-  normal: new PQueue({ concurrency: 5 }),
-  bulk: new PQueue({ concurrency: 2 }),
-};
-
-async function prioritizedSupabaseCall<T>(
-  priority: 'critical' | 'normal' | 'bulk',
-  fn: () => Promise<T>
-): Promise<T> {
-  return supabaseQueues[priority].add(fn);
-}
+// lib/circuit-breaker.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
 
-// Usage
-await prioritizedSupabaseCall('critical', () =>
-  supabaseClient.processPayment(order)
-);
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN'
 
-await prioritizedSupabaseCall('bulk', () =>
-  supabaseClient.syncCatalog(products)
-);
-```
+interface CircuitBreakerOptions {
+  failureThreshold: number    // failures before opening
+  resetTimeoutMs: number      // ms before trying again (half-open)
+  halfOpenSuccesses: number   // successes in half-open to close
+  name: string                // for logging
+}
 
-## Timeout Hierarchy
+class CircuitBreaker {
+  private state: CircuitState = 'CLOSED'
+  private failures = 0
+  private lastFailureTime = 0
+  private halfOpenSuccesses = 0
+
+  constructor(private opts: CircuitBreakerOptions) {}
+
+  async call<T>(fn: () => Promise<T>, fallback?: () => T): Promise<T> {
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (this.state === 'OPEN') {
+      if (Date.now() - this.lastFailureTime > this.opts.resetTimeoutMs) {
+        this.state = 'HALF_OPEN'
+        this.halfOpenSuccesses = 0
+        console.log(`[CircuitBreaker:${this.opts.name}] OPEN → HALF_OPEN`)
+      } else {
+        if (fallback) return fallback()
+        throw new Error(`Circuit breaker ${this.opts.name} is OPEN`)
+      }
+    }
 
-```typescript
-const TIMEOUT_CONFIG = {
-  connect: 5000,      // Initial connection
-  request: 30000,     // Standard requests
-  upload: 120000,     // File uploads
-  longPoll: 300000,   // Webhook long-polling
-};
-
-async function timedoutSupabaseCall<T>(
-  operation: 'connect' | 'request' | 'upload' | 'longPoll',
-  fn: () => Promise<T>
-): Promise<T> {
-  const timeout = TIMEOUT_CONFIG[operation];
-
-  return Promise.race([
-    fn(),
-    new Promise<never>((_, reject) =>
-      setTimeout(() => reject(new Error(`Supabase ${operation} timeout`)), timeout)
-    ),
-  ]);
-}
-```
+    try {
+      const result = await fn()
+
+      // Success in HALF_OPEN: count toward recovery
+      if (this.state === 'HALF_OPEN') {
+        this.halfOpenSuccesses++
+        if (this.halfOpenSuccesses >= this.opts.halfOpenSuccesses) {
+          this.state = 'CLOSED'
+          this.failures = 0
+          console.log(`[CircuitBreaker:${this.opts.name}] HALF_OPEN → CLOSED`)
+        }
+      } else {
+        this.failures = 0  // reset on success in CLOSED state
+      }
 
-## Graceful Degradation
+      return result
+    } catch (error) {
+      this.failures++
+      this.lastFailureTime = Date.now()
+
+      if (this.failures >= this.opts.failureThreshold) {
+        this.state = 'OPEN'
+        console.error(
+          `[CircuitBreaker:${this.opts.name}] CLOSED → OPEN after ${this.failures} failures`
+        )
+      }
 
-```typescript
-interface SupabaseFallback {
-  enabled: boolean;
-  data: any;
-  staleness: 'fresh' | 'stale' | 'very_stale';
-}
+      if (fallback) return fallback()
+      throw error
+    }
+  }
 
-async function withSupabaseFallback<T>(
-  fn: () => Promise<T>,
-  fallbackFn: () => Promise<T>
-): Promise<{ data: T; fallback: boolean }> {
-  try {
-    const data = await fn();
-    // Update cache for future fallback
-    await updateFallbackCache(data);
-    return { data, fallback: false };
-  } catch (error) {
-    console.warn('Supabase failed, using fallback:', error.message);
-    const data = await fallbackFn();
-    return { data, fallback: true };
+  get currentState() {
+    return { state: this.state, failures: this.failures }
   }
 }
+
+// One circuit breaker per Supabase service domain
+export const dbCircuit = new CircuitBreaker({
+  name: 'database',
+  failureThreshold: 5,
+  resetTimeoutMs: 30_000,
+  halfOpenSuccesses: 3,
+})
+
+export const authCircuit = new CircuitBreaker({
+  name: 'auth',
+  failureThreshold: 3,
+  resetTimeoutMs: 15_000,
+  halfOpenSuccesses: 2,
+})
+
+export const storageCircuit = new CircuitBreaker({
+  name: 'storage',
+  failureThreshold: 3,
+  resetTimeoutMs: 60_000,
+  halfOpenSuccesses: 2,
+})
 ```
 
-## Dead Letter Queue
+### Retry with Exponential Backoff and Jitter
 
 ```typescript
-interface DeadLetterEntry {
-  id: string;
-  operation: string;
-  payload: any;
-  error: string;
-  attempts: number;
-  lastAttempt: Date;
+// lib/retry.ts
+interface RetryOptions {
+  maxRetries: number
+  baseDelayMs: number
+  maxDelayMs: number
+  retryableErrors?: string[]  // Supabase error codes to retry
 }
 
-class SupabaseDeadLetterQueue {
-  private queue: DeadLetterEntry[] = [];
-
-  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
-    this.queue.push({
-      ...entry,
-      id: uuidv4(),
-      lastAttempt: new Date(),
-    });
-  }
-
-  async processOne(): Promise<boolean> {
-    const entry = this.queue.shift();
-    if (!entry) return false;
-
-    try {
-      await supabaseClient[entry.operation](entry.payload);
-      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
-      return true;
-    } catch (error) {
-      entry.attempts++;
-      entry.lastAttempt = new Date();
+const DEFAULT_RETRYABLE = [
+  'PGRST301',   // connection error
+  '08006',      // connection failure
+  '57014',      // query cancelled (timeout)
+  '40001',      // serialization failure
+  '53300',      // too many connections
+]
+
+export async function withRetry<T>(
+  fn: () => Promise<{ data: T | null; error: any }>,
+  opts: RetryOptions = { maxRetries: 3, baseDelayMs: 200, maxDelayMs: 5000 }
+): Promise<{ data: T | null; error: any }> {
+  const retryable = opts.retryableErrors ?? DEFAULT_RETRYABLE
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    const result = await fn()
+
+    if (!result.error) return result
+
+    // Don't retry non-retryable errors (auth, RLS, validation)
+    const errorCode = result.error.code ?? ''
+    if (!retryable.includes(errorCode) && attempt > 0) {
+      return result
+    }
 
-      if (entry.attempts < 5) {
-        this.queue.push(entry);
-      } else {
-        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
-        await alertOnPermanentFailure(entry);
-      }
-      return false;
+    if (attempt < opts.maxRetries) {
+      // Exponential backoff with full jitter
+      const delay = Math.min(
+        opts.baseDelayMs * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5),
+        opts.maxDelayMs
+      )
+      console.warn(
+        `[Retry] Attempt ${attempt + 1}/${opts.maxRetries} failed (${errorCode}), ` +
+        `retrying in ${Math.round(delay)}ms`
+      )
+      await new Promise(resolve => setTimeout(resolve, delay))
     }
   }
+
+  // Should not reach here, but return last result
+  return fn()
 }
 ```
 
-## Health Check with Degraded State
+### Combining Circuit Breaker + Retry
 
 ```typescript
-type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
-
-async function supabaseHealthCheck(): Promise<{
-  status: HealthStatus;
-  details: Record<string, any>;
-}> {
-  const checks = {
-    api: await checkApiConnectivity(),
-    circuitBreaker: supabaseBreaker.stats(),
-    dlqSize: deadLetterQueue.size(),
-  };
-
-  const status: HealthStatus =
-    !checks.api.connected ? 'unhealthy' :
-    checks.circuitBreaker.state === 'open' ? 'degraded' :
-    checks.dlqSize > 100 ? 'degraded' :
-    'healthy';
-
-  return { status, details: checks };
+// services/todo-service.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '../lib/database.types'
+import { dbCircuit } from '../lib/circuit-breaker'
+import { withRetry } from '../lib/retry'
+
+const supabase = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
+
+export const TodoService = {
+  async list(userId: string) {
+    return dbCircuit.call(
+      // Retry transient errors inside the circuit breaker
+      () => withRetry(() =>
+        supabase
+          .from('todos')
+          .select('id, title, is_complete, created_at')
+          .eq('user_id', userId)
+          .order('created_at', { ascending: false })
+      ),
+      // Fallback when circuit is OPEN: return empty list
+      () => ({ data: [], error: null })
+    )
+  },
+
+  async create(todo: { title: string; user_id: string }) {
+    return dbCircuit.call(
+      () => withRetry(() =>
+        supabase
+          .from('todos')
+          .insert(todo)
+          .select('id, title, is_complete, created_at')
+          .single()
+      )
+      // No fallback for writes — let the error propagate to the offline queue
+    )
+  },
 }
 ```
 
-## Instructions
-
-### Step 1: Implement Circuit Breaker
-Wrap Supabase calls with circuit breaker.
-
-### Step 2: Add Idempotency Keys
-Generate deterministic keys for operations.
-
-### Step 3: Configure Bulkheads
-Separate queues for different priorities.
+## Step 2 — Offline Queue and Graceful Degradation
 
-### Step 4: Set Up Dead Letter Queue
-Handle permanent failures gracefully.
+See [offline queue, graceful degradation, health checks, and dual-write](references/offline-degradation-health-dualwrite.md) for IndexedDB offline queue with auto-flush, cached fallback patterns, health check endpoints monitoring database/auth/storage, dual-write for critical data with Redis backup, and reconciliation jobs.
 
 ## Output
-- Circuit breaker protecting Supabase calls
-- Idempotency preventing duplicates
-- Bulkhead isolation implemented
-- DLQ for failed operations
+
+- Circuit breaker protecting database, auth, and storage calls independently
+- Retry with exponential backoff and jitter for transient Supabase errors
+- Offline queue buffering writes during network outages with auto-flush on reconnect
+- Graceful degradation serving cached or fallback data when Supabase is unavailable
+- Health check endpoint monitoring all three Supabase services
+- Dual-write pattern ensuring critical data survives Supabase outages
+- Reconciliation job detecting and replaying missing records
 
 ## Error Handling
+
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| Circuit stays open | Threshold too low | Adjust error percentage |
-| Duplicate operations | Missing idempotency | Add idempotency key |
-| Queue full | Rate too high | Increase concurrency |
-| DLQ growing | Persistent failures | Investigate root cause |
-
-## Examples
-
-### Quick Circuit Check
-```typescript
-const state = supabaseBreaker.stats().state;
-console.log('Supabase circuit:', state);
-```
+| Circuit stays OPEN indefinitely | Supabase extended outage | Monitor `status.supabase.com`; circuit auto-recovers via HALF_OPEN |
+| Offline queue grows unbounded | User offline for hours | Cap queue at 1000 items; show UI warning at 100 |
+| Stale cache served too long | Cache TTL too generous | Reduce `cacheTtlMs`; show "last updated" timestamp |
+| Dual-write divergence | Network partition | Run reconciliation job every 5 min; alert on divergence count |
+| Health check false positive | Transient network blip | Require 3 consecutive failures before marking unhealthy |
+| Retry storm | All clients retry simultaneously | Jitter prevents thundering herd; circuit breaker stops retries when open |
 
 ## Resources
-- [Circuit Breaker Pattern](https://martinfowler.com/bliki/CircuitBreaker.html)
-- [Opossum Documentation](https://nodeshift.dev/opossum/)
-- [Supabase Reliability Guide](https://supabase.com/docs/reliability)
+
+- [Circuit Breaker Pattern (Martin Fowler)](https://martinfowler.com/bliki/CircuitBreaker.html)
+- [Exponential Backoff (AWS)](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)
+- [Supabase Status Page](https://status.supabase.com)
+- [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+- [Supabase Realtime (connection recovery)](https://supabase.com/docs/guides/realtime)
 
 ## Next Steps
-For policy enforcement, see `supabase-policy-guardrails`.
+
+For organizational governance and policy guardrails, see `supabase-policy-guardrails`.

package/skills/supabase-reliability-patterns/references/circuit-breaker.md

@@ -0,0 +1,36 @@
+# Circuit Breaker
+
+## Circuit Breaker
+
+```typescript
+import CircuitBreaker from 'opossum';
+
+const supabaseBreaker = new CircuitBreaker(
+  async (operation: () => Promise<any>) => operation(),
+  {
+    timeout: 30000,
+    errorThresholdPercentage: 50,
+    resetTimeout: 30000,
+    volumeThreshold: 10,
+  }
+);
+
+// Events
+supabaseBreaker.on('open', () => {
+  console.warn('Supabase circuit OPEN - requests failing fast');
+  alertOps('Supabase circuit breaker opened');
+});
+
+supabaseBreaker.on('halfOpen', () => {
+  console.info('Supabase circuit HALF-OPEN - testing recovery');
+});
+
+supabaseBreaker.on('close', () => {
+  console.info('Supabase circuit CLOSED - normal operation');
+});
+
+// Usage
+async function safeSupabaseCall<T>(fn: () => Promise<T>): Promise<T> {
+  return supabaseBreaker.fire(fn);
+}
+```

package/skills/supabase-reliability-patterns/references/dead-letter-queue.md

@@ -0,0 +1,48 @@
+# Dead Letter Queue
+
+## Dead Letter Queue
+
+```typescript
+interface DeadLetterEntry {
+  id: string;
+  operation: string;
+  payload: any;
+  error: string;
+  attempts: number;
+  lastAttempt: Date;
+}
+
+class SupabaseDeadLetterQueue {
+  private queue: DeadLetterEntry[] = [];
+
+  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
+    this.queue.push({
+      ...entry,
+      id: uuidv4(),
+      lastAttempt: new Date(),
+    });
+  }
+
+  async processOne(): Promise<boolean> {
+    const entry = this.queue.shift();
+    if (!entry) return false;
+
+    try {
+      await supabaseCliententry.operation;
+      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
+      return true;
+    } catch (error) {
+      entry.attempts++;
+      entry.lastAttempt = new Date();
+
+      if (entry.attempts < 5) {
+        this.queue.push(entry);
+      } else {
+        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
+        await alertOnPermanentFailure(entry);
+      }
+      return false;
+    }
+  }
+}
+```

package/skills/supabase-reliability-patterns/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Circuit stays open | Threshold too low | Adjust error percentage |
+| Duplicate operations | Missing idempotency | Add idempotency key |
+| Queue full | Rate too high | Increase concurrency |
+| DLQ growing | Persistent failures | Investigate root cause |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-reliability-patterns/references/examples.md

@@ -0,0 +1,11 @@
+## Examples
+
+### Quick Circuit Check
+
+```typescript
+const state = supabaseBreaker.stats().state;
+console.log('Supabase circuit:', state);
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-reliability-patterns/references/idempotency-keys.md

@@ -0,0 +1,36 @@
+# Idempotency Keys
+
+## Idempotency Keys
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+import crypto from 'crypto';
+
+// Generate deterministic idempotency key from input
+function generateIdempotencyKey(
+  operation: string,
+  params: Record<string, any>
+): string {
+  const data = JSON.stringify({ operation, params });
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+// Or use random key with storage
+class IdempotencyManager {
+  private store: Map<string, { key: string; expiresAt: Date }> = new Map();
+
+  getOrCreate(operationId: string): string {
+    const existing = this.store.get(operationId);
+    if (existing && existing.expiresAt > new Date()) {
+      return existing.key;
+    }
+
+    const key = uuidv4();
+    this.store.set(operationId, {
+      key,
+      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+    });
+    return key;
+  }
+}
+```