@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

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

@@ -1,112 +1,294 @@
 ---
 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:*)
+description: "Upgrade Supabase SDK and CLI versions with breaking-change detection\
+  \ and automated code migration.\nUse when upgrading @supabase/supabase-js (v1\u2192\
+  v2 or minor bumps), migrating auth/realtime/storage\nAPIs, or updating the Supabase\
+  \ CLI. Trigger with phrases like \"upgrade supabase\",\n\"supabase breaking changes\"\
+  , \"migrate supabase v2\", \"update supabase SDK\".\n"
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(pip:*), Bash(supabase:*),
+  Bash(git:*), Grep, Glob
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- migration
+- upgrade
+- sdk
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
-# Supabase Upgrade & Migration
+# Supabase Upgrade Migration
 
 ## Overview
-Guide for upgrading Supabase SDK versions and handling breaking changes.
+
+Upgrade `@supabase/supabase-js` and the Supabase CLI with breaking-change detection, automated code migration, and rollback planning. Covers the v1-to-v2 migration path (auth method renames, `data`/`error` destructuring, realtime API overhaul), minor version bumps, `@supabase/ssr` adoption, and Python SDK upgrades via `pip install --upgrade supabase`.
+
+## Current State
+
+!`npm list @supabase/supabase-js 2>/dev/null | grep supabase || echo 'supabase-js not installed'`
+!`supabase --version 2>/dev/null || echo 'CLI not installed'`
+!`pip show supabase 2>/dev/null | grep Version || echo 'Python SDK not installed'`
 
 ## Prerequisites
-- Current Supabase SDK installed
-- Git for version control
-- Test suite available
-- Staging environment
+
+- `@supabase/supabase-js` or the Python `supabase` package installed in the project
+- Git with a clean working tree (no uncommitted changes)
+- Test suite available for post-upgrade verification
+- Node.js >= 18 (for supabase-js v2) or Python >= 3.8 (for Python SDK)
 
 ## Instructions
 
-### Step 1: Check Current Version
+### Step 1: Audit Versions, Scan Usage, and Review Breaking Changes
+
+Check every installed Supabase package and find all import sites in the codebase.
+
 ```bash
+# Check current SDK version
 npm list @supabase/supabase-js
-npm view @supabase/supabase-js version
+
+# Check CLI version
+supabase --version
+
+# Check Python SDK version
+pip show supabase | grep Version
+
+# Find all JS/TS Supabase imports
+grep -rn "from '@supabase/supabase-js'" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null
+grep -rn "createClient" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null
+
+# Find all Python Supabase imports
+grep -rn "from supabase" --include="*.py" src/ app/ 2>/dev/null
 ```
 
-### Step 2: Review Changelog
-```bash
-open https://github.com/supabase/sdk/releases
+**supabase-js v1 → v2 breaking changes:**
+
+| v1 Pattern | v2 Replacement | Notes |
+|-----------|---------------|-------|
+| `createClient(url, key)` | `createClient(url, key)` | Signature unchanged, but return type differs |
+| `supabase.auth.session()` | `supabase.auth.getSession()` | Sync → async, returns `{ data: { session } }` |
+| `supabase.auth.user()` | `supabase.auth.getUser()` | Sync → async, returns `{ data: { user } }` |
+| `supabase.auth.signIn({ email, password })` | `supabase.auth.signInWithPassword({ email, password })` | Method split by auth type |
+| `supabase.auth.signIn({ provider: 'google' })` | `supabase.auth.signInWithOAuth({ provider: 'google' })` | OAuth separated |
+| `supabase.auth.signIn({ email })` | `supabase.auth.signInWithOtp({ email })` | Magic link separated |
+| `supabase.auth.api.resetPasswordForEmail(e)` | `supabase.auth.resetPasswordForEmail(e)` | `.api` namespace removed |
+| `{ data: subscription }` from `onAuthStateChange` | `{ data: { subscription } }` | Extra destructuring level |
+| `error.message` string parsing | `error.code` enum (`PGRST116`, etc.) | Reliable error matching |
+| `.single()` returns error on 0 rows | `.maybeSingle()` for optional rows | New method for nullable results |
+| `supabase.from('t').on('INSERT', cb).subscribe()` | `supabase.channel('c').on('postgres_changes', ...).subscribe()` | Realtime v2 channel API |
+| `supabase.storage.from('b').download('path')` | Same, but returns `{ data: Blob, error }` | Consistent error/data tuple |
+
+**Realtime v2 migration detail:**
+
+```typescript
+// v1 realtime
+supabase
+  .from('messages')
+  .on('INSERT', (payload) => console.log(payload.new))
+  .subscribe()
+
+// v2 realtime — channel-based API
+supabase
+  .channel('messages-insert')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' },
+    (payload) => console.log(payload.new))
+  .subscribe()
 ```
 
-### Step 3: Create Upgrade Branch
+### Step 2: Run the Upgrade and Apply Code Migrations
+
+Create a branch, install new packages, and transform code to match v2 APIs.
+
 ```bash
-git checkout -b upgrade/supabase-sdk-vX.Y.Z
+# Create upgrade branch
+git checkout -b upgrade-supabase-sdk
+
+# Upgrade JS/TS SDK
 npm install @supabase/supabase-js@latest
-npm test
-```
 
-### Step 4: Handle Breaking Changes
-Update import statements, configuration, and method signatures as needed.
+# Upgrade SSR helper (if used with Next.js/SvelteKit/Nuxt)
+npm install @supabase/ssr@latest
 
-## Output
-- Updated SDK version
-- Fixed breaking changes
-- Passing test suite
-- Documented rollback procedure
+# Upgrade CLI
+npm install -g supabase@latest
 
-## 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 |
+# Upgrade Python SDK
+pip install --upgrade supabase
 
-## Examples
+# Regenerate TypeScript types from linked project
+npx supabase gen types typescript --linked > lib/database.types.ts
+
+# Generate a database migration if schema drifted
+npx supabase db diff --use-migra -f upgrade_check
+```
+
+Apply auth code migrations:
 
-### Import Changes
 ```typescript
-// Before (v1.x)
-import { Client } from '@supabase/supabase-js';
+// BEFORE (v1 auth patterns)
+const session = supabase.auth.session()
+const user = supabase.auth.user()
+const { error } = await supabase.auth.signIn({ email, password })
+const { data: subscription } = supabase.auth.onAuthStateChange(callback)
 
-// After (v2.x)
-import { SupabaseClient } from '@supabase/supabase-js';
+// AFTER (v2 auth patterns)
+const { data: { session } } = await supabase.auth.getSession()
+const { data: { user } } = await supabase.auth.getUser()
+const { error } = await supabase.auth.signInWithPassword({ email, password })
+const { data: { subscription } } = supabase.auth.onAuthStateChange(callback)
 ```
 
-### Configuration Changes
+Apply error handling migration:
+
 ```typescript
-// Before (v1.x)
-const client = new Client({ key: 'xxx' });
+// BEFORE (v1 — string matching)
+if (error.message.includes('not found')) { ... }
 
-// After (v2.x)
-const client = new SupabaseClient({
-  apiKey: 'xxx',
-});
+// AFTER (v2 — structured error codes)
+if (error.code === 'PGRST116') { ... }  // "not found" → PGRST116
 ```
 
-### Rollback Procedure
+### Step 3: Verify, Test, and Prepare Rollback
+
 ```bash
-npm install @supabase/supabase-js@1.x.x --save-exact
+# Type check (catches 90% of migration issues)
+npx tsc --noEmit
+
+# Run test suite
+npm test
+
+# Python tests
+python -m pytest tests/ -v
+
+# Manual smoke test critical auth flows:
+# 1. Sign up → confirm email → sign in with password
+# 2. OAuth sign in → callback handling
+# 3. Password reset → email → reset form
+# 4. Session refresh across page navigations
+# 5. Realtime subscription connect/disconnect
+# 6. Storage upload/download round-trip
+```
+
+**Rollback procedure** (if upgrade causes issues):
+
+```text
+# Option A: Pin to previous version
+npm install @supabase/supabase-js@<previous-version>
+pip install supabase==<previous-version>
+
+# Option B: Revert the branch
+git stash && git checkout main
+```
+
+## Output
+
+- `@supabase/supabase-js` upgraded to latest version with `npm list` confirmation
+- All `supabase.auth.signIn()` calls migrated to `signInWithPassword` / `signInWithOAuth` / `signInWithOtp`
+- Sync auth methods (`session()`, `user()`) replaced with async `getSession()` / `getUser()`
+- Realtime subscriptions migrated from `.on()` to channel-based API
+- `data`/`error` destructuring updated where return shapes changed
+- TypeScript types regenerated from current schema
+- Test suite passing, type checking clean
+- Rollback branch or version pin documented
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Property 'session' does not exist` | v1 sync `.session()` removed in v2 | Replace with `await supabase.auth.getSession()` |
+| `Property 'signIn' does not exist` | `signIn` split into multiple methods in v2 | Use `signInWithPassword`, `signInWithOAuth`, or `signInWithOtp` |
+| `supabase.auth.api` is undefined | `.api` namespace removed in v2 | Call methods directly on `supabase.auth.*` |
+| `TypeError: supabase.from(...).on is not a function` | Realtime API replaced in v2 | Use `supabase.channel().on('postgres_changes', ...)` |
+| Type errors after `gen types` | Database schema changed between versions | Update application code to match new generated types |
+| `PGRST116` error on `.single()` | Zero rows returned (v2 throws) | Use `.maybeSingle()` for optional lookups |
+| `ERR_REQUIRE_ESM` after upgrade | v2 is ESM-only in some bundlers | Update `tsconfig.json` to `"module": "esnext"` or use dynamic `import()` |
+| `AuthSessionMissingError` | `getSession()` called before auth initialized | Wrap in `onAuthStateChange` listener or check `session !== null` |
+
+## Examples
+
+**Full v1 → v2 auth migration (Next.js):**
+
+```typescript
+// lib/supabase.ts — client initialization (unchanged API)
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
+
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+)
 ```
 
-### 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
+// app/login/page.tsx — v2 auth flow
+export async function login(email: string, password: string) {
+  const { data, error } = await supabase.auth.signInWithPassword({
+    email,
+    password,
+  })
+  if (error) {
+    // v2: use error.code instead of parsing error.message
+    if (error.code === 'invalid_credentials') {
+      return { success: false, message: 'Invalid email or password' }
     }
-  });
+    throw error
+  }
+  return { success: true, session: data.session }
+}
+```
+
+```typescript
+// hooks/useAuth.ts — v2 session listener
+import { useEffect, useState } from 'react'
+import { supabase } from '@/lib/supabase'
+import type { Session } from '@supabase/supabase-js'
+
+export function useAuth() {
+  const [session, setSession] = useState<Session | null>(null)
+
+  useEffect(() => {
+    // v2: getSession is async, returns nested { data: { session } }
+    supabase.auth.getSession().then(({ data: { session } }) => {
+      setSession(session)
+    })
+
+    // v2: subscription nested one level deeper
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      (_event, session) => setSession(session)
+    )
+
+    return () => subscription.unsubscribe()
+  }, [])
+
+  return session
 }
+```
 
-// 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
+**Python SDK upgrade:**
+
+```python
+# Before (supabase-py < 2.0)
+from supabase import create_client
+supabase = create_client(url, key)
+data = supabase.table("users").select("*").execute()
+users = data["data"]
+
+# After (supabase-py >= 2.0)
+from supabase import create_client, Client
+supabase: Client = create_client(url, key)
+response = supabase.table("users").select("*").execute()
+users = response.data  # attribute access, not dict
 ```
 
 ## Resources
-- [Supabase Changelog](https://github.com/supabase/sdk/releases)
-- [Supabase Migration Guide](https://supabase.com/docs/migration)
+
+- supabase-js v2 Migration Guide — official step-by-step
+- [supabase-js Releases](https://github.com/supabase/supabase-js/releases) — changelog for every version
+- [Supabase CLI Releases](https://github.com/supabase/cli/releases) — CLI changelog
+- Auth Helpers Migration — `@supabase/auth-helpers` → `@supabase/ssr`
+- [Realtime v2 Guide](https://supabase.com/docs/guides/realtime) — channel-based API reference
+- [supabase-py Releases](https://github.com/supabase-community/supabase-py/releases) — Python SDK changelog
 
 ## Next Steps
-For CI integration during upgrades, see `supabase-ci-integration`.
+
+For CI integration with the upgraded SDK, see `supabase-ci-integration`. For database migration workflows after schema changes, see `supabase-migration-deep-dive`.

package/skills/supabase-upgrade-migration/references/errors.md

@@ -0,0 +1,10 @@
+# Error Handling Reference
+
+| 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 |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-upgrade-migration/references/examples.md

@@ -0,0 +1,51 @@
+## 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
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-upgrade-migration/references/implementation.md

@@ -0,0 +1,29 @@
+## Implementation Guide
+
+### 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.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*