New Integration: Supabase

Description

Add Supabase integration to sync project activity, database changes, edge function deployments, and platform events into CORE using the Supabase Management API.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Similar developer platform integration
• integrations/linear/ - Project management integration
• integrations/notion/ - For database/content sync patterns

Required Files Structure

integrations/supabase/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Supabase Management API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Supabase Management API Integration

OAuth Setup

• Use OAuth 2.1 Authorization Code flow (PKCE)
• Authorization URL: https://api.supabase.com/v1/oauth/authorize
• Token URL: https://api.supabase.com/v1/oauth/token
• Required scopes (format: <resource>:<action>):
  • projects:read - Read project details and configuration
  • projects:write - Create and modify projects
  • databases:read - Read database configuration and migrations
  • databases:write - Run migrations, manage database
  • auth:read - Read auth configuration and users
  • auth:write - Manage auth settings
  • storage:read - Read storage buckets and objects
  • storage:write - Manage storage
  • edge_functions:read - Read edge functions
  • edge_functions:write - Deploy edge functions
  • secrets:read - Read project secrets
  • secrets:write - Manage project secrets
  • organizations:read - Read organization details
  • organizations:write - Manage organizations
• Alternative: Personal Access Token (PAT) for automation workflows

Key Endpoints

Base URL: https://api.supabase.com/v1

Projects

• GET /projects - List all projects
• POST /projects - Create a new project
• GET /projects/{ref} - Get project details
• DELETE /projects/{ref} - Delete a project
• GET /projects/{ref}/health - Check project service health
• GET /projects/{ref}/api-keys - Get project API keys
• POST /projects/{ref}/api-keys - Create new API keys

Database

• GET /projects/{ref}/database/migrations - List database migrations
• POST /projects/{ref}/database/migrations - Create a migration (create tables)
• GET /projects/{ref}/database/context - Get database context
• POST /projects/{ref}/database/query - Run a SQL query
• POST /projects/{ref}/branches - Create a development branch
• GET /projects/{ref}/branches - List branches
• DELETE /branches/{branch_id} - Delete a branch

Edge Functions

• GET /projects/{ref}/functions - List edge functions
• POST /projects/{ref}/functions - Create an edge function
• GET /projects/{ref}/functions/{slug} - Get function details
• PATCH /projects/{ref}/functions/{slug} - Update a function
• DELETE /projects/{ref}/functions/{slug} - Delete a function

Auth

• GET /projects/{ref}/config/auth - Get auth configuration
• PATCH /projects/{ref}/config/auth - Update auth configuration

Storage

• GET /projects/{ref}/config/storage - Get storage configuration

Secrets

• GET /projects/{ref}/secrets - List project secrets
• POST /projects/{ref}/secrets - Create secrets
• DELETE /projects/{ref}/secrets - Delete secrets

Organizations

• GET /organizations - List organizations
• GET /organizations/{slug} - Get organization details
• GET /organizations/{slug}/members - List organization members

Billing

• PATCH /projects/{ref}/billing/addons - Upgrade/downgrade compute size

Events to Track

1. Projects

   • Project created / deleted / paused / restored
   • Project health status changes
   • API keys rotated

2. Database

   • Migration created / applied
   • Branch created / merged / deleted
   • Schema changes

3. Edge Functions

   • Function deployed / updated / deleted
   • Function invocation errors

4. Auth

   • Auth configuration changed
   • Auth provider enabled / disabled

5. Storage

   • Storage configuration updated
   • Bucket created / deleted

6. Organization

   • Member added / removed
   • Billing changes

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.1 (PKCE) flow in account-create.ts
• Create Supabase Management API utilities in utils.ts
• Implement sync logic in schedule.ts for projects, functions, and database activity
• Convert Supabase platform events to CORE activity format
• Add polling-based change detection for project health and function deployments
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Supabase Management API uses OAuth 2.1 with PKCE (more secure than standard OAuth 2.0)
• Authentication via Bearer token: Authorization: Bearer <access_token>
• Personal Access Tokens (PATs) are long-lived and useful for CI/CD automation
• Scopes restrict OAuth token access to specific Management API endpoints; all scopes support read and/or write
• OAuth App ID is used for tracking and rate limiting per integration
• Project references (ref) are used as unique identifiers for projects
• Database branching is available for development workflows
• The Management API is separate from the project-level REST/GraphQL APIs (PostgREST, Realtime)
• For real-time database changes within a project, use Supabase Realtime (separate from Management API)
• Consider using supabase-management-js community SDK

Resources

• Supabase Management API Reference
• Build a Supabase OAuth Integration
• OAuth Scopes Documentation
• OAuth 2.1 Server Guide
• Supabase for Platforms
• Management API OpenAPI Spec
• supabase-management-js SDK
• Access Control

Labels

enhancement, good first issue, integration, new-feature, new-integration