@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-incident-runbook/references/examples.md

@@ -0,0 +1,10 @@
+## Examples
+
+### One-Line Health Check
+
+```bash
+curl -sf https://api.yourapp.com/health | jq '.services.supabase.status' || echo "UNHEALTHY"
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-incident-runbook/references/immediate-actions-by-error-type.md

@@ -0,0 +1,41 @@
+# Immediate Actions By Error Type
+
+## Immediate Actions by Error Type
+
+### 401/403 - Authentication
+
+```bash
+# Verify API key is set
+kubectl get secret supabase-secrets -o jsonpath='{.data.api-key}' | base64 -d
+
+# Check if key was rotated
+# → Verify in Supabase dashboard
+
+# Remediation: Update secret and restart pods
+kubectl create secret generic supabase-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
+kubectl rollout restart deployment/supabase-integration
+```
+
+### 429 - Rate Limited
+
+```bash
+# Check rate limit headers
+curl -v https://api.supabase.com 2>&1 | grep -i rate
+
+# Enable request queuing
+kubectl set env deployment/supabase-integration RATE_LIMIT_MODE=queue
+
+# Long-term: Contact Supabase for limit increase
+```
+
+### 500/503 - Supabase Errors
+
+```bash
+# Enable graceful degradation
+kubectl set env deployment/supabase-integration SUPABASE_FALLBACK=true
+
+# Notify users of degraded service
+# Update status page
+
+# Monitor Supabase status for resolution
+```

package/skills/supabase-install-auth/SKILL.md

@@ -1,90 +1,226 @@
 ---
 name: supabase-install-auth
-description: |
-  Install and configure Supabase SDK/CLI authentication.
-  Use when setting up a new Supabase integration, configuring API keys,
-  or initializing Supabase in your project.
-  Trigger with phrases like "install supabase", "setup supabase",
-  "supabase auth", "configure supabase API key".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
+description: 'Install and configure Supabase SDK, CLI, and project authentication.
+
+  Use when setting up a new Supabase project, installing @supabase/supabase-js,
+
+  configuring environment variables, or initializing the Supabase client.
+
+  Trigger with "install supabase", "setup supabase", "supabase auth config",
+
+  "configure supabase", "supabase init", "add supabase to project".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(pip:*),
+  Bash(supabase:*), Grep, Glob
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- setup
+- authentication
+- sdk
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Supabase Install & Auth
 
 ## Overview
-Set up Supabase SDK/CLI and configure authentication credentials.
+
+Install the Supabase SDK, CLI, and project credentials from scratch — covering package install, environment configuration, client initialization, and connection verification for both TypeScript (`@supabase/supabase-js`) and Python (`supabase`).
+
+**Key facts:**
+
+- **npm package:** `@supabase/supabase-js`
+- **Python package:** `supabase` (via pip)
+- **Client factory:** `createClient()` — never `new SupabaseClient()`
+- **Dashboard:** https://supabase.com/dashboard (Settings > API for keys)
+- **Docs:** https://supabase.com/docs
 
 ## Prerequisites
-- Node.js 18+ or Python 3.10+
-- Package manager (npm, pnpm, or pip)
-- Supabase account with API access
-- API key from Supabase dashboard
+
+- Node.js 18+ (for JS/TS) or Python 3.8+ (for Python)
+- Package manager: npm, pnpm, or yarn (JS) / pip (Python)
+- A Supabase project created at https://supabase.com/dashboard
+- Docker Desktop (only if using local development via `supabase start`)
 
 ## Instructions
 
-### Step 1: Install SDK
+### Step 1 — Install the SDK and CLI
+
+Install the SDK and the Supabase CLI:
+
+**JavaScript / TypeScript:**
+
 ```bash
-# Node.js
+# Install the SDK
 npm install @supabase/supabase-js
 
-# Python
+# For SSR frameworks (Next.js, SvelteKit, Nuxt), also install:
+npm install @supabase/ssr
+
+# Install the Supabase CLI (for types, migrations, local dev)
+npm install -D supabase
+```
+
+**Python:**
+
+```bash
+# Install the SDK
 pip install supabase
+
+# Install the CLI (alternative: brew install supabase/tap/supabase)
+npm install -g supabase
 ```
 
-### Step 2: Configure Authentication
+Verify the CLI is available:
+
 ```bash
-# Set environment variable
-export SUPABASE_API_KEY="your-api-key"
+npx supabase --version
+```
 
-# Or create .env file
-echo 'SUPABASE_API_KEY=your-api-key' >> .env
+### Step 2 — Configure Environment Variables
+
+Retrieve project credentials from the Supabase Dashboard (Settings > API) and create the env file:
+
+```bash
+# .env.local (or .env)
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...          # anon key — safe for client-side
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1...  # admin key — server-side ONLY
 ```
 
-### Step 3: Verify Connection
-```typescript
-const result = await supabase.from('_test').select('*').limit(1); console.log(result.error ? 'Failed' : 'OK');
+Add env files to `.gitignore` immediately:
+
+```
+.env
+.env.local
+.env.*.local
 ```
 
-## Output
-- Installed SDK package in node_modules or site-packages
-- Environment variable or .env file with API key
-- Successful connection verification output
+**Security rules:**
 
-## Error Handling
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Invalid API Key | Incorrect or expired key | Verify key in Supabase dashboard |
-| Rate Limited | Exceeded quota | Check quota at https://supabase.com/docs |
-| Network Error | Firewall blocking | Ensure outbound HTTPS allowed |
-| Module Not Found | Installation failed | Run `npm install` or `pip install` again |
+- The **anon key** (`SUPABASE_KEY`) is safe for client-side code. It respects Row Level Security (RLS) policies.
+- The **service role key** (`SUPABASE_SERVICE_ROLE_KEY`) bypasses RLS entirely. Use only on the server. Never bundle into client code or expose in browser.
 
-## Examples
+### Step 3 — Initialize the Client and Verify
+
+Create a client singleton and verify connectivity:
+
+**TypeScript — client-side (anon key):**
 
-### TypeScript Setup
 ```typescript
-import { SupabaseClient } from '@supabase/supabase-js';
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_KEY!
+)
 
-const client = new SupabaseClient({
-  apiKey: process.env.SUPABASE_API_KEY,
-});
+export default supabase
 ```
 
-### Python Setup
-```python
-from supabase import SupabaseClient
+**TypeScript — server-side (service role key):**
 
-client = SupabaseClient(
-    api_key=os.environ.get('SUPABASE_API_KEY')
+```typescript
+// lib/supabase-admin.ts
+import { createClient } from '@supabase/supabase-js'
+
+export const supabaseAdmin = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  {
+    auth: {
+      autoRefreshToken: false,
+      persistSession: false,
+    },
+  }
 )
 ```
 
+**Python — client initialization:**
+
+```python
+# lib/supabase_client.py
+import os
+from supabase import create_client
+
+url = os.environ["SUPABASE_URL"]
+key = os.environ["SUPABASE_KEY"]
+
+supabase = create_client(url, key)
+```
+
+**Verify the connection:**
+
+```typescript
+// Quick connectivity check
+const { data, error } = await supabase.from('_health_check').select('*').limit(1)
+if (error && error.code !== 'PGRST116') {
+  // PGRST116 = relation does not exist (expected if table doesn't exist yet)
+  throw new Error(`Supabase connection failed: ${error.message}`)
+}
+console.log('Supabase connected successfully')
+```
+
+**Optional — generate TypeScript types from the database schema:**
+
+```text
+npx supabase login
+npx supabase link --project-ref <your-project-ref>
+npx supabase gen types typescript --linked > lib/database.types.ts
+```
+
+Then add the type parameter to the client:
+
+```typescript
+import type { Database } from './database.types'
+const supabase = createClient<Database>(url, key)
+```
+
+## Output
+
+Completing all three steps produces:
+
+- `@supabase/supabase-js` or `supabase` Python package installed
+- Supabase CLI available via `npx supabase`
+- `.env.local` containing `SUPABASE_URL`, `SUPABASE_KEY`, and `SUPABASE_SERVICE_ROLE_KEY`
+- Client singleton module (`lib/supabase.ts` or `lib/supabase_client.py`)
+- Server-side admin client (`lib/supabase-admin.ts`, TypeScript only)
+- Verified connectivity to the Supabase project
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `FetchError: request failed` | Wrong `SUPABASE_URL` | Verify URL at Dashboard > Settings > API |
+| `Invalid API key` | Wrong or expired key | Copy fresh anon key from Dashboard > Settings > API |
+| `PGRST301: JWSError` | Malformed JWT in key | Remove trailing whitespace/newlines from env var |
+| `Cannot find module '@supabase/supabase-js'` | SDK not installed | Run `npm install @supabase/supabase-js` |
+| `ModuleNotFoundError: No module named 'supabase'` | Python SDK not installed | Run `pip install supabase` |
+| `supabase: command not found` | CLI not installed | Run `npm install -D supabase`, then use `npx supabase` |
+| `Error: supabase start` fails | Docker not running | Start Docker Desktop, then retry `npx supabase start` |
+| `TypeError: SupabaseClient is not a constructor` | Wrong import pattern | Use `createClient()` — not `new SupabaseClient()` |
+
+## Examples
+
+Full TypeScript and Python examples with auth sign-up, sign-in, session management, SSR patterns, and type-safe queries: [examples](references/examples.md)
+
 ## Resources
-- [Supabase Documentation](https://supabase.com/docs)
-- [Supabase Dashboard](https://api.supabase.com)
-- [Supabase Status](https://status.supabase.com)
+
+- [Supabase JS Client Reference](https://supabase.com/docs/reference/javascript/initializing) — `createClient` options, auth, database, storage, realtime
+- [Supabase Python Client Reference](https://supabase.com/docs/reference/python/initializing) — Python SDK setup and usage
+- [Supabase CLI Reference](https://supabase.com/docs/reference/cli/introduction) — local dev, migrations, type generation
+- [Supabase Auth Guide](https://supabase.com/docs/guides/auth) — email/password, OAuth, magic links, RLS
+- [Generating TypeScript Types](https://supabase.com/docs/guides/api/rest/generating-types) — type-safe database queries
+- [Supabase Dashboard](https://supabase.com/dashboard) — project settings, API keys, database editor
 
 ## Next Steps
-After successful auth, proceed to `supabase-hello-world` for your first API call.
+
+After successful setup, continue with:
+
+- **supabase-hello-world** — run your first database query
+- **supabase-rls-policies** — secure your tables with Row Level Security
+- **supabase-email-auth** — set up email/password authentication flows

package/skills/supabase-install-auth/references/examples.md

@@ -0,0 +1,102 @@
+# Supabase Install & Auth — Examples
+
+## TypeScript — Full setup with auth
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_KEY!
+)
+
+// Sign up a new user
+const { data: signUp, error: signUpError } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password-123',
+})
+
+// Sign in an existing user
+const { data: signIn, error: signInError } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password-123',
+})
+
+// Get the current session
+const { data: { session } } = await supabase.auth.getSession()
+console.log('Logged in as:', session?.user.email)
+
+// Sign out
+await supabase.auth.signOut()
+```
+
+## Python — Full setup with auth
+
+```python
+import os
+from supabase import create_client
+
+url = os.environ["SUPABASE_URL"]
+key = os.environ["SUPABASE_KEY"]
+supabase = create_client(url, key)
+
+# Sign up a new user
+result = supabase.auth.sign_up({
+    "email": "user@example.com",
+    "password": "secure-password-123",
+})
+
+# Sign in an existing user
+result = supabase.auth.sign_in_with_password({
+    "email": "user@example.com",
+    "password": "secure-password-123",
+})
+
+# Get the current session
+session = supabase.auth.get_session()
+print(f"Logged in as: {session.user.email}")
+
+# Sign out
+supabase.auth.sign_out()
+```
+
+## TypeScript — SSR with Next.js App Router
+
+```typescript
+// app/lib/supabase-server.ts
+import { createClient } from '@supabase/supabase-js'
+import { cookies } from 'next/headers'
+
+export function createServerClient() {
+  const cookieStore = cookies()
+  return createClient(
+    process.env.SUPABASE_URL!,
+    process.env.SUPABASE_KEY!,
+    {
+      auth: {
+        persistSession: false,
+      },
+    }
+  )
+}
+```
+
+## TypeScript — Type-safe client with generated types
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
+
+const supabase = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_KEY!
+)
+
+// Fully typed query — IDE autocomplete for table and column names
+const { data: users, error } = await supabase
+  .from('profiles')
+  .select('id, username, avatar_url')
+  .eq('is_active', true)
+  .order('created_at', { ascending: false })
+  .limit(10)
+```