From 0c27456c862f3e0f8144ff4c158bbacaa5fe005d Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Wed, 12 Aug 2026 10:21:19 -0300 Subject: [PATCH] docs: Update documentation from JS, Dart, and Swift SDK changes (#48723) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Updates docs based on recent SDK changes across three of the six tracked SDKs. `supabase-py`, `supabase-kt`, and `supabase-csharp` were also analyzed this cycle but had no doc-worthy changes (internal bug fixes / dependency bumps only, or no new commits). ## Changes analyzed | SDK | Repo | Commits | Latest tag | |---|---|---|---| | js | https://github.com/supabase/supabase-js | `485695ff7...21e410f56` | v3.0.0-next.29 | | dart | https://github.com/supabase/supabase-flutter | `6979093...5447063` | yet_another_json_isolate-v2.1.1 | | py | https://github.com/supabase/supabase-py | `3c98900...0490201` | v3.0.0a1 | | swift | https://github.com/supabase/supabase-swift | `c24795d...51a083a` | v2.54.1 | | kt | https://github.com/supabase-community/supabase-kt | (no new commits) | 3.7.0 | | csharp | https://github.com/supabase-community/supabase-csharp | `572624e...ac057a2` | v1.5.0 | ## Documentation updates - **`apps/docs/content/guides/auth/sessions/pkce-flow.mdx`** — new "Overlapping flows" section documenting the experimental `appendPkceFlowIdToRedirects` option and `flowId`-aware `exchangeCodeForSession()`, added in supabase-js #2569, which fixes concurrent PKCE flows (e.g. multiple tabs) clobbering each other's stored code verifier. - **`apps/docs/spec/supabase_dart_v2.yml`** — `stream()` entry: documented the new filter methods (`like`, `ilike`, `match`, `imatch`, `isFilter`, `isDistinct`) and multi-filter chaining added in supabase-flutter #1610, plus two behavioral caveats (filter re-evaluation on UPDATE, primary-key-only DELETE payloads) and a new example. - **`apps/docs/spec/supabase_swift_v2.yml`**: - `invoke()` entry: documented the new `timeoutInterval` override on `FunctionInvokeOptions` (supabase-swift #1144), with a new example. - Added missing `generate-link` and `signOut()` (admin) spec entries — supabase-swift #1152 added these methods but Swift had no reference entries for them, even though the shared nav ids already existed in `common-client-libs-sections.json` for other SDKs. ## Test plan - [x] `python3 -c "import yaml; yaml.safe_load(...)"` on both edited YAML spec files — parses cleanly - [x] `npx prettier --check` on all three changed files — passes - [ ] Visual check of rendered reference pages for the new Swift `generate-link` / `signOut` / timeout examples and the Dart `stream()` multi-filter example (docs dev server) --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Summary by CodeRabbit - **Documentation** - Added guidance for experimental overlapping PKCE authentication flows, including separating concurrent flows and exchanging their flow IDs. - Expanded Dart streaming documentation with filter operators, multiple-filter behavior, update semantics, delete payloads, and chained-filter examples. - Added Swift documentation for admin link generation, user sign-out, and configurable Edge Function timeouts. - Documented the default 150-second Edge Function idle timeout and per-invocation timeout overrides. --------- Co-authored-by: Claude Sonnet 5 --- .../guides/auth/sessions/pkce-flow.mdx | 36 +++++++++ apps/docs/spec/supabase_dart_v2.yml | 22 ++++++ apps/docs/spec/supabase_swift_v2.yml | 74 +++++++++++++++++++ 3 files changed, 132 insertions(+) diff --git a/apps/docs/content/guides/auth/sessions/pkce-flow.mdx b/apps/docs/content/guides/auth/sessions/pkce-flow.mdx index 8574485eb87..1f027b53b15 100644 --- a/apps/docs/content/guides/auth/sessions/pkce-flow.mdx +++ b/apps/docs/content/guides/auth/sessions/pkce-flow.mdx @@ -85,6 +85,42 @@ Behind the scenes, the code exchange requires a code verifier. Both the code in The code verifier is created and stored locally when the Auth flow is first initiated. That means the code exchange must be initiated on the same browser and device where the flow was started. +## Overlapping flows + +If more than one PKCE flow is started on the same browser before either one completes (for example, `signInWithOAuth()` called in two tabs), the code verifier stored for the earlier flow is overwritten by the later one, and exchanging the first flow's code fails. + + + +Support for overlapping flows is currently experimental and requires explicit opt-in as the API may change without notice. + + + +To keep each flow's verifier separate, set the `appendPkceFlowIdToRedirects` option when creating the client: + +```js +const supabase = createClient(supabaseUrl, supabaseKey, { + auth: { + experimental: { appendPkceFlowIdToRedirects: true }, + }, +}) +``` + +With this enabled, the client library appends a `sb_flow_id` query parameter to `redirectTo`, so your OAuth callback page can read it back and use it to select the matching verifier. You can also get the flow ID directly from the response of `signInWithOAuth()`: + +```js +const { data, error } = await supabase.auth.signInWithOAuth({ + provider: 'github', +}) + +const flowId = data.flowId +``` + +Pass the flow ID to `exchangeCodeForSession()` to make sure the correct verifier is used, whether you read it from `data.flowId` or from the `sb_flow_id` query parameter in the redirect URL: + +```js +const { data, error } = await supabase.auth.exchangeCodeForSession(authCode, { flowId }) +``` + ## Resources - [OAuth 2.0 guide](https://oauth.net/2/pkce/) to PKCE flow diff --git a/apps/docs/spec/supabase_dart_v2.yml b/apps/docs/spec/supabase_dart_v2.yml index 9b46a812a72..cb46b3999c7 100644 --- a/apps/docs/spec/supabase_dart_v2.yml +++ b/apps/docs/spec/supabase_dart_v2.yml @@ -4600,6 +4600,15 @@ functions: - `.lt('column', value)` listens to rows where the column is less than the value - `.lte('column', value)` listens to rows where the column is less than or equal to the value - `.inFilter('column', [val1, val2, val3])` listens to rows where the column is one of the values + - `.like('column', pattern)` listens to rows where the column matches the given `LIKE` pattern + - `.ilike('column', pattern)` listens to rows where the column matches the given case-insensitive `LIKE` pattern + - `.matchRegex('column', pattern)` listens to rows where the column matches the given PostgreSQL regular expression, case-sensitive + - `.imatchRegex('column', pattern)` listens to rows where the column matches the given PostgreSQL regular expression, case-insensitive + - `.isFilter('column', value)` listens to rows where the column `IS` the given value (e.g. `null`, `true`, `false`) + - `.isDistinct('column', value)` listens to rows where the column `IS DISTINCT FROM` the given value + - Multiple filters can be chained together on the same `stream()` call, and they are combined with `AND` both when fetching the initial data and when filtering realtime changes. + - For `UPDATE` events, a filter such as `.eq()` is only re-evaluated against the new row. If a row stops matching the filter after an update, it is not removed from the stream and will remain in its last known state until it is deleted or the stream is restarted. + - `DELETE` events only include the primary key columns of the deleted row by default, not the full previous row. examples: - id: listen-to-table name: Listen to a table @@ -4632,6 +4641,19 @@ functions: .order('name') .limit(10); ``` + - id: with-multiple-filters + name: With multiple filters + description: | + Multiple filters can be chained together and are combined with `AND`. + code: | + ```dart + supabase.from('countries') + .stream(primaryKey: ['id']) + .eq('continent', 'Asia') + .like('name', '%Republic%') + .order('name') + .limit(10); + ``` - id: using-stream-with-stream-builder name: Using `stream()` with `StreamBuilder` description: | diff --git a/apps/docs/spec/supabase_swift_v2.yml b/apps/docs/spec/supabase_swift_v2.yml index 56e8d168e36..132a3fd12b5 100644 --- a/apps/docs/spec/supabase_swift_v2.yml +++ b/apps/docs/spec/supabase_swift_v2.yml @@ -1757,6 +1757,62 @@ functions: ) ``` + - id: generate-link + title: 'generateLink()' + description: | + Generates an email link for a specific action without sending it. This is useful for custom admin functionality where you want to build the email or OTP flow yourself. + notes: | + - `GenerateLinkParams` exposes a static factory for each link type: `.signUp(email:password:redirectTo:)`, `.invite(email:redirectTo:)`, `.magicLink(email:redirectTo:)`, `.recovery(email:redirectTo:)`, `.emailChangeCurrent(email:newEmail:redirectTo:)`, and `.emailChangeNew(email:newEmail:redirectTo:)`. + - `generateLink()` creates the user for `.signUp` and `.invite` if one doesn't already exist. + examples: + - id: generate-a-signup-link + name: Generate a signup link + isSpotlight: true + code: | + ```swift + let response = try await supabase.auth.admin.generateLink( + params: .signUp( + email: "email@example.com", + password: "secret" + ) + ) + + let actionLink = response.properties.actionLink + ``` + - id: generate-a-recovery-link + name: Generate a recovery link + code: | + ```swift + let response = try await supabase.auth.admin.generateLink( + params: .recovery( + email: "email@example.com", + redirectTo: URL(string: "https://example.com/reset-password") + ) + ) + ``` + + - id: auth-js-gotrueadminapi-signout + title: 'signOut()' + description: | + Signs out a specific user by revoking their session(s), using that user's access token (JWT). + notes: | + - Unlike `supabase.auth.signOut()`, this method takes the target user's access token (JWT), not a user ID. + - By default, `signOut()` uses the `.global` scope, which revokes every session for the user. Pass `.local` to revoke only the session tied to the given JWT, or `.others` to keep that session and revoke all the rest. + examples: + - id: sign-out-a-user + name: Sign out a user + isSpotlight: true + code: | + ```swift + try await supabase.auth.admin.signOut(jwt: jwt) + ``` + - id: sign-out-a-user-with-scope + name: Sign out a user with a scope + code: | + ```swift + try await supabase.auth.admin.signOut(jwt: jwt, scope: .others) + ``` + - id: admin-oauth-list-clients title: 'admin.oauth.listClients()' description: | @@ -4607,6 +4663,7 @@ functions: - Requires an Authorization header. - When you pass in a body to your function, we automatically attach the Content-Type header for `String`, and `Data`. If it doesn't match any of these types we assume the payload is `json`, serialize it and attach the `Content-Type` header as `application/json`. You can override this behaviour by passing in a `Content-Type` header of your own. - When a region is specified, both the `x-region` header and `forceFunctionRegion` query parameter are set to ensure proper function routing. + - By default, function invocations use a 150-second idle timeout. You can override this per-call by passing `timeoutInterval` to `FunctionInvokeOptions`. This only controls the client's request timeout — it cannot extend function execution beyond the platform's [150-second gateway idle timeout](/docs/guides/functions/limits), after which a 504 Gateway Timeout is returned regardless of the value passed. examples: - id: invocation-with-decodable name: Invocation with `Decodable` response @@ -4781,6 +4838,23 @@ functions: ) ) ``` + - id: invocation-with-timeout-override + name: Invocation with a custom timeout + description: | + Override the default 150-second idle timeout for a single invocation by passing `timeoutInterval`. + isSpotlight: true + code: | + ```swift + let response = try await supabase.functions + .invoke( + "hello", + options: FunctionInvokeOptions( + body: ["foo": "bar"], + timeoutInterval: 30 + ) + ) + ``` + - id: subscribe title: on().subscribe() notes: |