feat!: add supabaseOptions and refactor client creation to options objects

[tomaspozo]

Summary

• Adds supabaseOptions?: SupabaseClientOptions<string> to WithSupabaseConfig, allowing users to customize internal createClient() calls (e.g., db.schema, custom fetch, realtime config)
• Options flow through to both the RLS-scoped client and the admin client
• Security-critical auth settings (persistSession, autoRefreshToken, detectSessionInUrl) and the Authorization header are always force-overwritten

[linear]

FUNC-529 Add support of for supabase client options

We should allow users to customize the way the way the internal clients are initialized:

withSupabase({allow:"always", supabaseOptions: {schema: "api"}})

and we extend the interface like this, and pass down

export interface WithSupabaseConfig {
...
supabaseOptions: SupabaseClientOptions<SchemaName>
}

[Copilot]

Pull request overview

Adds a supabaseOptions escape hatch to customize the internal Supabase client creation while refactoring createContextClient / createAdminClient to accept options objects, and wiring the options through createSupabaseContext / withSupabase.

Changes:

• Add supabaseOptions?: SupabaseClientOptions<string> to WithSupabaseConfig and introduce ClientAuth, CreateContextClientOptions, and CreateAdminClientOptions types.
• Refactor createContextClient / createAdminClient to accept options objects and merge forwarded supabaseOptions.
• Update and extend tests to cover the new options-object APIs and basic supabaseOptions plumbing.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/types.ts	Adds new public config/options types and the supabaseOptions config field.
src/index.ts	Re-exports the newly introduced types from the main entrypoint.
src/create-supabase-context.ts	Threads supabaseOptions into both context and admin client creation via options objects.
src/create-supabase-context.test.ts	Adds a basic test for supabaseOptions plumbing through createSupabaseContext.
src/core/index.ts	Re-exports the new types from the ./core entrypoint.
src/core/create-context-client.ts	Refactors to options object and merges forwarded supabaseOptions into createClient() options.
src/core/create-context-client.test.ts	Updates for options-object signature and adds basic supabaseOptions tests.
src/core/create-admin-client.ts	Refactors to options object and merges forwarded supabaseOptions into createClient() options.
src/core/create-admin-client.test.ts	Updates for options-object signature and adds a basic supabaseOptions test.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kallebysantos]

I believe this ensures TS sync with database main type with the scoped selected schema 🤔

[kallebysantos]

Update: It doesn't sync types

[kallebysantos]

Looks good to me!!
Just not really sure if the final Typescript will scope the selected schema, since its expects narrow types and passing down the SchemaName.

---

Update: Its not scoping to selected schema

Details

Screen.Recording.2026-03-26.at.12.20.41.mov