feat: supabase SDK Integration Proposal

[calvinbrewer]

Current Challenges

PostREST and Composite Types

The current implementation faces several challenges when working with Supabase and encrypted data:

1. Complex String Formatting: Users need to manually format encrypted payloads with multiple levels of JSON stringification:

   const searchTerm = `(${JSON.stringify(JSON.stringify(searchResult.data))})`
   // or even triple stringification in some cases
   const searchTerm = `${JSON.stringify(`(${JSON.stringify(JSON.stringify(searchResult.data))})`)}`

2. Type Safety: The current approach lacks proper TypeScript type safety for encrypted fields.

3. Error-Prone: The manual string formatting is error-prone and can lead to subtle bugs.

4. Limited Query Support: Some advanced query patterns are difficult to implement with the current approach.

Proposed Solution: @cipherstash/supabase Package

Overview

Create a dedicated @cipherstash/supabase package that provides a clean, type-safe interface for working with encrypted data in Supabase.

Key Features

1. Type-Safe Query Builder

2. Automatic Payload Formatting

   • Handle all JSON stringification internally
   • Support for all Supabase query methods (eq, like, ilike, in, etc.)

3. Enhanced TypeScript Support

4. Query Helpers

Implementation Plan

1. Phase 1: Core Integration

   • Basic query builder with support for common operations
   • Type definitions and basic error handling

2. Phase 2: Advanced Features

   • Support for complex queries and joins
   • Performance optimizations
   • Caching layer for encrypted fields

3. Phase 3: Developer Experience

   • Comprehensive documentation
   • Example applications
   • Migration guide from current approach

Benefits

1. Improved Developer Experience

   • No more manual string formatting
   • Better IDE support with TypeScript
   • Clearer error messages

2. Reduced Errors

   • Type checking for encrypted fields
   • Consistent handling of encrypted data

3. Better Performance

   • Optimized query building
   • Potential for caching encrypted fields

Questions to Consider

• Should we support both the current approach and the new package during migration?
• How should we handle versioning with Supabase SDK updates?
• What level of backward compatibility should we maintain?

Next Steps

1. Gather community feedback on the proposal
2. Create a detailed technical specification
3. Begin implementation of Phase 1
4. Create example applications and documentation

[calvinbrewer]

Resolved in #143 and #137