From 901d1915b6f915ee5e7f804975aa8e09bbd8ce99 Mon Sep 17 00:00:00 2001
From: Ben Fritsch
Date: Mon, 5 Oct 2026 14:32:29 +0200
Subject: [PATCH 03/41] add Ben Fritsch to humans.txt (#51265)
Adding myself to humans.txt
---
apps/docs/public/humans.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/apps/docs/public/humans.txt b/apps/docs/public/humans.txt
index 8544ba1ef78..0ce95cc5169 100644
--- a/apps/docs/public/humans.txt
+++ b/apps/docs/public/humans.txt
@@ -38,6 +38,7 @@ Artyom Borissov
Aziz Quadri
Barco Fourie
Barry Roodt
+Ben Fritsch
Beng Eu
Benjamin Coenen
Beth Long
From 04a6baf86933bd000cc7a2d8919cf669ccccaf66 Mon Sep 17 00:00:00 2001
From: Kody Jackson
Date: Mon, 5 Oct 2026 07:43:35 -0500
Subject: [PATCH 04/41] fix(kb) - add topic name (#51186)
## Problem
Adds a new topic b/c `Comparisons` is reserved for other types of
content.
## Preview links
TBD
## Summary by CodeRabbit
* **New Features**
* Made the Comparison topic visible and added a hidden Rundowns topic
covering comparisons across technologies and facets.
---
apps/kb/src/lib/topics.ts | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/apps/kb/src/lib/topics.ts b/apps/kb/src/lib/topics.ts
index 572a3800b3f..828fd6682e2 100644
--- a/apps/kb/src/lib/topics.ts
+++ b/apps/kb/src/lib/topics.ts
@@ -21,6 +21,12 @@ export const TOPICS = [
name: 'Comparison',
description: 'How Supabase compares to other databases and platforms.',
pinned: false,
+ visible: true,
+ },
+ {
+ name: 'Rundowns',
+ description: 'How different technologies compare across a variety of facets.',
+ pinned: false,
visible: false,
},
{
From 77e3b4382f6214da734068080d663dd0c6d28fd7 Mon Sep 17 00:00:00 2001
From: Tanun Turbo Chalermsinsuwan
Date: Mon, 5 Oct 2026 19:54:55 +0700
Subject: [PATCH 05/41] feat(role): Allow eligible organizations to invite
users as 'No-access' base role (#50922)
## Problem
As the API has allow inviting users into `None / No-access` role for
team, enterprise, and platform tier organization, we need to update the
documentation and descriptions for this new role on the invitation form.
## Solution
1. Updated `apps/docs/content/guides/platform/access-control.mdx` to
include the role
2. Added the role description on
`apps/studio/components/interfaces/Organization/TeamSettings/Roles.constants.tsx`
3. Add the roles into the proper sorting order at
`apps/studio/data/organization-members/organization-roles-query.ts`
4. Add logic to invitation components to disable the role when inviting
user into project(s), as the backend does not allow it.
## Testing and verification steps
The UI:
https://studio-staging-aa8is1m07-supabase.vercel.app/dashboard/org
Documentation:
https://docs-kht98bi78-supabase.vercel.app/docs/guides/platform/access-control
## Checklist
Check all before review:
- [x] I have read
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
- [x] If I wrote a new docs topic or edited an existing topic, I used
the `/write-the-docs` or `/edit-the-docs` skill, which references
[WORD_LIST](https://github.com/supabase/supabase/blob/master/apps/docs/WORD_LIST.md)
and the docs
[CONTRIBUTING](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md)
guide
## Summary by CodeRabbit
## Summary
* **Updates**
* The **None** role is labeled **No-access** and describes the lack of
organization and project resource access.
* **None** is included after **Read-only** in the role list. When
inviting a member with project-only access, **None** is disabled with an
explanation.
* **Documentation**
* Clarified plan coverage for **Read-Only** and **No access**, and added
guidance on assigning **No access** at the organization level before
granting project-specific roles.
---
.../content/guides/platform/access-control.mdx | 5 ++++-
.../TeamSettings/InviteMemberButton.tsx | 16 ++++++++++++----
.../TeamSettings/Roles.constants.tsx | 1 +
.../UpdateRolesPanel/UpdateRolesPanel.tsx | 15 +++++++++++----
.../organization-roles-query.ts | 13 +++++++++++--
5 files changed, 39 insertions(+), 11 deletions(-)
diff --git a/apps/docs/content/guides/platform/access-control.mdx b/apps/docs/content/guides/platform/access-control.mdx
index 73bea005159..36717e0e9e8 100644
--- a/apps/docs/content/guides/platform/access-control.mdx
+++ b/apps/docs/content/guides/platform/access-control.mdx
@@ -11,10 +11,11 @@ For each organization and project, a member can have one of the following roles:
- **Administrator**: full access to everything in organization and project resources **except** updating organization settings, transferring projects outside of the organization, and adding new owners.
- **Developer**: read-only access to organization resources and content access to project resources but cannot change any project settings.
- **Read-Only**: read-only access to organization and project resources.
+- **No-access**: no access to any organization or project resources by default. Use this for members who should only see the specific projects they're granted a [project-scoped role](#organization-scoped-roles-vs-project-scoped-roles) on.
-Read-Only role is only available on the [Team and Enterprise plans](/pricing).
+Read-Only and No-access roles are only available on the [Team and Enterprise plans](/pricing).
@@ -67,6 +68,8 @@ Each member in the organization can be assigned a role that is scoped either to
This allows for more granular control, ensuring that users only have visibility and access to the projects relevant to their role.
+To default a member to zero project access and grant access on a per-project basis, assign them the organization-level **No access** role, then grant project-scoped roles for the specific projects they need. The **No-access** role is omitted from the permission tables below since it has none of the listed permissions by default.
+
### Organization permissions across roles
The table below shows the actions each role can take on the resources belonging to the organization.
diff --git a/apps/studio/components/interfaces/Organization/TeamSettings/InviteMemberButton.tsx b/apps/studio/components/interfaces/Organization/TeamSettings/InviteMemberButton.tsx
index 516b9ed8a26..c9976e5bed0 100644
--- a/apps/studio/components/interfaces/Organization/TeamSettings/InviteMemberButton.tsx
+++ b/apps/studio/components/interfaces/Organization/TeamSettings/InviteMemberButton.tsx
@@ -358,12 +358,20 @@ export const InviteMemberButton = () => {
const canAssignRole = rolesAddable.includes(role.id)
const isOwnerRole = role.name === 'Owner'
const disabledForStripe = isStripeProjectsOrg && isOwnerRole
- const disabled = !canAssignRole || disabledForStripe
+
+ const isNoAccessRole = role.name === 'No-access'
+ const isApplyingProjectRole = !applyToOrg
+ const disabledForProjectRole = isApplyingProjectRole && isNoAccessRole
+
+ const disabled =
+ !canAssignRole || disabledForStripe || disabledForProjectRole
const disabledReason = disabledForStripe
? 'Cannot be assigned in Stripe Projects organizations'
- : !canAssignRole
- ? 'Additional permissions required to assign role'
- : undefined
+ : disabledForProjectRole
+ ? 'Cannot assign No-access role to project-scoped members'
+ : !canAssignRole
+ ? 'Additional permissions required to assign role'
+ : undefined
return (
diff --git a/apps/studio/components/interfaces/Organization/TeamSettings/Roles.constants.tsx b/apps/studio/components/interfaces/Organization/TeamSettings/Roles.constants.tsx
index a3759ad9ca9..30b7ec2d957 100644
--- a/apps/studio/components/interfaces/Organization/TeamSettings/Roles.constants.tsx
+++ b/apps/studio/components/interfaces/Organization/TeamSettings/Roles.constants.tsx
@@ -17,4 +17,5 @@ export const ROLE_DESCRIPTIONS: Record = {
'Manage project content, including deleting data, users, files, and Edge Functions. Cannot change settings or delete projects.',
'Read-only':
'View resources without modifying or deleting them. SQL Editor access is limited to SELECT queries.',
+ 'No-access': 'No access to any organization or project resources',
}
diff --git a/apps/studio/components/interfaces/Organization/TeamSettings/UpdateRolesPanel/UpdateRolesPanel.tsx b/apps/studio/components/interfaces/Organization/TeamSettings/UpdateRolesPanel/UpdateRolesPanel.tsx
index c4470ea1bac..b57a713e1c7 100644
--- a/apps/studio/components/interfaces/Organization/TeamSettings/UpdateRolesPanel/UpdateRolesPanel.tsx
+++ b/apps/studio/components/interfaces/Organization/TeamSettings/UpdateRolesPanel/UpdateRolesPanel.tsx
@@ -282,12 +282,19 @@ export const UpdateRolesPanel = ({ visible, member, onClose }: UpdateRolesPanelP
const canAssignRole = rolesAddable.includes(role.id)
const isOwnerRole = role.name === 'Owner'
const disabledForStripe = isStripeProjectsOrg && isOwnerRole
- const disabled = !canAssignRole || disabledForStripe
+
+ const isNoAccessRole = role.name === 'No-access'
+ const disabledForProjectRole =
+ !isApplyingRoleToAllProjects && isNoAccessRole
+ const disabled =
+ !canAssignRole || disabledForStripe || disabledForProjectRole
const disabledReason = disabledForStripe
? 'Cannot be assigned in Stripe Projects organizations'
- : !canAssignRole
- ? 'Additional permissions required to assign role'
- : undefined
+ : disabledForProjectRole
+ ? 'Cannot assign No-access role to project-scoped members'
+ : !canAssignRole
+ ? 'Additional permissions required to assign role'
+ : undefined
return (
(
.sort((a, b) => {
return FIXED_ROLE_ORDER.indexOf(a.name) - FIXED_ROLE_ORDER.indexOf(b.name)
})
- .filter((role) => FIXED_ROLE_ORDER.includes(role.name)),
+ .filter((role) => FIXED_ROLE_ORDER.includes(role.name))
+ .map((role) => ({ ...role, name: getOverrideRoleName(role.name) })),
} as TData
},
...options,
})
+
+const OVERRIDE_ROLE_NAMES: Record = {
+ None: 'No-access',
+}
+
+export function getOverrideRoleName(rolename: string) {
+ return OVERRIDE_ROLE_NAMES[rolename] ?? rolename
+}
From 0d8b1417bcc37ae8b1c880f4306b6c9749cef16e Mon Sep 17 00:00:00 2001
From: "supabase-supabase-autofixer[bot]"
<248690971+supabase-supabase-autofixer[bot]@users.noreply.github.com>
Date: Mon, 5 Oct 2026 13:16:39 +0000
Subject: [PATCH 06/41] [bot] Decrease ESLint ratchet baselines (#51225)
Automated weekly decrease of ESLint ratchet baselines.
Co-authored-by: github-actions[bot]
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
---
apps/studio/.github/eslint-rule-baselines.json | 12 ++++--------
1 file changed, 4 insertions(+), 8 deletions(-)
diff --git a/apps/studio/.github/eslint-rule-baselines.json b/apps/studio/.github/eslint-rule-baselines.json
index 745b53c2792..4fdc6d40801 100644
--- a/apps/studio/.github/eslint-rule-baselines.json
+++ b/apps/studio/.github/eslint-rule-baselines.json
@@ -6,15 +6,15 @@
"@typescript-eslint/no-explicit-any": 799,
"no-restricted-exports": 176,
"react/no-unstable-nested-components": 34,
- "jsx-a11y/control-has-associated-label": 178,
+ "jsx-a11y/control-has-associated-label": 174,
"jsx-a11y/label-has-associated-control": 33,
"jsx-a11y/no-redundant-roles": 2,
"jsx-a11y/anchor-is-valid": 6,
"jsx-a11y/heading-has-content": 2,
"valtio/state-snapshot-rule": 1,
- "shadcn/no-arbitrary-values": 199,
- "shadcn/no-unknown-classes": 151,
- "shadcn/no-raw-colors": 64
+ "shadcn/no-arbitrary-values": 212,
+ "shadcn/no-unknown-classes": 150,
+ "shadcn/no-raw-colors": 63
},
"ruleFiles": {
"react-hooks/exhaustive-deps": {
@@ -857,9 +857,7 @@
"components/interfaces/Database/Policies/PolicyEditorPanel/PolicyDetailsV2.tsx": 1,
"components/interfaces/Database/Privileges/PrivilegesTable.tsx": 1,
"components/interfaces/Database/Publications/PublicationSkeleton.tsx": 1,
- "components/interfaces/Database/Replication/DestinationPanel/DestinationForm/AnalyticsBucket/Fields.tsx": 2,
"components/interfaces/Database/Replication/DestinationPanel/DestinationForm/BigQuery/Fields.tsx": 1,
- "components/interfaces/Database/Replication/DestinationPanel/DestinationForm/DuckLake/Fields.tsx": 2,
"components/interfaces/Database/Roles/CreateRolePanel.tsx": 2,
"components/interfaces/Database/Roles/RoleRow.tsx": 1,
"components/interfaces/Functions/EdgeFunctionDetails/EdgeFunctionDetails.tsx": 1,
@@ -1128,7 +1126,6 @@
"components/interfaces/Auth/Users/UsersGridComponents.tsx": 3,
"components/interfaces/Billing/Payment/AddNewPaymentMethodModal.tsx": 1,
"components/interfaces/BranchManagement/ConnectToGitHub.tsx": 1,
- "components/interfaces/ConnectSheet/content/steps/direct-connection/IPv4StatusPanel.tsx": 1,
"components/interfaces/Database/EnumeratedTypes/CreateEnumeratedTypeSidePanel.tsx": 1,
"components/interfaces/Database/EnumeratedTypes/EditEnumeratedTypeSidePanel.tsx": 1,
"components/interfaces/Database/Functions/FunctionsList/FunctionList.tsx": 1,
@@ -1217,7 +1214,6 @@
"components/interfaces/BranchManagement/BranchPanels.tsx": 1,
"components/interfaces/BranchManagement/CreateBranchModal.tsx": 6,
"components/interfaces/BranchManagement/DeleteBranchModal.tsx": 1,
- "components/interfaces/ConnectSheet/content/steps/direct-connection/IPv4StatusPanel.tsx": 1,
"components/interfaces/Database/Functions/FunctionsList/FunctionsList.tsx": 2,
"components/interfaces/Database/Hooks/DeleteHookModal.tsx": 2,
"components/interfaces/Database/Migrations/Migrations.tsx": 1,
From de41b029ef89bea2b8839e2f690e87c274fc29c7 Mon Sep 17 00:00:00 2001
From: Charis <26616127+charislam@users.noreply.github.com>
Date: Mon, 5 Oct 2026 09:18:24 -0400
Subject: [PATCH 07/41] always use canonical link for new status page (#51264)
---
apps/studio/components/layouts/AppLayout/useStatusBanner.ts | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/apps/studio/components/layouts/AppLayout/useStatusBanner.ts b/apps/studio/components/layouts/AppLayout/useStatusBanner.ts
index 85797ea0bf0..74fb1d90e37 100644
--- a/apps/studio/components/layouts/AppLayout/useStatusBanner.ts
+++ b/apps/studio/components/layouts/AppLayout/useStatusBanner.ts
@@ -61,5 +61,5 @@ export function useStatusBanner(): StatusBannerState {
)
}
- return { type: 'shown', selection, pageUrl: data?.pageUrl ?? DEFAULT_STATUS_PAGE_URL, onDismiss }
+ return { type: 'shown', selection, pageUrl: DEFAULT_STATUS_PAGE_URL, onDismiss }
}
From 0c2257fb3d6d8aa684bb2d0150efa7f4b8d73985 Mon Sep 17 00:00:00 2001
From: "kemal.earth" <606977+kemaldotearth@users.noreply.github.com>
Date: Mon, 5 Oct 2026 14:20:21 +0100
Subject: [PATCH 08/41] feat(studio): scoped oauth data layer (#49476)
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
~~This is the first part (and ultimately the final part of the stacked
PR). PR 1 introduces mock data for us while we build the requirements of
the scoped oauth interstitial, all following PR's will be stacked on top
of this one.~~
This is the first part, the data layer side. We began with mock data,
but as backend support arrived we've used this PR to help us shape the
UI as well as the frontend data layer. This now acts as the frontend
data layer.
## Summary by CodeRabbit
* **New Features**
* Added OAuth app authorization request handling.
* Added visibility into application details, requested scopes, and
existing authorizations.
* Added organization and project selection during authorization.
* Added organization roles and project access details.
* Added approval and denial options with secure redirect handling.
* Added validation for required authorization details and project
selections.
* Added support for role validation feedback during approval.
* Added representative authorization scenarios for approved, denied, and
re-consent flows.
---------
Co-authored-by: Claude Sonnet 5
Co-authored-by: Gildas Garcia <1122076+djhi@users.noreply.github.com>
Co-authored-by: Samir Ketema <6003000+samirketema@users.noreply.github.com>
---
apps/studio/data/oauth-apps/keys.ts | 25 +
apps/studio/data/oauth-apps/mocks.ts | 622 ++++++++++++++++++
.../oauth-apps/oauth-apps-approvals-query.ts | 40 ++
.../oauth-apps-authorize-approve-mutation.ts | 56 ++
.../oauth-apps-authorize-deny-mutation.ts | 47 ++
.../oauth-apps-authorize-mutations.test.ts | 82 +++
...s-authorize-organization-projects-query.ts | 53 ++
...auth-apps-authorize-organizations-query.ts | 49 ++
.../oauth-apps-authorize-request-query.ts | 42 ++
.../oauth-apps/oauth-apps-grants-query.ts | 37 ++
.../oauth-apps-member-grants-query.ts | 43 ++
.../oauth-apps-org-app-details-query.ts | 41 ++
.../oauth-apps-preflight-validation-query.ts | 47 ++
.../oauth-apps-revoke-grant-mutation.ts | 48 ++
.../oauth-apps/oauth-apps-revoke-mutation.ts | 57 ++
apps/studio/data/oauth-apps/types.test.ts | 142 ++++
apps/studio/data/oauth-apps/types.ts | 190 ++++++
knip.jsonc | 7 +
18 files changed, 1628 insertions(+)
create mode 100644 apps/studio/data/oauth-apps/keys.ts
create mode 100644 apps/studio/data/oauth-apps/mocks.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-approvals-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-approve-mutation.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-deny-mutation.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-mutations.test.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-organization-projects-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-organizations-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-authorize-request-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-grants-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-member-grants-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-org-app-details-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-preflight-validation-query.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-revoke-grant-mutation.ts
create mode 100644 apps/studio/data/oauth-apps/oauth-apps-revoke-mutation.ts
create mode 100644 apps/studio/data/oauth-apps/types.test.ts
create mode 100644 apps/studio/data/oauth-apps/types.ts
diff --git a/apps/studio/data/oauth-apps/keys.ts b/apps/studio/data/oauth-apps/keys.ts
new file mode 100644
index 00000000000..7fa7cd3de54
--- /dev/null
+++ b/apps/studio/data/oauth-apps/keys.ts
@@ -0,0 +1,25 @@
+export const oauthAppsKeys = {
+ authorizeRequest: (id: string | undefined) => ['oauth-apps', 'authorize', id] as const,
+ authorizeOrganizations: (id: string | undefined) =>
+ ['oauth-apps', 'authorize', id, 'organizations'] as const,
+ authorizeOrganizationProjects: (id: string | undefined, slug: string | undefined) =>
+ ['oauth-apps', 'authorize', id, 'organizations', slug, 'projects'] as const,
+ orgAppDetails: (slug: string | undefined, appId: string | undefined) =>
+ ['oauth-apps', 'organizations', slug, 'apps', appId, 'grant'] as const,
+ preflightValidation: (slug: string | undefined, appId: string | undefined) =>
+ ['oauth-apps', 'organizations', slug, 'apps', appId, 'preflight-validation'] as const,
+ // cursor omitted (rather than passed as `undefined`) so the cursor-less key is a true prefix
+ // of every paginated key — invalidating without a cursor clears every cached page.
+ approvals: (slug: string | undefined, cursor?: string) =>
+ cursor === undefined
+ ? (['oauth-apps', 'approvals', slug] as const)
+ : (['oauth-apps', 'approvals', slug, cursor] as const),
+ appMemberGrants: (slug: string | undefined, appId: string | undefined, cursor?: string) =>
+ cursor === undefined
+ ? (['oauth-apps', 'authorized', slug, appId, 'member-grants'] as const)
+ : (['oauth-apps', 'authorized', slug, appId, 'member-grants', cursor] as const),
+ grants: (cursor?: string) =>
+ cursor === undefined
+ ? (['oauth-apps', 'grants'] as const)
+ : (['oauth-apps', 'grants', cursor] as const),
+}
diff --git a/apps/studio/data/oauth-apps/mocks.ts b/apps/studio/data/oauth-apps/mocks.ts
new file mode 100644
index 00000000000..d809a743c30
--- /dev/null
+++ b/apps/studio/data/oauth-apps/mocks.ts
@@ -0,0 +1,622 @@
+import dayjs from 'dayjs'
+
+import type { OAuthAppsAuthorizeIdentity } from './oauth-apps-authorize-organizations-query'
+import type {
+ ListOAuthApprovalsResponse,
+ ListOrgAppGrantsResponse,
+ ListOwnGrantsResponse,
+ OAuthAppsAuthorizeApproveResult,
+ OAuthAppsAuthorizeOrganizationProject,
+ OAuthAppsAuthorizePreflightResult,
+ OAuthAppsAuthorizeRequest,
+ OAuthExistingGrant,
+ OAuthOrganizationRole,
+ OAuthOrgAppDetails,
+ OAuthScope,
+} from './types'
+import { isPreflightValidationFailure, isWriteScope } from './types'
+import type { OrganizationRole } from '@/data/organization-members/organization-roles-query'
+
+const ENABLE_MOCKS = true
+export const USE_MOCKS = ENABLE_MOCKS && process.env.NEXT_PUBLIC_ENVIRONMENT !== 'prod'
+
+export const OAUTH_APPS_MOCK_SCENARIOS = {
+ vercelDeveloper: 'mock-vercel-developer',
+ vercelReadOnly: 'mock-vercel-readonly',
+ vercelReconsent: 'mock-vercel-reconsent',
+ vercelOrgAdmin: 'mock-vercel-org-admin',
+ vercelManyProjects: 'mock-vercel-many-projects',
+ vercelRoleValidation: 'mock-vercel-role-validation',
+ vercelOptionalProjects: 'mock-vercel-optional-projects',
+ vercelAllProjects: 'mock-vercel-all-projects',
+ vercelReconsentAllProjects: 'mock-vercel-reconsent-all-projects',
+ kemalBot: 'mock-kemal-bot',
+ kemalBotOrgWide: 'mock-kemal-bot-org-wide',
+ dynamicMcpClient: 'mock-dynamic-mcp-client',
+} as const
+
+export const OWNER_ROLE: OrganizationRole = {
+ id: 1,
+ base_role_id: 1,
+ name: 'Owner',
+ description: null,
+ projects: [],
+}
+
+export const ADMINISTRATOR_ROLE: OrganizationRole = {
+ id: 2,
+ base_role_id: 2,
+ name: 'Administrator',
+ description: null,
+ projects: [],
+}
+
+export const DEVELOPER_ROLE: OrganizationRole = {
+ id: 3,
+ base_role_id: 3,
+ name: 'Developer',
+ description: null,
+ projects: [],
+}
+
+export const READ_ONLY_ROLE: OrganizationRole = {
+ id: 4,
+ base_role_id: 4,
+ name: 'Read-only',
+ description: null,
+ projects: [],
+}
+
+const VERCEL_SCOPES: OAuthScope[] = [
+ 'database:read',
+ 'database:write',
+ 'environment:read',
+ 'environment:write',
+ 'secrets:read',
+ 'secrets:write',
+ 'projects:read',
+ 'edge_functions:read',
+ 'storage:read',
+]
+
+const VERCEL_REQUEST: OAuthAppsAuthorizeRequest = {
+ app_id: 'vercel',
+ app_name: 'Vercel',
+ name: 'Vercel',
+ website: 'https://vercel.com',
+ domain: 'vercel.com',
+ redirect_uri: 'https://vercel.com/api/integrations/supabase/callback',
+ registration_type: 'manual',
+ expires_at: dayjs().add(1, 'month').toISOString(),
+ grant_kind: 'member_bound',
+ project_scoping_mode: true,
+ scopes: VERCEL_SCOPES,
+}
+
+const VERCEL_OPTIONAL_PROJECTS_REQUEST: OAuthAppsAuthorizeRequest = {
+ ...VERCEL_REQUEST,
+ app_id: 'vercel-optional',
+ project_scoping_mode: true,
+}
+
+const VERCEL_ALL_PROJECTS_REQUEST: OAuthAppsAuthorizeRequest = {
+ ...VERCEL_REQUEST,
+ app_id: 'vercel-org-wide',
+ project_scoping_mode: false,
+}
+
+const DYNAMIC_MCP_CLIENT_REQUEST: OAuthAppsAuthorizeRequest = {
+ ...VERCEL_REQUEST,
+ app_id: 'dynamic-mcp-client',
+ app_name: 'Northwind MCP',
+ name: 'Northwind MCP',
+ website: 'https://mcp.northwind.example',
+ domain: 'mcp.northwind.example',
+ redirect_uri: 'https://mcp.northwind.example/callback',
+ registration_type: 'dynamic',
+ // DCR (MCP) oauth apps are forced org-bound, unscoped.
+ grant_kind: 'organization_bound',
+ project_scoping_mode: false,
+}
+
+const KEMAL_BOT_REQUEST: OAuthAppsAuthorizeRequest = {
+ app_id: 'kemal-bot',
+ app_name: 'kemal-bot',
+ name: 'kemal-bot',
+ website: 'https://kemal.lol',
+ domain: 'kemal.lol',
+ redirect_uri: 'https://kemal.lol/hollerback',
+ registration_type: 'manual',
+ expires_at: dayjs().add(1, 'month').toISOString(),
+ grant_kind: 'organization_bound',
+ project_scoping_mode: true,
+ scopes: ['projects:read'],
+}
+
+const KEMAL_BOT_ORG_WIDE_REQUEST: OAuthAppsAuthorizeRequest = {
+ ...KEMAL_BOT_REQUEST,
+ app_id: 'kemal-bot-org-wide',
+ project_scoping_mode: false,
+}
+
+const MOCK_AUTHORIZE_REQUESTS: Record = {
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelDeveloper]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReadOnly]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReconsent]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelOrgAdmin]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelManyProjects]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelRoleValidation]: VERCEL_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelOptionalProjects]: VERCEL_OPTIONAL_PROJECTS_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelAllProjects]: VERCEL_ALL_PROJECTS_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReconsentAllProjects]: VERCEL_OPTIONAL_PROJECTS_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.kemalBot]: KEMAL_BOT_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.kemalBotOrgWide]: KEMAL_BOT_ORG_WIDE_REQUEST,
+ [OAUTH_APPS_MOCK_SCENARIOS.dynamicMcpClient]: DYNAMIC_MCP_CLIENT_REQUEST,
+}
+
+const NORTHWIND_TRADERS_DEVELOPER: OAuthOrganizationRole = {
+ slug: 'northwind-traders',
+ name: 'Northwind Traders',
+ default_role: DEVELOPER_ROLE,
+}
+
+const NORTHWIND_TRADERS_READ_ONLY: OAuthOrganizationRole = {
+ ...NORTHWIND_TRADERS_DEVELOPER,
+ default_role: READ_ONLY_ROLE,
+}
+
+const CONTOSO_LABS: OAuthOrganizationRole = {
+ slug: 'contoso-labs',
+ name: 'Contoso Labs',
+ default_role: OWNER_ROLE,
+}
+
+const TAILSPIN_TOYS_ADMIN: OAuthOrganizationRole = {
+ slug: 'tailspin-toys',
+ name: 'Tailspin Toys',
+ default_role: ADMINISTRATOR_ROLE,
+}
+
+const FABRIKAM_OWNER: OAuthOrganizationRole = {
+ slug: 'fabrikam-industries',
+ name: 'Fabrikam Industries',
+ default_role: OWNER_ROLE,
+}
+
+const WINGTIP_TOYS_DEVELOPER: OAuthOrganizationRole = {
+ slug: 'wingtip-toys',
+ name: 'Wingtip Toys',
+ default_role: DEVELOPER_ROLE,
+}
+
+const LITWARE_DEVELOPER: OAuthOrganizationRole = {
+ slug: 'litware-inc',
+ name: 'Litware Inc.',
+ default_role: DEVELOPER_ROLE,
+}
+
+const MOCK_IDENTITIES: Record = {
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelDeveloper]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, CONTOSO_LABS],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReadOnly]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_READ_ONLY, CONTOSO_LABS],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReconsent]: {
+ email: 'admin@example.com',
+ organizations: [TAILSPIN_TOYS_ADMIN, NORTHWIND_TRADERS_DEVELOPER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelOrgAdmin]: {
+ email: 'admin@example.com',
+ organizations: [TAILSPIN_TOYS_ADMIN, FABRIKAM_OWNER, NORTHWIND_TRADERS_DEVELOPER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelManyProjects]: {
+ email: 'admin@example.com',
+ organizations: [WINGTIP_TOYS_DEVELOPER, NORTHWIND_TRADERS_DEVELOPER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelRoleValidation]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, CONTOSO_LABS],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelOptionalProjects]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, CONTOSO_LABS],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelAllProjects]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_READ_ONLY, CONTOSO_LABS, FABRIKAM_OWNER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.vercelReconsentAllProjects]: {
+ email: 'admin@example.com',
+ organizations: [TAILSPIN_TOYS_ADMIN, NORTHWIND_TRADERS_DEVELOPER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.kemalBot]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, CONTOSO_LABS],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.kemalBotOrgWide]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, FABRIKAM_OWNER],
+ },
+ [OAUTH_APPS_MOCK_SCENARIOS.dynamicMcpClient]: {
+ email: 'admin@example.com',
+ organizations: [NORTHWIND_TRADERS_DEVELOPER, CONTOSO_LABS],
+ },
+}
+
+const MOCK_ORGANIZATION_PROJECTS: Record = {
+ 'northwind-traders': [
+ { ref: 'northwindstorefront1', name: 'northwind-storefront', role: ADMINISTRATOR_ROLE },
+ { ref: 'northwindcms1', name: 'northwind-cms', role: DEVELOPER_ROLE },
+ { ref: 'fabrikamapi1', name: 'fabrikam-api', role: READ_ONLY_ROLE },
+ { ref: 'fabrikamjobs1', name: 'fabrikam-jobs', role: READ_ONLY_ROLE },
+ ],
+ 'wingtip-toys': [
+ { ref: 'wingtipweb1', name: 'wingtip-web', role: ADMINISTRATOR_ROLE },
+ { ref: 'wingtipapi1', name: 'wingtip-api', role: DEVELOPER_ROLE },
+ { ref: 'wingtipadmin1', name: 'wingtip-admin', role: DEVELOPER_ROLE },
+ { ref: 'wingtipjobs1', name: 'wingtip-jobs', role: DEVELOPER_ROLE },
+ { ref: 'wingtipsearch1', name: 'wingtip-search', role: READ_ONLY_ROLE },
+ { ref: 'wingtipbilling1', name: 'wingtip-billing', role: ADMINISTRATOR_ROLE },
+ { ref: 'wingtipmail1', name: 'wingtip-mail', role: DEVELOPER_ROLE },
+ { ref: 'wingtipmedia1', name: 'wingtip-media', role: DEVELOPER_ROLE },
+ { ref: 'wingtipmetrics1', name: 'wingtip-metrics', role: READ_ONLY_ROLE },
+ { ref: 'wingtipstaging1', name: 'wingtip-staging', role: DEVELOPER_ROLE },
+ { ref: 'wingtippreview1', name: 'wingtip-preview', role: DEVELOPER_ROLE },
+ { ref: 'wingtipsandbox1', name: 'wingtip-sandbox', role: READ_ONLY_ROLE },
+ ],
+ 'fabrikam-industries': [
+ { ref: 'fabrikamledger1', name: 'fabrikam-ledger', role: ADMINISTRATOR_ROLE },
+ ],
+ 'tailspin-toys': [
+ { ref: 'tailspinshop1', name: 'tailspin-shop', role: ADMINISTRATOR_ROLE },
+ { ref: 'tailspinwarehouse1', name: 'tailspin-warehouse', role: DEVELOPER_ROLE },
+ ],
+ 'litware-inc': [{ ref: 'litwarecrm1', name: 'litware-crm', role: DEVELOPER_ROLE }],
+ 'contoso-labs': [],
+}
+
+const TAILSPIN_VERCEL_EXISTING_GRANT: OAuthExistingGrant = {
+ approved_scopes: ['database:read', 'database:write', 'projects:read'],
+ project_refs: ['tailspinshop1', 'tailspindeleted1'],
+ approved_at: '2026-08-14T09:12:00.000Z',
+}
+
+const TAILSPIN_VERCEL_OPTIONAL_EXISTING_GRANT: OAuthExistingGrant = {
+ approved_scopes: ['database:read', 'projects:read'],
+ project_refs: [],
+ approved_at: '2026-08-29T16:40:00.000Z',
+}
+
+const DEFAULT_ORG_APP_DETAILS: OAuthOrgAppDetails = {
+ existing_grant: null,
+}
+
+const MOCK_ORG_APP_DETAILS: Record> = {
+ 'tailspin-toys': {
+ vercel: { existing_grant: TAILSPIN_VERCEL_EXISTING_GRANT },
+ 'vercel-optional': { existing_grant: TAILSPIN_VERCEL_OPTIONAL_EXISTING_GRANT },
+ },
+}
+
+// Real oauth_apps config, keyed by app_id — preflight-validation is org+app scoped, not tied to
+// an in-flight authorization request.
+const MOCK_APPS_BY_ID: Record = {
+ vercel: VERCEL_REQUEST,
+ 'vercel-optional': VERCEL_OPTIONAL_PROJECTS_REQUEST,
+ 'vercel-org-wide': VERCEL_ALL_PROJECTS_REQUEST,
+ 'dynamic-mcp-client': DYNAMIC_MCP_CLIENT_REQUEST,
+ 'kemal-bot': KEMAL_BOT_REQUEST,
+ 'kemal-bot-org-wide': KEMAL_BOT_ORG_WIDE_REQUEST,
+}
+
+// The current member's org-level role, keyed by org slug — same reasoning as MOCK_APPS_BY_ID.
+const MOCK_ORGANIZATIONS_BY_SLUG: Record = {
+ 'northwind-traders': NORTHWIND_TRADERS_READ_ONLY,
+ 'tailspin-toys': TAILSPIN_TOYS_ADMIN,
+ 'fabrikam-industries': FABRIKAM_OWNER,
+ 'contoso-labs': CONTOSO_LABS,
+ 'wingtip-toys': WINGTIP_TOYS_DEVELOPER,
+ 'litware-inc': LITWARE_DEVELOPER,
+}
+
+const MOCK_APPROVALS: ListOAuthApprovalsResponse = {
+ data: [
+ {
+ app: {
+ id: 'vercel',
+ name: 'Vercel',
+ icon: null,
+ created_by: '',
+ },
+ grant_target: 'members',
+ org_grant: null,
+ },
+ {
+ app: {
+ id: 'dynamic-mcp-client',
+ name: 'Northwind MCP',
+ icon: null,
+ created_by: '',
+ },
+ grant_target: 'members',
+ org_grant: null,
+ },
+ {
+ app: {
+ id: 'contoso-analytics',
+ name: 'Contoso Analytics',
+ icon: null,
+ created_by: '',
+ },
+ grant_target: 'organization',
+ org_grant: {
+ grant_id: 'grant-contoso-analytics-org',
+ approved_scopes: ['analytics:read', 'projects:read'],
+ approved_at: '2025-11-03T14:20:00.000Z',
+ },
+ },
+ ],
+ pagination: { next_cursor: null },
+}
+
+const MOCK_APP_GRANTS: Record = {
+ vercel: {
+ data: [
+ {
+ grant_id: 'grant-vercel-admin',
+ kind: 'member_bound',
+ user: {
+ gotrue_id: 'b1d3e2f4-0000-4000-8000-000000000001',
+ email: 'admin@example.com',
+ },
+ projects: [
+ { ref: 'northwindstorefront1', name: 'northwind-storefront' },
+ { ref: 'northwindcms1', name: 'northwind-cms' },
+ ],
+ approved_scopes: ['database:read', 'database:write', 'projects:read'],
+ approved_at: '2026-08-18T09:12:00.000Z',
+ },
+ {
+ grant_id: 'grant-vercel-developer',
+ kind: 'member_bound',
+ user: {
+ gotrue_id: 'b1d3e2f4-0000-4000-8000-000000000002',
+ email: 'developer@example.com',
+ avatar_url: 'https://avatars.example/developer.png',
+ },
+ projects: [{ ref: 'northwindcms1', name: 'northwind-cms' }],
+ approved_scopes: ['projects:read'],
+ approved_at: '2026-08-16T11:30:00.000Z',
+ },
+ ],
+ pagination: { next_cursor: null },
+ },
+ 'dynamic-mcp-client': {
+ data: [
+ {
+ grant_id: 'grant-northwind-mcp-ops',
+ kind: 'member_bound',
+ user: {
+ gotrue_id: 'b1d3e2f4-0000-4000-8000-000000000003',
+ email: 'ops@example.com',
+ },
+ projects: [{ ref: 'northwindstorefront1', name: 'northwind-storefront' }],
+ approved_scopes: ['database:read', 'database:write'],
+ approved_at: '2026-09-01T08:45:00.000Z',
+ },
+ ],
+ pagination: { next_cursor: null },
+ },
+ 'contoso-analytics': {
+ data: [
+ {
+ grant_id: 'grant-contoso-analytics-org',
+ kind: 'organization_bound',
+ user: null,
+ projects: null,
+ approved_scopes: ['analytics:read', 'projects:read'],
+ approved_at: '2025-11-03T14:20:00.000Z',
+ },
+ ],
+ pagination: { next_cursor: null },
+ },
+}
+
+const MOCK_OWN_GRANTS: ListOwnGrantsResponse = {
+ data: [
+ {
+ grant_id: 'grant-vercel-admin',
+ app: { id: 'vercel', name: 'Vercel', icon: null },
+ organization: { slug: 'northwind-traders', name: 'Northwind Traders' },
+ projects: [
+ { ref: 'northwindstorefront1', name: 'northwind-storefront' },
+ { ref: 'northwindcms1', name: 'northwind-cms' },
+ ],
+ approved_scopes: ['database:read', 'database:write', 'projects:read'],
+ approved_at: '2026-08-18T09:12:00.000Z',
+ },
+ {
+ grant_id: 'grant-northwind-mcp-ops',
+ app: { id: 'dynamic-mcp-client', name: 'Northwind MCP', icon: null },
+ organization: { slug: 'northwind-traders', name: 'Northwind Traders' },
+ projects: [{ ref: 'northwindstorefront1', name: 'northwind-storefront' }],
+ approved_scopes: ['database:read', 'database:write'],
+ approved_at: '2026-09-01T08:45:00.000Z',
+ },
+ {
+ grant_id: 'kemal-bot-all-projects',
+ app: { id: 'kemal-bot', name: 'kemal-bot', icon: null },
+ organization: { slug: 'northwind-traders', name: 'Northwind Traders' },
+ // Targets all projects
+ projects: null,
+ approved_scopes: ['database:read', 'database:write'],
+ approved_at: '2026-09-20T14:30:00.000Z',
+ },
+ ],
+ pagination: { next_cursor: null },
+}
+
+// Fixture lists are small and static — cursor is accepted for real-endpoint parity but not
+// used to actually paginate the mock data.
+export function getMockOAuthApprovals(_cursor?: string): ListOAuthApprovalsResponse {
+ return MOCK_APPROVALS
+}
+
+export function getMockOAuthAppGrants(appId: string, _cursor?: string): ListOrgAppGrantsResponse {
+ return MOCK_APP_GRANTS[appId] ?? { data: [], pagination: { next_cursor: null } }
+}
+
+export function getMockOAuthOwnGrants(_cursor?: string): ListOwnGrantsResponse {
+ return MOCK_OWN_GRANTS
+}
+
+export function getMockOAuthAppsAuthorizeRequest(authId: string): OAuthAppsAuthorizeRequest {
+ const request = MOCK_AUTHORIZE_REQUESTS[authId]
+ if (!request) throw new Error(`No mock authorize request for id "${authId}"`)
+ return request
+}
+
+export function getMockOAuthAppsAuthorizeIdentity(authId: string): OAuthAppsAuthorizeIdentity {
+ const identity = MOCK_IDENTITIES[authId]
+ if (!identity) throw new Error(`No mock identity for id "${authId}"`)
+ return identity
+}
+
+export function getMockOAuthAppsAuthorizeOrganizationProjects(
+ slug: string
+): OAuthAppsAuthorizeOrganizationProject[] {
+ return MOCK_ORGANIZATION_PROJECTS[slug] ?? []
+}
+
+export function getMockOAuthOrgAppDetails(slug: string, appId: string): OAuthOrgAppDetails {
+ return MOCK_ORG_APP_DETAILS[slug]?.[appId] ?? DEFAULT_ORG_APP_DETAILS
+}
+
+function findMockOrganization(authId: string, slug: string): OAuthOrganizationRole | undefined {
+ return getMockOAuthAppsAuthorizeIdentity(authId).organizations.find(
+ (candidate) => candidate.slug === slug
+ )
+}
+
+const MOCK_OAUTH_STATE = 'mock_state_9f2c1b'
+
+function buildMockRedirectUrl(redirectUri: string, params: Record) {
+ const url = new URL(redirectUri)
+ Object.entries(params).forEach(([key, value]) => url.searchParams.set(key, value))
+ return url.toString()
+}
+
+export function getMockOAuthAppsAuthorizeRedirect(
+ authId: string,
+ { approved }: { approved: boolean }
+) {
+ const request = getMockOAuthAppsAuthorizeRequest(authId)
+ const url = approved
+ ? buildMockRedirectUrl(request.redirect_uri, {
+ code: 'mock_authorization_code',
+ state: MOCK_OAUTH_STATE,
+ })
+ : buildMockRedirectUrl(request.redirect_uri, {
+ error: 'access_denied',
+ error_description: 'The user denied the authorization request',
+ state: MOCK_OAUTH_STATE,
+ })
+
+ return { url }
+}
+
+const ROLE_VALIDATED_SCENARIOS = new Set([
+ OAUTH_APPS_MOCK_SCENARIOS.vercelRoleValidation,
+ OAUTH_APPS_MOCK_SCENARIOS.vercelAllProjects,
+ OAUTH_APPS_MOCK_SCENARIOS.kemalBotOrgWide,
+])
+
+function isReadOnlyRole(role: OrganizationRole) {
+ return role.id === READ_ONLY_ROLE.id
+}
+
+function isOwnerOrAdmin(role: OrganizationRole) {
+ return role.id === OWNER_ROLE.id || role.id === ADMINISTRATOR_ROLE.id
+}
+
+// Upfront org-level check shared by preflight-validation and the "all projects" branch of approve.
+// Never checks project-scoped roles (that's approve's job once project_refs are known).
+function evaluateGrantEligibility(
+ request: OAuthAppsAuthorizeRequest,
+ organization: OAuthOrganizationRole
+): OAuthAppsAuthorizePreflightResult {
+ if (request.grant_kind === 'organization_bound') {
+ if (isOwnerOrAdmin(organization.default_role)) return { ok: true }
+ return {
+ error_code: 'role_validation_failed',
+ message: `Your ${organization.default_role.name} role cannot install this app for the organization.`,
+ validation: { scope_target: 'organization', role: organization.default_role },
+ }
+ }
+
+ const failedScopes = request.scopes.filter(isWriteScope)
+ if (failedScopes.length === 0 || !isReadOnlyRole(organization.default_role)) return { ok: true }
+
+ return {
+ error_code: 'role_validation_failed',
+ message: `Your ${organization.default_role.name} role cannot satisfy this app's scopes for all projects.`,
+ validation: {
+ scope_target: 'all_projects',
+ role: organization.default_role,
+ failed_scopes: failedScopes,
+ },
+ }
+}
+
+export function getMockOAuthAppsPreflightValidation(
+ slug: string,
+ appId: string
+): OAuthAppsAuthorizePreflightResult {
+ const request = MOCK_APPS_BY_ID[appId]
+ const organization = MOCK_ORGANIZATIONS_BY_SLUG[slug]
+ if (!request || !organization) return { ok: true }
+
+ return evaluateGrantEligibility(request, organization)
+}
+
+export function getMockOAuthAppsAuthorizeApproveResult(
+ authId: string,
+ { slug, projectRefs }: { slug: string; projectRefs: string[] | undefined }
+): OAuthAppsAuthorizeApproveResult {
+ const approved = getMockOAuthAppsAuthorizeRedirect(authId, { approved: true })
+ if (!ROLE_VALIDATED_SCENARIOS.has(authId)) return approved
+
+ const request = getMockOAuthAppsAuthorizeRequest(authId)
+ const organization = findMockOrganization(authId, slug)
+ if (!organization) return approved
+
+ if (projectRefs === undefined || request.grant_kind === 'organization_bound') {
+ const result = evaluateGrantEligibility(request, organization)
+ return isPreflightValidationFailure(result) ? result : approved
+ }
+
+ const failedScopes = request.scopes.filter(isWriteScope)
+ if (failedScopes.length === 0) return approved
+
+ const blocked = getMockOAuthAppsAuthorizeOrganizationProjects(slug).filter(
+ (project) => projectRefs.includes(project.ref) && isReadOnlyRole(project.role)
+ )
+ if (blocked.length === 0) return approved
+
+ return {
+ error_code: 'role_validation_failed',
+ message: `Your role is read-only on ${blocked.length} of the selected projects.`,
+ validation: {
+ scope_target: 'projects',
+ failures: blocked.map(({ name, ref, role }) => ({
+ ref,
+ name,
+ role,
+ failed_scopes: failedScopes,
+ })),
+ },
+ }
+}
diff --git a/apps/studio/data/oauth-apps/oauth-apps-approvals-query.ts b/apps/studio/data/oauth-apps/oauth-apps-approvals-query.ts
new file mode 100644
index 00000000000..f440618196b
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-approvals-query.ts
@@ -0,0 +1,40 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthApprovals, USE_MOCKS } from './mocks'
+import type { ListOAuthApprovalsResponse } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthApprovalsVariables = {
+ slug?: string
+ cursor?: string
+}
+
+export type { ListOAuthApprovalsResponse, OAuthApprovalItem } from './types'
+
+export async function getOAuthApprovals({
+ slug,
+ cursor,
+}: OAuthApprovalsVariables): Promise {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!USE_MOCKS) throw new Error('OAuth app approvals are not yet implemented')
+
+ return getMockOAuthApprovals(cursor)
+}
+
+export type OAuthApprovalsData = Awaited>
+export type OAuthApprovalsError = ResponseError
+
+export const useOAuthApprovalsQuery = (
+ { slug, cursor }: OAuthApprovalsVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.approvals(slug, cursor),
+ queryFn: () => getOAuthApprovals({ slug, cursor }),
+ enabled: enabled && USE_MOCKS && Boolean(slug),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-approve-mutation.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-approve-mutation.ts
new file mode 100644
index 00000000000..d3da65fb547
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-approve-mutation.ts
@@ -0,0 +1,56 @@
+import { useMutation } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+import { getMockOAuthAppsAuthorizeApproveResult, USE_MOCKS } from './mocks'
+import type { OAuthAppsAuthorizeApproveResult, OAuthAuthorizeApproveRequest } from './types'
+import type { ResponseError, UseCustomMutationOptions } from '@/types'
+
+export type OAuthAppsAuthorizeApproveVariables = {
+ slug: string
+ auth_id: string
+ body: OAuthAuthorizeApproveRequest
+}
+
+export type OAuthAppsAuthorizeApproveResponse = OAuthAppsAuthorizeApproveResult
+
+export async function approveOAuthAppsAuthorize({
+ slug,
+ auth_id,
+ body,
+}: OAuthAppsAuthorizeApproveVariables): Promise {
+ if (!auth_id) throw new Error('Authorization request id is required')
+ if (!slug) throw new Error('Organization slug is required')
+ if (!USE_MOCKS) throw new Error('OAuth app authorization approval is not yet implemented')
+
+ return getMockOAuthAppsAuthorizeApproveResult(auth_id, { slug, projectRefs: body.project_refs })
+}
+
+type OAuthAppsAuthorizeApproveData = Awaited>
+
+export const useOAuthAppsAuthorizeApproveMutation = ({
+ onError,
+ ...options
+}: Omit<
+ UseCustomMutationOptions<
+ OAuthAppsAuthorizeApproveData,
+ ResponseError,
+ OAuthAppsAuthorizeApproveVariables
+ >,
+ 'mutationFn'
+> = {}) => {
+ return useMutation<
+ OAuthAppsAuthorizeApproveData,
+ ResponseError,
+ OAuthAppsAuthorizeApproveVariables
+ >({
+ mutationFn: (vars) => approveOAuthAppsAuthorize(vars),
+ async onError(data, variables, context) {
+ if (onError === undefined) {
+ toast.error(`Failed to authorize access to OAuth app: ${data.message}`)
+ } else {
+ onError(data, variables, context)
+ }
+ },
+ ...options,
+ })
+}
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-deny-mutation.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-deny-mutation.ts
new file mode 100644
index 00000000000..e54431cd965
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-deny-mutation.ts
@@ -0,0 +1,47 @@
+import { useMutation } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+import { getMockOAuthAppsAuthorizeRedirect, USE_MOCKS } from './mocks'
+import type { OAuthAppsAuthorizeRedirect } from './types'
+import type { ResponseError, UseCustomMutationOptions } from '@/types'
+
+export type OAuthAppsAuthorizeDenyVariables = {
+ slug: string
+ auth_id: string
+}
+
+export type OAuthAppsAuthorizeDenyResponse = OAuthAppsAuthorizeRedirect
+
+export async function denyOAuthAppsAuthorize({ slug, auth_id }: OAuthAppsAuthorizeDenyVariables) {
+ if (!auth_id) throw new Error('Authorization request id is required')
+ if (!slug) throw new Error('Organization slug is required')
+ if (!USE_MOCKS) throw new Error('OAuth app authorization denial is not yet implemented')
+
+ return getMockOAuthAppsAuthorizeRedirect(auth_id, { approved: false })
+}
+
+type OAuthAppsAuthorizeDenyData = Awaited>
+
+export const useOAuthAppsAuthorizeDenyMutation = ({
+ onError,
+ ...options
+}: Omit<
+ UseCustomMutationOptions<
+ OAuthAppsAuthorizeDenyData,
+ ResponseError,
+ OAuthAppsAuthorizeDenyVariables
+ >,
+ 'mutationFn'
+> = {}) => {
+ return useMutation({
+ mutationFn: (vars) => denyOAuthAppsAuthorize(vars),
+ async onError(data, variables, context) {
+ if (onError === undefined) {
+ toast.error(`Failed to deny access to OAuth app: ${data.message}`)
+ } else {
+ onError(data, variables, context)
+ }
+ },
+ ...options,
+ })
+}
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-mutations.test.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-mutations.test.ts
new file mode 100644
index 00000000000..f53884948b3
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-mutations.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'vitest'
+
+import { OAUTH_APPS_MOCK_SCENARIOS } from './mocks'
+import { approveOAuthAppsAuthorize } from './oauth-apps-authorize-approve-mutation'
+import { denyOAuthAppsAuthorize } from './oauth-apps-authorize-deny-mutation'
+import { isRoleValidationFailure } from './types'
+
+const AUTH_ID = OAUTH_APPS_MOCK_SCENARIOS.vercelDeveloper
+const SLUG = 'northwind-traders'
+const BODY = { project_refs: ['northwindstorefront1'] }
+
+async function approveExpectingRedirect(
+ variables: Parameters[0]
+) {
+ const result = await approveOAuthAppsAuthorize(variables)
+ if (isRoleValidationFailure(result)) throw new Error('expected a redirect, got a role failure')
+ return result
+}
+
+describe('approveOAuthAppsAuthorize', () => {
+ test('returns a redirect url carrying both code and state', async () => {
+ const { url } = await approveExpectingRedirect({ slug: SLUG, auth_id: AUTH_ID, body: BODY })
+
+ const params = new URL(url).searchParams
+ expect(params.get('code')).toBeTruthy()
+ expect(params.get('state')).toBeTruthy()
+ expect(params.get('error')).toBeNull()
+ })
+
+ test('accepts a body without project_refs', async () => {
+ const { url } = await approveExpectingRedirect({ slug: SLUG, auth_id: AUTH_ID, body: {} })
+
+ expect(new URL(url).searchParams.get('code')).toBeTruthy()
+ })
+
+ test('requires an authorization request id', async () => {
+ await expect(
+ approveOAuthAppsAuthorize({ slug: SLUG, auth_id: '', body: BODY })
+ ).rejects.toThrow('Authorization request id is required')
+ })
+
+ test('requires an organization slug', async () => {
+ await expect(
+ approveOAuthAppsAuthorize({ slug: '', auth_id: AUTH_ID, body: BODY })
+ ).rejects.toThrow('Organization slug is required')
+ })
+
+ test('does not enforce a selection cap', async () => {
+ const manyRefs = Array.from({ length: 25 }, (_, index) => `ref-${index}`)
+
+ const { url } = await approveExpectingRedirect({
+ slug: SLUG,
+ auth_id: AUTH_ID,
+ body: { project_refs: manyRefs },
+ })
+
+ expect(url).toBeTruthy()
+ })
+})
+
+describe('denyOAuthAppsAuthorize', () => {
+ test('returns a redirect url carrying access_denied and state', async () => {
+ const { url } = await denyOAuthAppsAuthorize({ slug: SLUG, auth_id: AUTH_ID })
+
+ const params = new URL(url).searchParams
+ expect(params.get('error')).toBe('access_denied')
+ expect(params.get('state')).toBeTruthy()
+ expect(params.get('code')).toBeNull()
+ })
+
+ test('requires an authorization request id', async () => {
+ await expect(denyOAuthAppsAuthorize({ slug: SLUG, auth_id: '' })).rejects.toThrow(
+ 'Authorization request id is required'
+ )
+ })
+
+ test('requires an organization slug', async () => {
+ await expect(denyOAuthAppsAuthorize({ slug: '', auth_id: AUTH_ID })).rejects.toThrow(
+ 'Organization slug is required'
+ )
+ })
+})
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-organization-projects-query.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-organization-projects-query.ts
new file mode 100644
index 00000000000..8881f59a2b1
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-organization-projects-query.ts
@@ -0,0 +1,53 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthAppsAuthorizeOrganizationProjects, USE_MOCKS } from './mocks'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthAppsAuthorizeOrganizationProjectsVariables = {
+ id?: string
+ slug?: string
+}
+
+export type { OAuthAppsAuthorizeOrganizationProject } from './types'
+
+export async function getOAuthAppsAuthorizeOrganizationProjects({
+ id,
+ slug,
+}: OAuthAppsAuthorizeOrganizationProjectsVariables) {
+ if (!id) throw new Error('Authorization request id is required')
+ if (!slug) throw new Error('Organization slug is required')
+ if (!USE_MOCKS)
+ throw new Error('OAuth app authorization organization projects are not yet implemented')
+
+ return getMockOAuthAppsAuthorizeOrganizationProjects(slug)
+}
+
+export type OAuthAppsAuthorizeOrganizationProjectsData = Awaited<
+ ReturnType
+>
+export type OAuthAppsAuthorizeOrganizationProjectsError = ResponseError
+
+export const useOAuthAppsAuthorizeOrganizationProjectsQuery = <
+ TData = OAuthAppsAuthorizeOrganizationProjectsData,
+>(
+ { id, slug }: OAuthAppsAuthorizeOrganizationProjectsVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions<
+ OAuthAppsAuthorizeOrganizationProjectsData,
+ OAuthAppsAuthorizeOrganizationProjectsError,
+ TData
+ > = {}
+) =>
+ useQuery<
+ OAuthAppsAuthorizeOrganizationProjectsData,
+ OAuthAppsAuthorizeOrganizationProjectsError,
+ TData
+ >({
+ queryKey: oauthAppsKeys.authorizeOrganizationProjects(id, slug),
+ queryFn: () => getOAuthAppsAuthorizeOrganizationProjects({ id, slug }),
+ enabled: enabled && USE_MOCKS && Boolean(id) && Boolean(slug),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-organizations-query.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-organizations-query.ts
new file mode 100644
index 00000000000..c41bf4992f3
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-organizations-query.ts
@@ -0,0 +1,49 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthAppsAuthorizeIdentity, USE_MOCKS } from './mocks'
+import type { OAuthOrganizationRole } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthAppsAuthorizeOrganizationsVariables = {
+ id?: string
+}
+
+export type OAuthAppsAuthorizeIdentity = {
+ email: string
+ organizations: OAuthOrganizationRole[]
+}
+
+export async function getOAuthAppsAuthorizeIdentity({
+ id,
+}: OAuthAppsAuthorizeOrganizationsVariables) {
+ if (!id) throw new Error('Authorization request id is required')
+ if (!USE_MOCKS) throw new Error('OAuth app authorization identity is not yet implemented')
+
+ return getMockOAuthAppsAuthorizeIdentity(id)
+}
+
+export type OAuthAppsAuthorizeOrganizationsData = Awaited<
+ ReturnType
+>
+export type OAuthAppsAuthorizeOrganizationsError = ResponseError
+
+export const useOAuthAppsAuthorizeOrganizationsQuery = <
+ TData = OAuthAppsAuthorizeOrganizationsData,
+>(
+ { id }: OAuthAppsAuthorizeOrganizationsVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions<
+ OAuthAppsAuthorizeOrganizationsData,
+ OAuthAppsAuthorizeOrganizationsError,
+ TData
+ > = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.authorizeOrganizations(id),
+ queryFn: () => getOAuthAppsAuthorizeIdentity({ id }),
+ enabled: enabled && USE_MOCKS && Boolean(id),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-authorize-request-query.ts b/apps/studio/data/oauth-apps/oauth-apps-authorize-request-query.ts
new file mode 100644
index 00000000000..a231073e086
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-authorize-request-query.ts
@@ -0,0 +1,42 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthAppsAuthorizeRequest, USE_MOCKS } from './mocks'
+import type { OAuthAppsAuthorizeRequest } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthAppsAuthorizeRequestVariables = {
+ id?: string
+}
+
+export type { OAuthAppsAuthorizeRequest } from './types'
+
+export async function getOAuthAppsAuthorizeRequest({
+ id,
+}: OAuthAppsAuthorizeRequestVariables): Promise {
+ if (!id) throw new Error('Authorization request id is required')
+ if (!USE_MOCKS) throw new Error('OAuth app authorization request is not yet implemented')
+
+ return getMockOAuthAppsAuthorizeRequest(id)
+}
+
+export type OAuthAppsAuthorizeRequestData = Awaited>
+export type OAuthAppsAuthorizeRequestError = ResponseError
+
+export const useOAuthAppsAuthorizeRequestQuery = (
+ { id }: OAuthAppsAuthorizeRequestVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions<
+ OAuthAppsAuthorizeRequestData,
+ OAuthAppsAuthorizeRequestError,
+ TData
+ > = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.authorizeRequest(id),
+ queryFn: () => getOAuthAppsAuthorizeRequest({ id }),
+ enabled: enabled && USE_MOCKS && Boolean(id),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-grants-query.ts b/apps/studio/data/oauth-apps/oauth-apps-grants-query.ts
new file mode 100644
index 00000000000..f5f300fc160
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-grants-query.ts
@@ -0,0 +1,37 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthOwnGrants, USE_MOCKS } from './mocks'
+import type { ListOwnGrantsResponse } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthGrantsVariables = {
+ cursor?: string
+}
+
+export type { ListOwnGrantsResponse, MemberOauthGrantItem, OAuthGrantProject } from './types'
+
+export async function getOAuthGrants({
+ cursor,
+}: OAuthGrantsVariables = {}): Promise {
+ if (!USE_MOCKS) throw new Error('OAuth grants are not yet implemented')
+
+ return getMockOAuthOwnGrants(cursor)
+}
+
+export type OAuthGrantsData = Awaited>
+export type OAuthGrantsError = ResponseError
+
+export const useOAuthGrantsQuery = (
+ { cursor }: OAuthGrantsVariables = {},
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.grants(cursor),
+ queryFn: () => getOAuthGrants({ cursor }),
+ enabled: enabled && USE_MOCKS,
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-member-grants-query.ts b/apps/studio/data/oauth-apps/oauth-apps-member-grants-query.ts
new file mode 100644
index 00000000000..6cef0997500
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-member-grants-query.ts
@@ -0,0 +1,43 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthAppGrants, USE_MOCKS } from './mocks'
+import type { ListOrgAppGrantsResponse } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthAppMemberGrantsVariables = {
+ slug?: string
+ appId?: string
+ cursor?: string
+}
+
+export type { ListOrgAppGrantsResponse, OAuthGrantItem, OAuthGrantProject } from './types'
+
+export async function getOAuthAppMemberGrants({
+ slug,
+ appId,
+ cursor,
+}: OAuthAppMemberGrantsVariables): Promise {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!appId) throw new Error('App id is required')
+ if (!USE_MOCKS) throw new Error('OAuth app member grants are not yet implemented')
+
+ return getMockOAuthAppGrants(appId, cursor)
+}
+
+export type OAuthAppMemberGrantsData = Awaited>
+export type OAuthAppMemberGrantsError = ResponseError
+
+export const useOAuthAppMemberGrantsQuery = (
+ { slug, appId, cursor }: OAuthAppMemberGrantsVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.appMemberGrants(slug, appId, cursor),
+ queryFn: () => getOAuthAppMemberGrants({ slug, appId, cursor }),
+ enabled: enabled && USE_MOCKS && Boolean(slug) && Boolean(appId),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-org-app-details-query.ts b/apps/studio/data/oauth-apps/oauth-apps-org-app-details-query.ts
new file mode 100644
index 00000000000..169ae55359e
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-org-app-details-query.ts
@@ -0,0 +1,41 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthOrgAppDetails, USE_MOCKS } from './mocks'
+import type { OAuthOrgAppDetails } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthOrgAppDetailsVariables = {
+ slug?: string
+ appId?: string
+}
+
+export type { OAuthOrgAppDetails } from './types'
+
+export async function getOAuthOrgAppDetails({
+ slug,
+ appId,
+}: OAuthOrgAppDetailsVariables): Promise {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!appId) throw new Error('App id is required')
+ if (!USE_MOCKS) throw new Error('OAuth org app details are not yet implemented')
+
+ return getMockOAuthOrgAppDetails(slug, appId)
+}
+
+export type OAuthOrgAppDetailsData = Awaited>
+export type OAuthOrgAppDetailsError = ResponseError
+
+export const useOAuthOrgAppDetailsQuery = (
+ { slug, appId }: OAuthOrgAppDetailsVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.orgAppDetails(slug, appId),
+ queryFn: () => getOAuthOrgAppDetails({ slug, appId }),
+ enabled: enabled && USE_MOCKS && Boolean(slug) && Boolean(appId),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-preflight-validation-query.ts b/apps/studio/data/oauth-apps/oauth-apps-preflight-validation-query.ts
new file mode 100644
index 00000000000..5bf8f6a2e68
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-preflight-validation-query.ts
@@ -0,0 +1,47 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { oauthAppsKeys } from './keys'
+import { getMockOAuthAppsPreflightValidation, USE_MOCKS } from './mocks'
+import type { OAuthAppsAuthorizePreflightResult } from './types'
+import type { ResponseError, UseCustomQueryOptions } from '@/types'
+
+export type OAuthAppsPreflightValidationVariables = {
+ slug?: string
+ appId?: string
+}
+
+export type { OAuthAppsAuthorizePreflightResult } from './types'
+
+export async function getOAuthAppsPreflightValidation({
+ slug,
+ appId,
+}: OAuthAppsPreflightValidationVariables): Promise {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!appId) throw new Error('App id is required')
+ if (!USE_MOCKS) throw new Error('OAuth app preflight validation is not yet implemented')
+
+ return getMockOAuthAppsPreflightValidation(slug, appId)
+}
+
+export type OAuthAppsPreflightValidationData = Awaited<
+ ReturnType
+>
+export type OAuthAppsPreflightValidationError = ResponseError
+
+export const useOAuthAppsPreflightValidationQuery = (
+ { slug, appId }: OAuthAppsPreflightValidationVariables,
+ {
+ enabled = true,
+ ...options
+ }: UseCustomQueryOptions<
+ OAuthAppsPreflightValidationData,
+ OAuthAppsPreflightValidationError,
+ TData
+ > = {}
+) =>
+ useQuery({
+ queryKey: oauthAppsKeys.preflightValidation(slug, appId),
+ queryFn: () => getOAuthAppsPreflightValidation({ slug, appId }),
+ enabled: enabled && USE_MOCKS && Boolean(slug) && Boolean(appId),
+ ...options,
+ })
diff --git a/apps/studio/data/oauth-apps/oauth-apps-revoke-grant-mutation.ts b/apps/studio/data/oauth-apps/oauth-apps-revoke-grant-mutation.ts
new file mode 100644
index 00000000000..e7fe1faa1b4
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-revoke-grant-mutation.ts
@@ -0,0 +1,48 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+import { oauthAppsKeys } from './keys'
+import { USE_MOCKS } from './mocks'
+import type { ResponseError, UseCustomMutationOptions } from '@/types'
+
+export type OAuthGrantRevokeVariables = {
+ slug: string
+ grantId: string
+}
+
+export async function revokeOAuthGrant({ slug, grantId }: OAuthGrantRevokeVariables) {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!grantId) throw new Error('Grant id is required')
+ if (!USE_MOCKS) throw new Error('OAuth grant revocation is not yet implemented')
+
+ // 204 on success — no response body.
+}
+
+type OAuthGrantRevokeData = Awaited>
+
+export const useOAuthGrantRevokeMutation = ({
+ onError,
+ onSuccess,
+ ...options
+}: Omit<
+ UseCustomMutationOptions,
+ 'mutationFn'
+> = {}) => {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: (vars) => revokeOAuthGrant(vars),
+ async onSuccess(data, variables, context) {
+ await queryClient.invalidateQueries({ queryKey: oauthAppsKeys.grants() })
+ await onSuccess?.(data, variables, context)
+ },
+ async onError(data, variables, context) {
+ if (onError === undefined) {
+ toast.error(`Failed to revoke OAuth grant: ${data.message}`)
+ } else {
+ onError(data, variables, context)
+ }
+ },
+ ...options,
+ })
+}
diff --git a/apps/studio/data/oauth-apps/oauth-apps-revoke-mutation.ts b/apps/studio/data/oauth-apps/oauth-apps-revoke-mutation.ts
new file mode 100644
index 00000000000..72f80a5b592
--- /dev/null
+++ b/apps/studio/data/oauth-apps/oauth-apps-revoke-mutation.ts
@@ -0,0 +1,57 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+import { oauthAppsKeys } from './keys'
+import { USE_MOCKS } from './mocks'
+import type { ResponseError, UseCustomMutationOptions } from '@/types'
+
+export type OAuthAppRevokeVariables = {
+ slug: string
+ appId: string
+}
+
+export async function revokeOAuthApp({ slug, appId }: OAuthAppRevokeVariables) {
+ if (!slug) throw new Error('Organization slug is required')
+ if (!appId) throw new Error('App id is required')
+ if (!USE_MOCKS) throw new Error('OAuth app revocation is not yet implemented')
+
+ return { id: appId }
+}
+
+type OAuthAppRevokeData = Awaited>
+
+export const useOAuthAppRevokeMutation = ({
+ onError,
+ onSuccess,
+ ...options
+}: Omit<
+ UseCustomMutationOptions,
+ 'mutationFn'
+> = {}) => {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: (vars) => revokeOAuthApp(vars),
+ async onSuccess(data, variables, context) {
+ // Revoking an app deletes every row for (app_id, organization_id), both kinds — the
+ // org's approvals overview, this app's grant list, and any member's own-grants view are
+ // all stale.
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: oauthAppsKeys.approvals(variables.slug) }),
+ queryClient.invalidateQueries({
+ queryKey: oauthAppsKeys.appMemberGrants(variables.slug, variables.appId),
+ }),
+ queryClient.invalidateQueries({ queryKey: oauthAppsKeys.grants() }),
+ ])
+ await onSuccess?.(data, variables, context)
+ },
+ async onError(data, variables, context) {
+ if (onError === undefined) {
+ toast.error(`Failed to revoke OAuth app: ${data.message}`)
+ } else {
+ onError(data, variables, context)
+ }
+ },
+ ...options,
+ })
+}
diff --git a/apps/studio/data/oauth-apps/types.test.ts b/apps/studio/data/oauth-apps/types.test.ts
new file mode 100644
index 00000000000..0af62eee06a
--- /dev/null
+++ b/apps/studio/data/oauth-apps/types.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, test } from 'vitest'
+
+import { DEVELOPER_ROLE, READ_ONLY_ROLE } from './mocks'
+import type { OAuthAppsAuthorizeOrganizationProject, OAuthExistingGrant } from './types'
+import { getFailedProjects, getPreselectedProjectRefs, isRoleValidationFailure } from './types'
+
+const project = (ref: string): OAuthAppsAuthorizeOrganizationProject => ({
+ ref,
+ name: ref,
+ role: DEVELOPER_ROLE,
+})
+
+const grant = (refs: string[]): OAuthExistingGrant => ({
+ approved_scopes: ['projects:read'],
+ project_refs: refs,
+ approved_at: '2026-08-14T09:12:00.000Z',
+})
+
+describe('getPreselectedProjectRefs', () => {
+ const live = ['alpha', 'bravo', 'charlie', 'delta'].map(project)
+
+ test('preselects the project_ref query param when it resolves against live projects', () => {
+ expect(
+ getPreselectedProjectRefs({ existingGrant: null, projectRef: 'alpha', liveProjects: live })
+ ).toEqual(['alpha'])
+ })
+
+ test('drops a project_ref that does not resolve against live projects', () => {
+ expect(
+ getPreselectedProjectRefs({ existingGrant: null, projectRef: 'ghost', liveProjects: live })
+ ).toEqual([])
+ })
+
+ test('returns nothing when there is neither a grant nor a project_ref', () => {
+ expect(
+ getPreselectedProjectRefs({ existingGrant: null, projectRef: null, liveProjects: live })
+ ).toEqual([])
+ })
+
+ test('existing-grant refs win over the project_ref query param', () => {
+ expect(
+ getPreselectedProjectRefs({
+ existingGrant: grant(['charlie', 'delta']),
+ projectRef: 'alpha',
+ liveProjects: live,
+ })
+ ).toEqual(['charlie', 'delta'])
+ })
+
+ test('filters stale refs out of the existing grant', () => {
+ expect(
+ getPreselectedProjectRefs({
+ existingGrant: grant(['alpha', 'ghost']),
+ projectRef: null,
+ liveProjects: live,
+ })
+ ).toEqual(['alpha'])
+ })
+
+ test('falls back to the project_ref when the existing grant carries no refs', () => {
+ expect(
+ getPreselectedProjectRefs({
+ existingGrant: grant([]),
+ projectRef: 'bravo',
+ liveProjects: live,
+ })
+ ).toEqual(['bravo'])
+ })
+
+ test('does not cap the number of preselected refs', () => {
+ const manyProjects = Array.from({ length: 15 }, (_, index) => project(`ref-${index}`))
+ const manyRefs = manyProjects.map((entry) => entry.ref)
+
+ expect(
+ getPreselectedProjectRefs({
+ existingGrant: grant(manyRefs),
+ projectRef: null,
+ liveProjects: manyProjects,
+ })
+ ).toEqual(manyRefs)
+ })
+
+ test('returns nothing when there are no live projects', () => {
+ expect(
+ getPreselectedProjectRefs({
+ existingGrant: grant(['alpha']),
+ projectRef: 'alpha',
+ liveProjects: [],
+ })
+ ).toEqual([])
+ })
+})
+
+describe('isRoleValidationFailure', () => {
+ test('recognises a role validation failure', () => {
+ expect(
+ isRoleValidationFailure({
+ error_code: 'role_validation_failed',
+ message: 'nope',
+ validation: { scope_target: 'organization', role: READ_ONLY_ROLE },
+ })
+ ).toBe(true)
+ })
+
+ test('treats a redirect as a success', () => {
+ expect(isRoleValidationFailure({ url: 'https://vercel.com/callback?code=abc' })).toBe(false)
+ })
+})
+
+describe('getFailedProjects', () => {
+ test('returns the failures of a projects-level failure', () => {
+ const failure = {
+ ref: 'alpha',
+ name: 'alpha',
+ role: READ_ONLY_ROLE,
+ failed_scopes: ['database:write' as const],
+ }
+
+ expect(
+ getFailedProjects({
+ error_code: 'role_validation_failed',
+ message: 'nope',
+ validation: { scope_target: 'projects', failures: [failure] },
+ })
+ ).toEqual([failure])
+ })
+
+ test('is empty for an organization-level failure', () => {
+ expect(
+ getFailedProjects({
+ error_code: 'role_validation_failed',
+ message: 'nope',
+ validation: { scope_target: 'organization', role: READ_ONLY_ROLE },
+ })
+ ).toEqual([])
+ })
+
+ test('is empty when there is no failure', () => {
+ expect(getFailedProjects(null)).toEqual([])
+ expect(getFailedProjects(undefined)).toEqual([])
+ })
+})
diff --git a/apps/studio/data/oauth-apps/types.ts b/apps/studio/data/oauth-apps/types.ts
new file mode 100644
index 00000000000..4d811a3b37d
--- /dev/null
+++ b/apps/studio/data/oauth-apps/types.ts
@@ -0,0 +1,190 @@
+import type { components } from 'api-types'
+
+import type { OrganizationRole } from '@/data/organization-members/organization-roles-query'
+
+type LiveAuthorizeRequest = components['schemas']['GetOAuthAuthorizationResponse_Output']
+
+export type OAuthAppsAuthorizeLiveFields = Pick<
+ LiveAuthorizeRequest,
+ 'name' | 'website' | 'domain' | 'icon' | 'redirect_uri' | 'registration_type' | 'expires_at'
+>
+
+export type OAuthScope = NonNullable[number]
+
+export function isWriteScope(scope: OAuthScope): boolean {
+ return scope.endsWith(':write')
+}
+
+export type OAuthGrantKind = 'organization_bound' | 'member_bound'
+
+export type OAuthAppsAuthorizeRequest = OAuthAppsAuthorizeLiveFields & {
+ app_id: string
+ app_name: string
+ grant_kind: OAuthGrantKind
+ project_scoping_mode: boolean
+ scopes: OAuthScope[]
+}
+
+export type OAuthOrganizationRole = {
+ slug: string
+ name: string
+ default_role: OrganizationRole
+}
+
+export type OAuthAppsAuthorizeOrganizationProject = {
+ ref: string
+ name: string
+ role: OrganizationRole
+}
+
+export type OAuthExistingGrant = {
+ approved_scopes: OAuthScope[] | null
+ project_refs: string[]
+ approved_at: string
+}
+
+export type OAuthOrgAppDetails = {
+ existing_grant: OAuthExistingGrant | null
+}
+
+export function getPreselectedProjectRefs({
+ existingGrant,
+ projectRef,
+ liveProjects,
+}: {
+ existingGrant: OAuthExistingGrant | null
+ projectRef: string | null
+ liveProjects: OAuthAppsAuthorizeOrganizationProject[]
+}): string[] {
+ const liveRefs = new Set(liveProjects.map((project) => project.ref))
+ const candidates = existingGrant?.project_refs.length
+ ? existingGrant.project_refs
+ : projectRef
+ ? [projectRef]
+ : []
+ return candidates.filter((ref) => liveRefs.has(ref))
+}
+
+export type OAuthAuthorizeApproveRequest = {
+ // not allowed when project_scoping_mode is false.
+ // when project_scoping_mode is true, if omitted, this means all projects
+ project_refs?: string[]
+}
+
+export type OAuthAppsAuthorizeRedirect =
+ components['schemas']['ApproveAuthorizationResponse_Output']
+
+export type OAuthScopeValidationResult =
+ | {
+ scope_target: 'organization'
+ role: OrganizationRole
+ }
+ | {
+ scope_target: 'all_projects'
+ role: OrganizationRole
+ failed_scopes: OAuthScope[]
+ }
+ | {
+ scope_target: 'projects'
+ failures: Array<{
+ ref: string
+ name: string
+ role: OrganizationRole
+ failed_scopes: OAuthScope[]
+ }>
+ }
+
+export type OAuthScopeValidationProjectFailure = Extract<
+ OAuthScopeValidationResult,
+ { scope_target: 'projects' }
+>['failures'][number]
+
+export type OAuthAppsAuthorizeRoleValidationFailure = {
+ error_code: 'role_validation_failed'
+ message: string
+ validation: OAuthScopeValidationResult
+}
+
+export type OAuthAppsAuthorizeApproveResult =
+ | OAuthAppsAuthorizeRedirect
+ | OAuthAppsAuthorizeRoleValidationFailure
+
+export function isRoleValidationFailure(
+ result: OAuthAppsAuthorizeApproveResult
+): result is OAuthAppsAuthorizeRoleValidationFailure {
+ return 'error_code' in result && result.error_code === 'role_validation_failed'
+}
+
+export function getFailedProjects(
+ failure: OAuthAppsAuthorizeRoleValidationFailure | null | undefined
+): OAuthScopeValidationProjectFailure[] {
+ if (!failure) return []
+ return failure.validation.scope_target === 'projects' ? failure.validation.failures : []
+}
+
+export type OAuthAppsAuthorizePreflightSuccess = { ok: true }
+
+export type OAuthAppsAuthorizePreflightResult =
+ | OAuthAppsAuthorizePreflightSuccess
+ | OAuthAppsAuthorizeRoleValidationFailure
+
+export function isPreflightValidationFailure(
+ result: OAuthAppsAuthorizePreflightResult
+): result is OAuthAppsAuthorizeRoleValidationFailure {
+ return 'error_code' in result && result.error_code === 'role_validation_failed'
+}
+
+export type OAuthApprovalTarget = 'organization' | 'members' | 'organization_and_members'
+
+export type OAuthApprovalItem = {
+ app: {
+ id: string
+ name: string
+ created_by: string
+ icon: string | null
+ }
+ grant_target: OAuthApprovalTarget
+ org_grant: {
+ grant_id: string
+ approved_scopes: string[]
+ approved_at: string
+ } | null
+}
+
+export type ListOAuthApprovalsResponse = {
+ data: OAuthApprovalItem[]
+ pagination: { next_cursor: string | null }
+}
+
+export type OAuthGrantProject = {
+ ref: string
+ name: string
+}
+
+export type OAuthGrantItem = {
+ grant_id: string
+ kind: OAuthGrantKind
+ user: { gotrue_id: string; email: string; avatar_url?: string } | null
+ projects: OAuthGrantProject[] | null
+ approved_scopes: string[]
+ approved_at: string
+}
+
+export type ListOrgAppGrantsResponse = {
+ data: OAuthGrantItem[]
+ pagination: { next_cursor: string | null }
+}
+
+export type MemberOauthGrantItem = {
+ grant_id: string
+ app: { id: string; name: string; icon: string | null }
+ organization: { slug: string; name: string }
+ projects: OAuthGrantProject[] | null
+ approved_scopes: string[]
+ approved_at: string
+}
+
+export type ListOwnGrantsResponse = {
+ data: MemberOauthGrantItem[]
+ pagination: { next_cursor: string | null }
+}
diff --git a/knip.jsonc b/knip.jsonc
index 7a79952a7e0..5baa43c1ad7 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -65,6 +65,13 @@
// read are documentation of the valid values, not dead code. Scoped to
// this file so `enumMembers` keeps working everywhere else.
"data/database/constraints-query.ts": ["enumMembers"],
+ // Data contracts and mock hooks for the OAuth authorization
+ // interstitial, landed ahead of the UI that consumes them. `exports`
+ // and `types` cover the contract types that only gain consumers in the
+ // consent-screen PR.
+ // TODO(PROD-625): drop every oauth-apps knip exception in the
+ // consent-screen PR, once the interstitial route imports them.
+ "data/oauth-apps/**": ["files", "exports", "types"],
"hooks/misc/useTrackExperimentExposure.ts": ["files"],
// Staging-only pinned Postgres image + FDW request payload for creating
// Warehouse test projects by hand. Nothing imports it yet — it's kept
From f414a68e1bb0067f3f12953c8cd3b55ba75c79de Mon Sep 17 00:00:00 2001
From: Wen Bo Xie
Date: Mon, 5 Oct 2026 06:26:52 -0700
Subject: [PATCH 09/41] docs(cli): address final review feedback on supabase
stack guides (#51217)
- Add stack = true under the existing [experimental] table instead of
pasting a duplicate table, which leaves the setting off.
- Note that db dump targets the linked project unless --local is passed,
and that --db-url reaches a named local project through DB_URL.
- Qualify offline destroy on the host data being deletable, and scope
the shared Docker volume cleanup note to volume-backed projects.
- Say Docker database storage is chosen when the local project is
created.
- Allow GitHub's release download host alongside github.com, or the S3
host alone, in allowlisted sandboxes.
- www: most services stop when idle (not Functions), and state the
[experimental] stack prerequisite in the native runtime entry.
---
.../local-development/docker-and-native-runtimes.mdx | 6 ++++--
.../running-multiple-local-projects.mdx | 12 +++++++-----
apps/www/data/features.tsx | 4 ++--
3 files changed, 13 insertions(+), 9 deletions(-)
diff --git a/apps/docs/content/guides/local-development/docker-and-native-runtimes.mdx b/apps/docs/content/guides/local-development/docker-and-native-runtimes.mdx
index ec1da3c4bc3..113bc12b773 100644
--- a/apps/docs/content/guides/local-development/docker-and-native-runtimes.mdx
+++ b/apps/docs/content/guides/local-development/docker-and-native-runtimes.mdx
@@ -30,10 +30,12 @@ The following table compares how each runtime runs services, what it needs, and
| Flag | `--runtime docker` or `--runtime podman` | `--runtime native` |
| How services run | One container per service, from images the CLI pulls | One process per service, from archives the CLI downloads and verifies |
| Requires | A running Docker or Podman engine | A supported platform, `tar` on the host, and, on first start, network access to the archive download hosts |
-| Database data | A Docker volume when the Docker client and daemon are both version 26 or later, or a host directory otherwise | `~/.supabase/stacks//` in your home directory |
+| Database data | Set when the local project is created. A Docker volume if the Docker client and daemon are both version 26 or later, otherwise a host directory | `~/.supabase/stacks//` in your home directory |
| Downloaded artifacts | The engine's image cache | `~/.supabase/cache/stack` in your home directory, shared by all local projects |
| Isolation between local projects | Separate network namespaces and file systems | Shared host process table and file locks |
+A Docker local project keeps the database storage it was created with. A local project created on Docker 25 keeps its host directory after you upgrade to Docker 26.
+
Both runtimes keep each local project's saved settings under `~/.supabase/stacks//`. The native runtime keeps its database data there too. If you set `SUPABASE_HOME`, the CLI uses that directory instead of `~/.supabase`.
In both runtimes, Postgres starts right away and other services start on their first request. By default, services that started this way stop again after 60 seconds idle, and Studio after 5 minutes. Functions doesn't stop on its own. A service also stays up while a running service depends on it, such as pgmeta while Studio runs. Pass `--eager` to start every enabled service before the command returns and turn off idle stops.
@@ -69,7 +71,7 @@ The native runtime runs on these platforms:
The native runtime doesn't run as `root`, because Postgres `initdb` can't. To run it as `root`, such as in a CI container, set `SUPABASE_NATIVE_POSTGRES_USER` to a non-root account. Create the account first if it doesn't exist. The CLI then runs Postgres as that user. In some supported coding agent sandboxes, the CLI finds a suitable non-root account without the variable.
-On first start, the CLI downloads service archives from the [`supabase/slim-services` GitHub releases](https://github.com/supabase/slim-services/releases), with `supabase-cli-artifacts.s3.us-east-1.amazonaws.com` as a fallback. It verifies their checksums and extracts them with the system `tar`, so install `tar` in minimal sandbox images. In a sandbox with an allowlist, allow `github.com` or that S3 host. Allowing only `ghcr.io` isn't enough.
+On first start, the CLI downloads service archives from the [`supabase/slim-services` GitHub releases](https://github.com/supabase/slim-services/releases), with `supabase-cli-artifacts.s3.us-east-1.amazonaws.com` as a fallback. It verifies their checksums and extracts them with the system `tar`, so install `tar` in minimal sandbox images. In a sandbox with an allowlist, allow the S3 host. To use GitHub instead, allow both `github.com` and `release-assets.githubusercontent.com`, because GitHub redirects release downloads to that host. Allowing only `ghcr.io` isn't enough.
To download the archives ahead of time without starting any services, such as when you build a sandbox image, run:
diff --git a/apps/docs/content/guides/local-development/running-multiple-local-projects.mdx b/apps/docs/content/guides/local-development/running-multiple-local-projects.mdx
index b1766586047..e718ac1c1b8 100644
--- a/apps/docs/content/guides/local-development/running-multiple-local-projects.mdx
+++ b/apps/docs/content/guides/local-development/running-multiple-local-projects.mdx
@@ -57,13 +57,15 @@ You need:
The `supabase stack` commands exist only when the `[experimental] stack` setting is on. Without it, `supabase stack` commands fail with `Unknown subcommand "stack"`.
-1. Add this to `supabase/config.toml` in your app directory:
+1. In `supabase/config.toml` in your app directory, add `stack = true` under the existing `[experimental]` table. If your `config.toml` doesn't have an `[experimental]` table, add one:
```toml
[experimental]
stack = true
```
+ Don't add a second `[experimental]` table. A duplicate table makes `config.toml` invalid. The stack commands then stay off. Commands that read the config fail with `failed to load config`.
+
In a directory without a `config.toml`, set the environment variable instead:
```bash
@@ -166,7 +168,7 @@ One app can run several local projects by name. This keeps a destructive test ru
A local project started without `--stack` is the app directory's default local project. Named local projects and the default one are independent of each other.
-The `db`, `migration`, and other database commands use the default local project for the current branch. They can't target a named local project. See [Limitations](#limitations).
+The `db`, `migration`, and other database commands don't accept `--stack`. When they run against a local database, they use the default local project for the current branch. `supabase db pull`, `supabase db push`, and `supabase db dump` target the linked project unless you pass `--local`. To reach a named local project from a command that accepts `--db-url`, pass the `DB_URL` from `supabase status --stack --env`. See [Limitations](#limitations).
## Find a local project's endpoints and keys
@@ -253,9 +255,9 @@ supabase stack destroy --stack test --yes
`destroy` keeps two kinds of data:
- Storage upload files, which live in your app at `supabase/.temp/stack-uploads//`. Delete that directory to remove them.
-- Container engine resources, if Docker or Podman isn't running. If no process for the local project is still running, the command removes the local project's registration. It prints cleanup commands to run after the engine starts again. Otherwise it fails and asks you to start the engine and retry.
+- Container engine resources, if Docker or Podman isn't running. The command can still remove the local project's registration if no process for it is still running and your user can delete its database files on the host. It then prints cleanup commands to run after the engine starts again. Otherwise it fails, keeps the local project, and asks you to start the engine and retry. Your user might not be able to delete database files that a container wrote to a host directory. Local projects created with Docker version 25 or earlier store data that way.
-The printed cleanup command deletes only this local project's database data, from a Docker volume that other local projects share. Don't delete the volume itself.
+If the local project stores its database data in a Docker volume, other local projects share that volume. The printed cleanup command deletes only this local project's data from it. Don't delete the volume itself.
## Differences from the default `supabase start`
@@ -275,7 +277,7 @@ Keep these differences in mind when you turn the setting on for an app that used
- Storage Analytics and Storage vector buckets
- A custom `edge_runtime.deno_version`
- OrioleDB, and `db.major_version` values other than 15 and 17
-- Database commands can't target a named local project. `supabase db reset`, `supabase db diff`, `supabase db pull`, `supabase db dump`, and the other local database commands use the app directory's default local project for the current branch, and don't accept `--stack`.
+- Database commands don't accept `--stack`. `supabase db reset` and `supabase db diff` run against the current branch's default local project. `supabase db pull`, `supabase db push`, and `supabase db dump` target the linked project unless you pass `--local`. To reach a named local project, pass the `DB_URL` from `supabase status --stack --env` to a command that accepts `--db-url`.
- Switching branches switches local projects. The git branch is part of the identity. After you check out another branch in the same directory, `supabase start` creates or resumes a different local project with its own data. The first branch's local project keeps running until you stop it.
- Moving or renaming an app directory creates a new local project, because the identity includes the project root path. The previous local project's data stays until you destroy it.
- `supabase stack logs` streams new log lines only. It has no history.
diff --git a/apps/www/data/features.tsx b/apps/www/data/features.tsx
index 597092badce..49bbfeeb214 100644
--- a/apps/www/data/features.tsx
+++ b/apps/www/data/features.tsx
@@ -2168,7 +2168,7 @@ With the default ports, a second \`supabase start\` on the same machine fails wi
2. Automatic ports: The CLI assigns ports from a shared range and keeps them across restarts. Remove the fixed ports from \`config.toml\` once, or create the project with the stack commands turned on.
3. Named environments: Start \`--stack dev\` and \`--stack test\` side by side in one app.
4. Docker or native runtime: Run in containers, or as processes on your machine without Docker on Linux and on macOS on Apple silicon. Use Docker when you run several local projects on one machine.
-5. Services start on demand: Postgres starts right away. Other services start on their first request and stop when idle, which keeps idle local projects light.
+5. Services start on demand: Postgres starts right away. Other services start on their first request. Most of them stop when idle, which keeps idle local projects light.
## Parallel local projects are valuable for:
- Developers running coding agents in git worktrees
@@ -2192,7 +2192,7 @@ The \`supabase stack\` commands are experimental. Their interface can change bet
title: 'Native runtime for local development',
subtitle: 'Run a local Supabase project as processes on your machine, without Docker.',
description: `
-The Supabase CLI can run a local Supabase project as native processes instead of containers. Coding agent sandboxes and CI runners often have no Docker daemon. There, \`supabase stack start\` downloads verified service binaries and runs Postgres, Auth, Storage, and the other services directly on the host.
+The Supabase CLI can run a local Supabase project as native processes instead of containers. Coding agent sandboxes and CI runners often have no Docker daemon. To run there, [turn on the \`[experimental] stack\` setting](https://supabase.com/docs/guides/local-development/running-multiple-local-projects#turn-on-the-stack-commands). Then \`supabase stack start\` downloads verified service binaries and runs Postgres, Auth, Storage, and the other services directly on the host.
It is the same local project you get from \`supabase start\`, with the same services and most of the same \`config.toml\` settings. The CLI picks Docker when its daemon responds, then Podman, then native. To require one, pass \`--runtime docker\`, \`--runtime podman\`, or \`--runtime native\`.
From 87681812a0b4aef538d18ea78a78e5ab6257952e Mon Sep 17 00:00:00 2001
From: Matt Rossman <22670878+mattrossman@users.noreply.github.com>
Date: Mon, 5 Oct 2026 09:37:51 -0400
Subject: [PATCH 10/41] fix(studio): assistant get_active_incidents url in prod
(#51047)
The Assistant's `get_active_incidents` tool has [failed in prod 99.8% of
the time over the past 60
days](https://supabase.slack.com/archives/C051L8U2EJF/p1790712805774689),
so users reporting outages get told it couldn't check incident status.
The failures never showed up as errors, which is why nobody noticed.
The Assistant now includes the `/dashboard` base path when it calls its
own API routes, so the tool stops hitting a 404 in prod
([`/api/incident-status`](https://supabase.com/api/incident-status) is a
404,
[`/dashboard/api/incident-status`](https://supabase.com/dashboard/api/incident-status)
is a 200). The tool also throws on a failed fetch now instead of
returning an `{ error }` result. That way failures show up as span
errors in Braintrust and as a failed tool call in the UI. The model
still gets the error message and tells the user it couldn't check.
When the fetch fails (in dashboard):
| Before (prod) | After (local, path temporarily broken) |
| --- | --- |
| 
| 
|
When the fetch fails (in Braintrust):
| Before (prod) | After (local, path temporarily broken) |
| --- | --- |
| 
| 
|
When the fetch works (local):
| Dashboard | Braintrust |
| --- | --- |
| 
| 
|
Ran it locally with tracing on. Here's a [successful
call](https://www.braintrust.dev/app/supabase.io/p/Assistant/logs?r=251bcd44-c55b-44bb-9ce2-b034b26f8832),
and one with the path temporarily broken, which now [logs a span
error](https://www.braintrust.dev/app/supabase.io/p/Assistant/logs?r=637f2dc8-f65b-4d65-9d86-0511b36e8685).
Local dev has no base path, so the prod URL is covered by the new
`getBasePathURL` tests.
Closes AI-1272
## Summary by CodeRabbit
* **Bug Fixes**
* Incident lookups now report fetch, HTTP, parsing, and validation
errors rather than returning an empty incident result.
* AI SQL generation now accounts for the configured site base path when
building its service URL.
* **Improvements**
* Site URLs now handle trailing slashes and existing base paths
consistently, avoiding duplicate path segments.
---
.../lib/ai/tools/incident-tools.test.ts | 44 ++---
apps/studio/lib/ai/tools/incident-tools.ts | 163 ++++++++----------
apps/studio/lib/helpers.test.ts | 28 +++
apps/studio/lib/helpers.ts | 11 ++
apps/studio/pages/api/ai/sql/generate-v4.ts | 4 +-
5 files changed, 130 insertions(+), 120 deletions(-)
diff --git a/apps/studio/lib/ai/tools/incident-tools.test.ts b/apps/studio/lib/ai/tools/incident-tools.test.ts
index c2e0ccee842..f62d3c7a0af 100644
--- a/apps/studio/lib/ai/tools/incident-tools.test.ts
+++ b/apps/studio/lib/ai/tools/incident-tools.test.ts
@@ -170,22 +170,19 @@ describe('ai/tools/incident-tools', () => {
expect((result as any).message).toContain('2 active incidents')
})
- it('should handle fetch errors', async () => {
+ it('throws on fetch errors', async () => {
const common = await import('common')
vi.spyOn(common, 'IS_PLATFORM', 'get').mockReturnValue(true)
mockFetch.mockRejectedValue(new Error('Network error'))
const tools = getIncidentTools({ baseUrl: 'https://supabase.com/dashboard' })
- const result = await (tools.get_active_incidents.execute as any)({}, executeOptions)
-
- expect(result).toEqual({
- incidents: [],
- error: 'Unable to check incident status at this time.',
- })
+ await expect(
+ (tools.get_active_incidents.execute as any)({}, executeOptions)
+ ).rejects.toThrow('Network error')
})
- it('should handle non-ok responses', async () => {
+ it('throws on non-ok responses with the status code', async () => {
const common = await import('common')
vi.spyOn(common, 'IS_PLATFORM', 'get').mockReturnValue(true)
@@ -195,12 +192,9 @@ describe('ai/tools/incident-tools', () => {
})
const tools = getIncidentTools({ baseUrl: 'https://supabase.com/dashboard' })
- const result = await (tools.get_active_incidents.execute as any)({}, executeOptions)
-
- expect(result).toEqual({
- incidents: [],
- error: 'Unable to check incident status at this time.',
- })
+ await expect(
+ (tools.get_active_incidents.execute as any)({}, executeOptions)
+ ).rejects.toThrow('Failed to fetch incident status: 500')
})
it('should use timeout signal', async () => {
@@ -424,7 +418,7 @@ describe('ai/tools/incident-tools', () => {
})
})
- it('returns an error when the response fails to parse', async () => {
+ it('throws when the response fails to parse', async () => {
mockFetch.mockResolvedValue({
ok: true,
json: async () => ({ this_is: 'not a valid status page response' }),
@@ -434,15 +428,12 @@ describe('ai/tools/incident-tools', () => {
baseUrl: 'https://supabase.com/dashboard',
useStatusPageWidget: true,
})
- const result = await (tools.get_active_incidents.execute as any)({}, executeOptions)
-
- expect(result).toEqual({
- incidents: [],
- error: 'Unable to check incident status at this time.',
- })
+ await expect((tools.get_active_incidents.execute as any)({}, executeOptions)).rejects.toThrow(
+ 'Failed to parse status page response'
+ )
})
- it('returns an error on a non-ok response', async () => {
+ it('throws on a non-ok response with the status code', async () => {
mockFetch.mockResolvedValue({
ok: false,
status: 500,
@@ -452,12 +443,9 @@ describe('ai/tools/incident-tools', () => {
baseUrl: 'https://supabase.com/dashboard',
useStatusPageWidget: true,
})
- const result = await (tools.get_active_incidents.execute as any)({}, executeOptions)
-
- expect(result).toEqual({
- incidents: [],
- error: 'Unable to check incident status at this time.',
- })
+ await expect((tools.get_active_incidents.execute as any)({}, executeOptions)).rejects.toThrow(
+ 'Failed to fetch status page: 500'
+ )
})
})
})
diff --git a/apps/studio/lib/ai/tools/incident-tools.ts b/apps/studio/lib/ai/tools/incident-tools.ts
index ffb8e0e0acb..d9e7a9cffbb 100644
--- a/apps/studio/lib/ai/tools/incident-tools.ts
+++ b/apps/studio/lib/ai/tools/incident-tools.ts
@@ -8,10 +8,6 @@ import {
type AffectedComponent,
} from '@/lib/status-page/status-page.schema'
-const INCIDENT_STATUS_ERROR = {
- incidents: [],
- error: 'Unable to check incident status at this time.',
-}
const NO_ACTIVE_INCIDENTS_MESSAGE = 'No active incidents.'
const DEFAULT_STATUS_PAGE_URL = 'https://status.supabase.com'
@@ -74,108 +70,95 @@ export const getIncidentTools = ({
}
if (useStatusPageWidget) {
- try {
- const response = await fetch(`${baseUrl}/api/status-page`, {
- signal: timeoutSignal(abortSignal),
- })
-
- if (!response.ok) {
- console.warn('Failed to fetch status page:', response.status)
- return INCIDENT_STATUS_ERROR
- }
-
- const json = await response.json()
- const parseResult = StatusPageResponseSchema.safeParse(json)
-
- if (!parseResult.success) {
- console.warn('Failed to parse status page response:', parseResult.error)
- return INCIDENT_STATUS_ERROR
- }
-
- const { data } = parseResult
-
- const incidents = data.ongoing_incidents
- .filter((incident) => incident.visible)
- .map((incident) => ({
- kind: 'incident' as const,
- name: incident.name,
- status: incident.status,
- impact: incident.current_worst_impact,
- affected_components: formatAffectedComponents(incident.affected_components),
- last_update_message: incident.last_update_message ?? null,
- url: incident.url,
- }))
-
- const maintenances = data.in_progress_maintenances
- .filter((maintenance) => maintenance.visible)
- .map((maintenance) => ({
- kind: 'maintenance' as const,
- name: maintenance.name,
- status: maintenance.status,
- affected_components: formatAffectedComponents(maintenance.affected_components),
- last_update_message: maintenance.last_update_message ?? null,
- url: maintenance.url,
- started_at: maintenance.started_at,
- }))
-
- const combined = [...incidents, ...maintenances]
-
- if (combined.length === 0) {
- return {
- incidents: [],
- message: NO_ACTIVE_INCIDENTS_MESSAGE,
- }
- }
-
- const statusPageUrl = data.page_url || DEFAULT_STATUS_PAGE_URL
-
- return {
- incidents: combined,
- message: buildActiveIncidentsMessage(
- incidents.length,
- maintenances.length,
- statusPageUrl
- ),
- }
- } catch (error) {
- console.warn('Failed to fetch status page:', error)
- return INCIDENT_STATUS_ERROR
- }
- }
-
- try {
- const response = await fetch(`${baseUrl}/api/incident-status`, {
+ const response = await fetch(`${baseUrl}/api/status-page`, {
signal: timeoutSignal(abortSignal),
})
if (!response.ok) {
- console.warn('Failed to fetch incident status:', response.status)
- return INCIDENT_STATUS_ERROR
+ throw new Error(`Failed to fetch status page: ${response.status}`)
}
- const incidents: IncidentInfo[] = await response.json()
+ const json = await response.json()
+ const parseResult = StatusPageResponseSchema.safeParse(json)
- if (incidents.length === 0) {
+ if (!parseResult.success) {
+ throw new Error(`Failed to parse status page response: ${parseResult.error.message}`)
+ }
+
+ const { data } = parseResult
+
+ const incidents = data.ongoing_incidents
+ .filter((incident) => incident.visible)
+ .map((incident) => ({
+ kind: 'incident' as const,
+ name: incident.name,
+ status: incident.status,
+ impact: incident.current_worst_impact,
+ affected_components: formatAffectedComponents(incident.affected_components),
+ last_update_message: incident.last_update_message ?? null,
+ url: incident.url,
+ }))
+
+ const maintenances = data.in_progress_maintenances
+ .filter((maintenance) => maintenance.visible)
+ .map((maintenance) => ({
+ kind: 'maintenance' as const,
+ name: maintenance.name,
+ status: maintenance.status,
+ affected_components: formatAffectedComponents(maintenance.affected_components),
+ last_update_message: maintenance.last_update_message ?? null,
+ url: maintenance.url,
+ started_at: maintenance.started_at,
+ }))
+
+ const combined = [...incidents, ...maintenances]
+
+ if (combined.length === 0) {
return {
incidents: [],
message: NO_ACTIVE_INCIDENTS_MESSAGE,
}
}
- const incidentSummaries = incidents.map((incident) => ({
- name: incident.name,
- status: incident.status,
- impact: incident.impact,
- active_since: incident.active_since,
- }))
+ const statusPageUrl = data.page_url || DEFAULT_STATUS_PAGE_URL
return {
- incidents: incidentSummaries,
- message: buildActiveIncidentsMessage(incidents.length, 0, DEFAULT_STATUS_PAGE_URL),
+ incidents: combined,
+ message: buildActiveIncidentsMessage(
+ incidents.length,
+ maintenances.length,
+ statusPageUrl
+ ),
}
- } catch (error) {
- console.warn('Failed to fetch incident status:', error)
- return INCIDENT_STATUS_ERROR
+ }
+
+ const response = await fetch(`${baseUrl}/api/incident-status`, {
+ signal: timeoutSignal(abortSignal),
+ })
+
+ if (!response.ok) {
+ throw new Error(`Failed to fetch incident status: ${response.status}`)
+ }
+
+ const incidents: IncidentInfo[] = await response.json()
+
+ if (incidents.length === 0) {
+ return {
+ incidents: [],
+ message: NO_ACTIVE_INCIDENTS_MESSAGE,
+ }
+ }
+
+ const incidentSummaries = incidents.map((incident) => ({
+ name: incident.name,
+ status: incident.status,
+ impact: incident.impact,
+ active_since: incident.active_since,
+ }))
+
+ return {
+ incidents: incidentSummaries,
+ message: buildActiveIncidentsMessage(incidents.length, 0, DEFAULT_STATUS_PAGE_URL),
}
},
}),
diff --git a/apps/studio/lib/helpers.test.ts b/apps/studio/lib/helpers.test.ts
index cd867453c81..c800524d7c2 100644
--- a/apps/studio/lib/helpers.test.ts
+++ b/apps/studio/lib/helpers.test.ts
@@ -10,6 +10,7 @@ import {
formatBytes,
formatCurrency,
formatRestoreWindow,
+ getBasePathURL,
getDatabaseMajorVersion,
getDistanceLatLonKM,
getSemanticVersion,
@@ -107,6 +108,33 @@ describe('getURL', () => {
})
})
+describe('getBasePathURL', () => {
+ afterEach(() => {
+ vi.unstubAllEnvs()
+ })
+
+ it('appends the base path to the site URL', () => {
+ vi.stubEnv('NEXT_PUBLIC_SITE_URL', 'https://supabase.com')
+ expect(getBasePathURL('/dashboard')).toEqual('https://supabase.com/dashboard')
+ })
+
+ it('does not double the base path on the fallback URL', () => {
+ vi.stubEnv('NEXT_PUBLIC_SITE_URL', '')
+ vi.stubEnv('NEXT_PUBLIC_VERCEL_BRANCH_URL', '')
+ expect(getBasePathURL('/dashboard')).toEqual('https://supabase.com/dashboard')
+ })
+
+ it('strips a trailing slash before appending the base path', () => {
+ vi.stubEnv('NEXT_PUBLIC_SITE_URL', 'https://supabase.com/')
+ expect(getBasePathURL('/dashboard')).toEqual('https://supabase.com/dashboard')
+ })
+
+ it('returns the site URL when there is no base path', () => {
+ vi.stubEnv('NEXT_PUBLIC_SITE_URL', 'http://localhost:8082')
+ expect(getBasePathURL('')).toEqual('http://localhost:8082')
+ })
+})
+
describe('makeRandomString', () => {
it('should return a random string of the given length', () => {
const result = makeRandomString(10)
diff --git a/apps/studio/lib/helpers.ts b/apps/studio/lib/helpers.ts
index 2206be48975..bf6c58c60b7 100644
--- a/apps/studio/lib/helpers.ts
+++ b/apps/studio/lib/helpers.ts
@@ -2,6 +2,7 @@ import { UIEvent } from 'react'
import { v4 as _uuidV4 } from 'uuid'
import type { TablesData } from '../data/tables/tables-query'
+import { BASE_PATH } from './constants'
export const uuidv4 = () => {
return _uuidV4()
@@ -73,6 +74,16 @@ export const getURL = () => {
return url.includes('http') ? url : `https://${url}`
}
+/**
+ * Adds the base path to `getURL()` when it's missing.
+ * `https://supabase.com` → `https://supabase.com/dashboard`
+ * `https://supabase.com/dashboard` → unchanged
+ */
+export const getBasePathURL = (basePath = BASE_PATH) => {
+ const url = getURL().replace(/\/$/, '')
+ return url.endsWith(basePath) ? url : `${url}${basePath}`
+}
+
/**
* Generates a random string using alpha characters
*/
diff --git a/apps/studio/pages/api/ai/sql/generate-v4.ts b/apps/studio/pages/api/ai/sql/generate-v4.ts
index f0e4fe3998e..67209870b15 100644
--- a/apps/studio/pages/api/ai/sql/generate-v4.ts
+++ b/apps/studio/pages/api/ai/sql/generate-v4.ts
@@ -30,7 +30,7 @@ import { getTools } from '@/lib/ai/tools'
import { encodeNotebookToolError } from '@/lib/ai/tools/notebook-tools'
import { apiWrapper } from '@/lib/api/apiWrapper'
import { executeQuery } from '@/lib/api/self-hosted/query'
-import { getURL } from '@/lib/helpers'
+import { getBasePathURL } from '@/lib/helpers'
import { isServerFlagEnabled, trustedUserEmail } from '@/lib/server/configcat'
export const maxDuration = 300
@@ -192,7 +192,7 @@ async function handlePost(req: NextApiRequest, res: NextApiResponse, claims?: Jw
authorization,
aiOptInLevel,
accessToken,
- baseUrl: getURL(),
+ baseUrl: getBasePathURL(),
supportMode,
isExplorerEnabled: explorerEnabled,
useStatusPageWidget,
From 0f453c89fa0b07d926f85d0b3911a6b2dcd47fe5 Mon Sep 17 00:00:00 2001
From: Katerina Skroumpelou
Date: Mon, 5 Oct 2026 16:56:05 +0300
Subject: [PATCH 11/41] docs: add @supabase/middleware install step to server
frameworks guide (#51266)
The framework bridges in the `@supabase/server` reference import
`@supabase/middleware` directly, but the guide never said to install it.
`@supabase/server` depends on it, so npm and yarn users get it through
hoisting, while pnpm users hit "Cannot find module
'@supabase/middleware'" the moment they copy a bridge. This PR adds the
direct-dependency note to the Versions admonition, an `npm install
@supabase/middleware` line to the copy-the-bridge step, and the same
instruction to the agent migration prompt.
---
apps/docs/spec/reference/server/v1/partials/frameworks.mdx | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/apps/docs/spec/reference/server/v1/partials/frameworks.mdx b/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
index 9c1bd872b76..a6e4401b2c4 100644
--- a/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
+++ b/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
@@ -11,6 +11,8 @@ The framework adapters (`@supabase/server/adapters/*`) predate the middleware en
The bridges need `@supabase/server` 1.6.0 or later and Node 22 or later. `withRequiredClaims` shipped in 1.5.1 and the entry form of `withSupabase` in 1.6.0. Releases before 1.5.1 have no `/middleware/*` exports.
+The bridge file imports `@supabase/middleware`, so add it to your project as a direct dependency. `@supabase/server` depends on it, but a strict package manager such as pnpm does not let your code import a transitive dependency.
+
### What a bridge gives you
@@ -458,6 +460,7 @@ Do the steps in order. The auth inventory comes before any code change, because
```bash
+ npm install @supabase/middleware
mkdir -p src/lib
curl --fail -o src/lib/supabase-middleware.ts \
https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts
@@ -614,7 +617,8 @@ contributes jwtClaims: null and falls through, turning a 401 endpoint into a
auth: 'user'. Never compose withClaims() and withRequiredClaims() together;
they share the jwtClaims key and that is a compile-time conflict.
-STEP 3: FETCH THE BRIDGE. Download
+STEP 3: FETCH THE BRIDGE. Add @supabase/middleware as a direct dependency of
+the project; the bridge imports it. Then download
https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts
and save it as src/lib/supabase-middleware.ts, verbatim. Do not "improve",
condense, or drop comments from it.
From b14a577f9d23608ebffeb89cab5e5e8c16326849 Mon Sep 17 00:00:00 2001
From: Kody Jackson
Date: Mon, 5 Oct 2026 09:42:07 -0500
Subject: [PATCH 12/41] fix(docs) - remove temp redirect that should've been
removed previously (#51200)
## Problem
The `pg_partman` extension was temporarily redirected in #30149, but
then never un-redirected.
This guide became live again in
https://github.com/supabase/supabase/pull/40037/changes#diff-4db130f9070f72e3e0a3f5794a6088230e28977fe743d79af767adb18327c8ab.
(#40037)
---
apps/www/lib/redirects.js | 5 -----
1 file changed, 5 deletions(-)
diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js
index a7460cba810..a8a7159eafe 100644
--- a/apps/www/lib/redirects.js
+++ b/apps/www/lib/redirects.js
@@ -2498,11 +2498,6 @@ module.exports = [
source: '/docs/guides/database/extensions/pgrepack',
destination: '/docs/guides/database/extensions/pg_repack',
},
- {
- permanent: false,
- source: '/docs/guides/database/extensions/pg_partman',
- destination: '/docs/guides/database/extensions',
- },
{
permanent: true,
source: '/docs/guides/ai/structured-unstructured-embeddings',
From d7f422eb7e339c5b6aacf927c78fc754a676a164 Mon Sep 17 00:00:00 2001
From: Kody Jackson
Date: Mon, 5 Oct 2026 09:42:41 -0500
Subject: [PATCH 13/41] fix(www) - remove unnecessary docs redirect for
serverless drivers page (#51197)
## Problem
The
[content](https://github.com/supabase/supabase/blob/master/apps/docs/content/guides/database/connecting-to-postgres/serverless-drivers.mdx)
about serverless drivers can't be accessed b/c it's covered by a
historical redirect (but still exists in the navigation menu).
## Solution
Remove the redirect (tagging @czenko b/c I see you're closer to here
contextually and you'd be able to confirm this is correct after your
work in #49869).
---
apps/www/lib/redirects.js | 5 -----
1 file changed, 5 deletions(-)
diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js
index a8a7159eafe..ba04c799a64 100644
--- a/apps/www/lib/redirects.js
+++ b/apps/www/lib/redirects.js
@@ -3312,11 +3312,6 @@ module.exports = [
source: '/docs/guides/resources/examples',
destination: '/docs/guides/getting-started',
},
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres/serverless-drivers',
- destination: '/docs/guides/database/connecting-to-postgres',
- },
{
permanent: true,
source: '/docs/guides/monitoring-troubleshooting/troubleshooting',
From c4221ef689ef76644242f3e9c036660adce5b276 Mon Sep 17 00:00:00 2001
From: Kody Jackson
Date: Mon, 5 Oct 2026 09:45:26 -0500
Subject: [PATCH 14/41] fix(www) - redirects are never evaluated for anchor
fragments (#51198)
## Problem
Fragments are never evaluated by the server, only paths.
## Solution
Removes non-functioning redirects to reduce clutter + potential routes
to evaluate.
## Preview links
N/A, since these redirects are within the docs project but the redirect
logic is attached to the www project (this setup makes redirects
difficult to test and preview).
## Steps to test
Try out any of the removed redirects in the live site today, they won't
work.
---
apps/www/lib/redirects.js | 169 --------------------------------------
1 file changed, 169 deletions(-)
diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js
index ba04c799a64..64e1267a2ec 100644
--- a/apps/www/lib/redirects.js
+++ b/apps/www/lib/redirects.js
@@ -1478,16 +1478,6 @@ module.exports = [
source: '/docs/guides/realtime/overview',
destination: '/docs/guides/realtime',
},
- {
- permanent: true,
- source: '/docs/guides/realtime#broadcast',
- destination: '/docs/guides/realtime/broadcast',
- },
- {
- permanent: true,
- source: '/docs/guides/realtime#presence',
- destination: '/docs/guides/realtime/presence',
- },
{
permanent: true,
source: '/docs/guides/realtime/postgres-cdc',
@@ -1752,16 +1742,6 @@ module.exports = [
source: '/docs/guides/storage-cdn',
destination: '/docs/guides/storage/cdn',
},
- {
- permanent: true,
- source: '/docs/guides/functions/auth#understanding-authorization-headers',
- destination: '/docs/guides/functions/auth-headers',
- },
- {
- permanent: true,
- source: '/docs/guides/functions/auth#the-verify_jwt-platform-check',
- destination: '/docs/guides/functions/auth-headers',
- },
{
permanent: true,
source: '/docs/guides/functions/examples',
@@ -1802,75 +1782,6 @@ module.exports = [
source: '/project/:path+',
destination: 'https://supabase.com/dashboard/project/:path+',
},
- // Reorganizing pooler docs:-----------------------------
-
- //external libraries
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#integrations',
- destination: '/docs/guides/database/connecting-to-postgres#quickstart-connection-guides',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connecting-with-drizzle',
- destination: '/docs/guides/database/drizzle',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connecting-with-prisma',
- destination: '/docs/guides/database/prisma',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connecting-with-postgresjs',
- destination: '/docs/guides/database/postgres-js',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connecting-with-pgadmin',
- destination: '/docs/guides/database/pgadmin',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connecting-with-psql',
- destination: '/docs/guides/database/psql',
- },
-
- // pooling
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#connection-pooler',
- destination: '/docs/guides/database/connecting-to-postgres#connection-pooling-in-depth',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#troubleshooting-supavisor',
- destination: '/docs/guides/database/supavisor',
- },
-
- //IPv4/IPv6
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#finding-your-database-hostname',
- destination: '/docs/guides/platform/ipv4-address#finding-your-databases-ip-address',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#managing-your-ip-address',
- destination: '/docs/guides/platform/ipv4-address#supabase-and-ipv6-compatibility',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#ipv6-address',
- destination: '/docs/guides/platform/ipv4-address#supabase-and-ipv6-compatibility',
- },
- {
- permanent: true,
- source: '/docs/guides/database/connecting-to-postgres#ipv4-address',
- destination: '/docs/guides/platform/ipv4-address',
- },
- //--------------------------------------------------------
-
// START docs 2.0, moving pages in to structure
{
permanent: true,
@@ -3362,61 +3273,6 @@ module.exports = [
source: '/docs/guides/platform/org-based-billing',
destination: '/docs/guides/platform/billing-on-supabase',
},
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#how-billing-is-organized',
- destination: '/docs/guides/platform/billing-on-supabase#organization-based-billing',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#quotas-and-features',
- destination: '/docs/guides/platform/billing-on-supabase#variable-usage-fees-and-quotas',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#usage-items',
- destination: '/docs/guides/platform/billing-on-supabase#variable-usage-fees-and-quotas',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#billing-for-compute-compute-hours',
- destination: '/docs/guides/platform/manage-your-usage/compute',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#compute-pricing',
- destination: '/docs/guides/platform/manage-your-usage/compute#pricing',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#compute-credits',
- destination: '/docs/guides/platform/manage-your-usage/compute#compute-credits',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#read-replicas',
- destination: '/docs/guides/platform/manage-your-usage/read-replicas',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#project-add-ons',
- destination: '/docs/guides/platform/manage-your-usage',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#unified-egress',
- destination: '/docs/guides/platform/manage-your-usage/egress',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#included-egress-quota',
- destination: '/docs/guides/platform/manage-your-usage/egress#pricing',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#egress-dashboards',
- destination: '/docs/guides/platform/manage-your-usage/egress#usage-page',
- },
{
permanent: true,
source: '/docs/guides/platform/manage-your-usage/log-ingest',
@@ -3427,31 +3283,6 @@ module.exports = [
source: '/docs/guides/platform/manage-your-usage/log-query',
destination: '/docs/guides/platform/manage-your-usage/logs-query',
},
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#disk-size',
- destination: '/docs/guides/platform/manage-your-usage/disk-size',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#free-plan',
- destination: '/docs/guides/platform/billing-on-supabase#free-plan',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#billing-examples',
- destination: '/docs/guides/platform/billing-on-supabase',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#multiple-projects-in-a-free-plan-organization',
- destination: '/docs/guides/platform/billing-on-supabase',
- },
- {
- permanent: false,
- source: '/docs/guides/platform/org-based-billing#multiple-projects-in-a-pro-plan-organization',
- destination: '/docs/guides/platform/billing-on-supabase',
- },
{
permanent: false,
source: '/docs/guides/platform/spend-cap',
From b02890813626695eb154df7e77fd8d112443b0ec Mon Sep 17 00:00:00 2001
From: "kemal.earth" <606977+kemaldotearth@users.noreply.github.com>
Date: Mon, 5 Oct 2026 16:42:17 +0100
Subject: [PATCH 15/41] feat(studio): add never option to scoped pat expiry
(#51273)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Problem
When building scoped pat's we had omitted the option to have them never
expire.
## Solution
This re-adds the option to select "never" and it comes with the caveat
of an admonition to warn the user that they would need to manually
delete or revoke this token.
## Review instructions
Provide a clear numbered procedure that the PR reviewer can walk
through.
1. Open /account/tokens
2. Click Generate new token.
3. Open Expires in. Confirm "Never" is the last option, after "Custom",
and has no Recommended badge.
4. Select Never. A warning admonition appears directly below the expiry
row: "This token never expires — Anyone with the token keeps access
until you delete it."
5. Pick an org and project, grant one permission, click Review access.
Summary shows Expires: Never.
6. Create the token. The POST body has no expires_at, and the new row's
Expires column reads Never.
Fixes FE-4527.
Co-authored-by: Ali Waseem
---
.../Form/NewScopedTokenForm.utils.test.ts | 18 +++++++-
.../Scoped/Form/NewScopedTokenForm.utils.ts | 10 ++++-
.../AccessTokens/Scoped/Form/TokenDetails.tsx | 11 +++++
.../Scoped/NewScopedTokenSheet.test.tsx | 43 +++++++++++++++++++
4 files changed, 79 insertions(+), 3 deletions(-)
diff --git a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.test.ts b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.test.ts
index ec481a840bb..ce500e6e2eb 100644
--- a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.test.ts
+++ b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.test.ts
@@ -1,7 +1,7 @@
import dayjs from 'dayjs'
import { describe, expect, test } from 'vitest'
-import { TokenFormSchema } from './NewScopedTokenForm.utils'
+import { getExpiryDate, TokenFormSchema } from './NewScopedTokenForm.utils'
const BASE_VALUES = {
tokenName: 'test',
@@ -35,3 +35,19 @@ describe('TokenFormSchema custom expiry', () => {
)
})
})
+
+describe('TokenFormSchema never expiry', () => {
+ test('accepts the never preset without a date', () => {
+ const result = TokenFormSchema.safeParse({ ...BASE_VALUES, expiresAt: 'never' })
+ expect(result.success).toBe(true)
+ })
+})
+
+describe('getExpiryDate', () => {
+ test('returns no date for the never preset', () => {
+ expect(getExpiryDate('never')).toBeUndefined()
+ })
+ test('returns no date for the custom preset', () => {
+ expect(getExpiryDate('custom')).toBeUndefined()
+ })
+})
diff --git a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.ts b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.ts
index 1ef60b1b2f5..6aa9589f18a 100644
--- a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.ts
+++ b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/NewScopedTokenForm.utils.ts
@@ -4,7 +4,7 @@ import { z } from 'zod'
import type { PermissionMode } from '../../AccessToken.permissions'
import { getMaxCustomExpiryDate } from '../../AccessToken.utils'
-export const EXPIRY_PRESETS = ['24h', '7d', '30d', '90d', 'custom'] as const
+export const EXPIRY_PRESETS = ['24h', '7d', '30d', '90d', 'custom', 'never'] as const
export type ExpiryPreset = (typeof EXPIRY_PRESETS)[number]
export const DEFAULT_EXPIRY: ExpiryPreset = '7d'
@@ -21,9 +21,13 @@ export const EXPIRY_OPTIONS: ExpiryOption[] = [
{ value: '30d', label: '30 days' },
{ value: '90d', label: '90 days' },
{ value: 'custom', label: 'Custom' },
+ { value: 'never', label: 'Never' },
]
-/** Resolves the final ISO expiry date for a preset, or `undefined` when the caller supplies a custom date. */
+/**
+ * Resolves the final ISO expiry date for a preset. Returns `undefined` for `custom`, where the
+ * caller supplies the date, and for `never`, where the token is created without an expiry.
+ */
export const getExpiryDate = (preset: ExpiryPreset): string | undefined => {
switch (preset) {
case '24h':
@@ -34,6 +38,8 @@ export const getExpiryDate = (preset: ExpiryPreset): string | undefined => {
return dayjs().add(30, 'days').toISOString()
case '90d':
return dayjs().add(90, 'days').toISOString()
+ case 'never':
+ return undefined
default:
return undefined
}
diff --git a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/TokenDetails.tsx b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/TokenDetails.tsx
index 48d2897c301..ff25c9b8de8 100644
--- a/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/TokenDetails.tsx
+++ b/apps/studio/components/interfaces/Account/AccessTokens/Scoped/Form/TokenDetails.tsx
@@ -14,6 +14,7 @@ import {
SelectValue,
useWatch,
} from 'ui'
+import { Admonition } from 'ui-patterns/Admonition'
import {
DatePicker,
DatePickerButton,
@@ -35,6 +36,7 @@ interface TokenDetailsProps {
}
export const TokenDetails = ({ control, setValue }: TokenDetailsProps) => {
+ const expiresAt = useWatch({ control, name: 'expiresAt' })
const customExpiryDate = useWatch({ control, name: 'customExpiryDate' })
const maxExpiryDate = getMaxCustomExpiryDate().toDate()
@@ -136,6 +138,15 @@ export const TokenDetails = ({ control, setValue }: TokenDetailsProps) => {
)}
/>
+
+ {expiresAt === 'never' && (
+ | undefined
+ addAPIMock({
+ method: 'post',
+ path: '/platform/profile/scoped-access-tokens',
+ response: async ({ request }) => {
+ createBody = (await request.json()) as Record
+ return HttpResponse.json({
+ created_at: '',
+ expires_at: null,
+ id: 'plop',
+ last_used_at: null,
+ name: 'test',
+ token: 'a_token_value',
+ token_alias: '',
+ permissions: [],
+ })
+ },
+ })
+ renderSheet()
+ fireEvent.click(await screen.findByRole('button', { name: 'Generate new token' }))
+ await screen.findByRole('dialog')
+ await user.type(await screen.findByLabelText('Name'), 'test')
+ fireEvent.click(await screen.findByRole('combobox', { name: 'Expires in' }))
+ fireEvent.click(await screen.findByRole('option', { name: 'Never' }))
+ fireEvent.click(await screen.findByRole('combobox', { name: 'Organization' }))
+ fireEvent.click(await screen.findByRole('option', { name: 'Acme Production' }))
+ fireEvent.click(await screen.findByRole('combobox', { name: 'Projects' }))
+ fireEvent.click(await screen.findByRole('option', { name: 'Project 1' }))
+ await expandPermissionCategory('Project')
+ fireEvent.click(await screen.findByLabelText('Project Settings', { exact: false }))
+ fireEvent.click(await screen.findByRole('option', { name: 'Read' }))
+ fireEvent.click(await screen.findByRole('button', { name: 'Review access' }))
+ await screen.findByText('Never')
+ fireEvent.click(await screen.findByRole('button', { name: 'Create token' }))
+ await waitFor(() => expect(createBody).toBeDefined())
+ expect(createBody?.expires_at).toBeUndefined()
+ expect(mockTrack).toHaveBeenCalledWith(
+ 'access_token_created',
+ expect.objectContaining({ expiryPreset: 'never' })
+ )
+ }, 10_000)
+
test('tracks dismissal with the in-progress resourceAccess and touched state on Cancel', async () => {
renderSheet()
fireEvent.click(await screen.findByRole('button', { name: 'Generate new token' }))
From 7d04c430824d3d7630ee396a7216e27428bb55fb Mon Sep 17 00:00:00 2001
From: Jordi Enric <37541088+jordienr@users.noreply.github.com>
Date: Mon, 5 Oct 2026 17:43:15 +0200
Subject: [PATCH 16/41] fix(logs): default unified logs to otel DEBUG-228
(#51089)
## Problem
Unified Logs could start legacy BigQuery requests while ConfigCat
loaded, then switch to OTEL when the flag resolved.
## Fix
Default Unified Logs to OTEL unless otelUnifiedLogs is explicitly false.
Use that selection for list, count, chart, facet, detail, download, and
manual refresh requests. Keep BigQuery as an explicit opt-out until the
legacy backend is removed.
## Validation
- Studio typecheck passed locally.
- Existing Unified Logs utility tests passed (21 tests).
- The focused Unified Logs query test file was removed as requested;
backend-selection and manual-refresh regressions are no longer covered
by that suite.
- CI checks are running on the current head.
Tracks
[DEBUG-228](https://linear.app/supabase/issue/DEBUG-228/prevent-bq-queries-before-the-feature-flag-loads).
---
apps/studio/data/logs/get-unified-logs.ts | 5 ++---
.../data/logs/unified-log-inspection-query.ts | 4 ++--
apps/studio/data/logs/unified-logs-chart-query.ts | 9 ++++++---
apps/studio/data/logs/unified-logs-count-query.ts | 4 ++--
.../data/logs/unified-logs-facet-count-query.ts | 4 ++--
.../data/logs/unified-logs-infinite-query.ts | 14 +++++++++-----
apps/studio/routes/__root.tsx | 2 +-
7 files changed, 24 insertions(+), 18 deletions(-)
diff --git a/apps/studio/data/logs/get-unified-logs.ts b/apps/studio/data/logs/get-unified-logs.ts
index fbcc0c4dc71..f9030b2b966 100644
--- a/apps/studio/data/logs/get-unified-logs.ts
+++ b/apps/studio/data/logs/get-unified-logs.ts
@@ -1,9 +1,8 @@
import { useMutation } from '@tanstack/react-query'
-import { useFlag } from 'common'
import { toast } from 'sonner'
import { logsAllEndpointUrl, pickLogsQueryBuilder } from './logs-endpoint'
-import { getUnifiedLogsISOStartEnd } from './unified-logs-infinite-query'
+import { getUnifiedLogsISOStartEnd, useUnifiedLogsBackend } from './unified-logs-infinite-query'
import { mapUnifiedLogRow, parseUnifiedLogsQueryRows } from './unified-logs.utils'
import { getUnifiedLogsQuery } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries'
import { getUnifiedLogsQuery as getUnifiedLogsQueryBq } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries.bq'
@@ -58,7 +57,7 @@ export const useGetUnifiedLogsMutation = ({
UseCustomMutationOptions,
'mutationFn'
> = {}) => {
- const useOtel = useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useMutation({
mutationFn: (vars) => retrieveUnifiedLogs({ ...vars, useOtel: vars.useOtel ?? useOtel }),
async onSuccess(data, variables, context) {
diff --git a/apps/studio/data/logs/unified-log-inspection-query.ts b/apps/studio/data/logs/unified-log-inspection-query.ts
index 216a173fab2..43894fbe7d1 100644
--- a/apps/studio/data/logs/unified-log-inspection-query.ts
+++ b/apps/studio/data/logs/unified-log-inspection-query.ts
@@ -1,5 +1,4 @@
import { useQuery } from '@tanstack/react-query'
-import { useFlag } from 'common'
import { executeAnalyticsSql } from './execute-analytics-sql'
import { logsKeys } from './keys'
@@ -12,6 +11,7 @@ import { analyticsLiteral as lit, safeSql, type SafeLogSqlFragment } from './saf
import {
getUnifiedLogsISOStartEnd,
UNIFIED_LOGS_QUERY_OPTIONS,
+ useUnifiedLogsBackend,
} from './unified-logs-infinite-query'
import {
getAuthServiceFlowQuery,
@@ -301,7 +301,7 @@ export const useUnifiedLogInspectionQuery = (
...options
}: UseCustomQueryOptions = {}
) => {
- const useOtel = !!useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useQuery({
queryKey: [...logsKeys.serviceFlow(projectRef, search, logId), { otel: useOtel }],
queryFn: ({ signal }) =>
diff --git a/apps/studio/data/logs/unified-logs-chart-query.ts b/apps/studio/data/logs/unified-logs-chart-query.ts
index 6a9315153d1..2af1561f304 100644
--- a/apps/studio/data/logs/unified-logs-chart-query.ts
+++ b/apps/studio/data/logs/unified-logs-chart-query.ts
@@ -1,10 +1,13 @@
import { keepPreviousData, useQuery } from '@tanstack/react-query'
-import { useFlag } from 'common'
import { executeAnalyticsSql } from './execute-analytics-sql'
import { logsKeys } from './keys'
import { logsAllEndpointUrl, pickLogsQueryBuilder } from './logs-endpoint'
-import { UNIFIED_LOGS_QUERY_OPTIONS, UnifiedLogsVariables } from './unified-logs-infinite-query'
+import {
+ UNIFIED_LOGS_QUERY_OPTIONS,
+ UnifiedLogsVariables,
+ useUnifiedLogsBackend,
+} from './unified-logs-infinite-query'
import { parseLogsFilterUrlParams } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.filters'
import { getLogsChartQuery } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries'
import { getLogsChartQuery as getLogsChartQueryBq } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries.bq'
@@ -163,7 +166,7 @@ export const useUnifiedLogsChartQuery = (
...options
}: UseCustomQueryOptions = {}
) => {
- const useOtel = useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useQuery({
queryKey: [...logsKeys.unifiedLogsChart(projectRef, search), { otel: useOtel }],
queryFn: ({ signal }) => getUnifiedLogsChart({ projectRef, search, useOtel }, signal),
diff --git a/apps/studio/data/logs/unified-logs-count-query.ts b/apps/studio/data/logs/unified-logs-count-query.ts
index 0a49dfbadd6..69fae9f7817 100644
--- a/apps/studio/data/logs/unified-logs-count-query.ts
+++ b/apps/studio/data/logs/unified-logs-count-query.ts
@@ -1,5 +1,4 @@
import { useQuery } from '@tanstack/react-query'
-import { useFlag } from 'common'
import { executeAnalyticsSql } from './execute-analytics-sql'
import { logsKeys } from './keys'
@@ -8,6 +7,7 @@ import {
getUnifiedLogsISOStartEnd,
UNIFIED_LOGS_QUERY_OPTIONS,
UnifiedLogsVariables,
+ useUnifiedLogsBackend,
} from './unified-logs-infinite-query'
import { getLogsCountQuery } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries'
import { getLogsCountQuery as getLogsCountQueryBq } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries.bq'
@@ -90,7 +90,7 @@ export const useUnifiedLogsCountQuery = (
...options
}: UseCustomQueryOptions = {}
) => {
- const useOtel = useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useQuery({
queryKey: [...logsKeys.unifiedLogsCount(projectRef, search), { otel: useOtel }],
queryFn: ({ signal }) => getUnifiedLogsCount({ projectRef, search, useOtel }, signal),
diff --git a/apps/studio/data/logs/unified-logs-facet-count-query.ts b/apps/studio/data/logs/unified-logs-facet-count-query.ts
index ef26390917e..43dde999327 100644
--- a/apps/studio/data/logs/unified-logs-facet-count-query.ts
+++ b/apps/studio/data/logs/unified-logs-facet-count-query.ts
@@ -1,5 +1,4 @@
import { useQuery } from '@tanstack/react-query'
-import { useFlag } from 'common'
import { executeAnalyticsSql } from './execute-analytics-sql'
import { logsKeys } from './keys'
@@ -9,6 +8,7 @@ import {
getUnifiedLogsISOStartEnd,
UNIFIED_LOGS_QUERY_OPTIONS,
UnifiedLogsVariables,
+ useUnifiedLogsBackend,
} from './unified-logs-infinite-query'
import { getFacetCountQuery } from '@/components/interfaces/UnifiedLogs/UnifiedLogs.queries'
import {
@@ -65,7 +65,7 @@ export const useUnifiedLogsFacetCountQuery =
...options
}: UseCustomQueryOptions = {}
) => {
- const useOtel = !!useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useQuery({
queryKey: [
...logsKeys.unifiedLogsFacetCount(projectRef, facet, facetSearch, search),
diff --git a/apps/studio/data/logs/unified-logs-infinite-query.ts b/apps/studio/data/logs/unified-logs-infinite-query.ts
index cf564c9c81f..86f3c68b8cd 100644
--- a/apps/studio/data/logs/unified-logs-infinite-query.ts
+++ b/apps/studio/data/logs/unified-logs-infinite-query.ts
@@ -1,5 +1,5 @@
import { InfiniteData, keepPreviousData, useInfiniteQuery } from '@tanstack/react-query'
-import { useFlag } from 'common'
+import { useFeatureFlags } from 'common'
import { executeAnalyticsSql } from './execute-analytics-sql'
import { logsKeys } from './keys'
@@ -29,6 +29,11 @@ export type UnifiedLogsData = any
export type UnifiedLogsError = ResponseError
export type UnifiedLogsVariables = { projectRef?: string; search: QuerySearchParamsType }
+export const useUnifiedLogsBackend = () => {
+ const { otelUnifiedLogs = true } = useFeatureFlags().configcat
+ return typeof otelUnifiedLogs === 'boolean' ? otelUnifiedLogs : true
+}
+
export const getUnifiedLogsISOStartEnd = (
search: QuerySearchParamsType,
endHoursFromNow: number = 1
@@ -152,12 +157,11 @@ export const useUnifiedLogsInfiniteQuery = (
PageParam | null
> = {}
) => {
- const useOtel = useFlag('otelUnifiedLogs')
+ const useOtel = useUnifiedLogsBackend()
return useInfiniteQuery({
queryKey: [...logsKeys.unifiedLogsInfinite(projectRef, search), { otel: useOtel }],
- queryFn: ({ signal, pageParam }) => {
- return getUnifiedLogs({ projectRef, search, pageParam, useOtel }, signal)
- },
+ queryFn: ({ signal, pageParam }) =>
+ getUnifiedLogs({ projectRef, search, pageParam, useOtel }, signal),
enabled: enabled && typeof projectRef !== 'undefined',
placeholderData: keepPreviousData,
getPreviousPageParam: (firstPage) => {
diff --git a/apps/studio/routes/__root.tsx b/apps/studio/routes/__root.tsx
index de414f0b2b0..a7abe08003a 100644
--- a/apps/studio/routes/__root.tsx
+++ b/apps/studio/routes/__root.tsx
@@ -341,7 +341,7 @@ export const Route = createRootRouteWithContext()({
maintenanceMode: IS_MAINTENANCE_MODE,
hash: location.hash,
})
- if (!match) return
+ if (!match) return undefined
// `to`/`search`/`hash`, never `href`: the router treats `href` as an
// opaque (external) target, and preloading a Link whose beforeLoad
// throws `redirect({ href })` recurses forever — the preload retry
From d7cac841c4f594b36134d69d2745a085f4e68f1f Mon Sep 17 00:00:00 2001
From: Katerina Skroumpelou
Date: Mon, 5 Oct 2026 19:08:24 +0300
Subject: [PATCH 17/41] docs: state the adapter removal date in the server
frameworks guide (#51276)
The server frameworks guide still said the adapters "will be deprecated
soon" and would be "removed in a future major". They have been
deprecated since `@supabase/server` 1.9.0, with `@deprecated` tags
shipping in 1.9.1, and the removal date is December 1, 2026. This PR
updates the two sentences to state that date and drops the wording about
the release shape, which is not decided.
---
apps/docs/spec/reference/server/v1/partials/frameworks.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/apps/docs/spec/reference/server/v1/partials/frameworks.mdx b/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
index a6e4401b2c4..3e29ea0d870 100644
--- a/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
+++ b/apps/docs/spec/reference/server/v1/partials/frameworks.mdx
@@ -5,7 +5,7 @@ title: Frameworks
`@supabase/server` middleware runs inside Hono, H3, Elysia, NestJS, and TanStack Start through a bridge: one file you copy into your project. The bridge runs a `@supabase/middleware` entry array in the framework's own middleware slot. Your route handlers then read `supabase`, `jwtClaims`, and any other key the entries contribute from the place your framework keeps per-request state.
-The framework adapters (`@supabase/server/adapters/*`) predate the middleware engine. We are moving off them, and they will be deprecated soon. The bridges on this page replace them. If you use an adapter today, read "Moving off the adapters" below before you change anything. One step in that migration can open an endpoint up without an error.
+The framework adapters (`@supabase/server/adapters/*`) predate the middleware engine. They are deprecated and will be removed on December 1, 2026. The bridges on this page replace them. If you use an adapter today, read "Moving off the adapters" below before you change anything. One step in that migration can open an endpoint up without an error.
@@ -270,7 +270,7 @@ The bridge files live in the server repository under [`examples/frameworks`](htt
Each adapter solved the same problem in a framework-specific way: build a `SupabaseContext` and stash it where the handler can reach it. That meant a published entry point, a peer dependency range, and a release cycle per framework, all to wrap one call. The engine replaced the model. A middleware is now an entry, a `(handler) => handler` wrapper over the Web `Request` and `Response` pair, and `withSupabaseClient()`, `withSupabaseAdminClient()`, `withRequiredClaims()`, and the rest are ordinary entries you compose. What remains is the bridge, and it belongs in your project, not in a package that has to track your framework's major versions.
-The adapters still work in v1 and will be deprecated soon. They will be removed in a future major. `withSupabase(config, handler)` from `@supabase/server` is not part of this change.
+The adapters are deprecated. They still work today and will be removed on December 1, 2026. `withSupabase(config, handler)` from `@supabase/server` is not part of this change.
Three changes come with the migration. The first can open an endpoint up.
From 42dc4dbe90658192d9c272dac96bff7da549943d Mon Sep 17 00:00:00 2001
From: Jeremias Menichelli
Date: Mon, 5 Oct 2026 13:22:12 -0300
Subject: [PATCH 18/41] chore: Add observability to search_v2 route (#51149)
## Problem
Our new Search V2 edge function can fail, we want to know when that
happens.
## Solution
Added the common Sentry wrapping plus try/catch strategy to the edge
function so we can add alerts to our Sentry dashboards and report
channels.
## Review instructions
There's no way to reproduce this for the moment.
## Checklist
Check all before review:
- [x] I have read
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
- [x] If I wrote a new docs topic or edited an existing topic, I used
the `/write-the-docs` or `/edit-the-docs` skill, which references
[WORD_LIST](https://github.com/supabase/supabase/blob/master/apps/docs/WORD_LIST.md)
and the docs
[CONTRIBUTING](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md)
guide
## Summary by CodeRabbit
* **Bug Fixes**
* Search requests that encounter unexpected server-side errors now
receive a handled 500 response instead of an unhandled failure. Errors
returned by the search service also produce a 500 response, making
failure behavior more consistent for clients. The search query and
result-limit behavior remain unchanged.
---
apps/docs/app/api/search_v2/route.ts | 48 ++++++++++++++++++----------
1 file changed, 31 insertions(+), 17 deletions(-)
diff --git a/apps/docs/app/api/search_v2/route.ts b/apps/docs/app/api/search_v2/route.ts
index 94030052ef7..9d08c899782 100644
--- a/apps/docs/app/api/search_v2/route.ts
+++ b/apps/docs/app/api/search_v2/route.ts
@@ -1,3 +1,4 @@
+import * as Sentry from '@sentry/nextjs'
import { supabaseSearchV2 } from '~/scripts/search_v2/client'
import { type NextRequest } from 'next/server'
@@ -10,23 +11,36 @@ export async function OPTIONS() {
}
export async function GET(request: NextRequest) {
- const { searchParams } = new URL(request.url)
- const query = searchParams.get('q')?.trim()
- const limit = Number(searchParams.get('limit')) || 10
+ try {
+ const { searchParams } = new URL(request.url)
+ const query = searchParams.get('q')?.trim()
+ const limit = Number(searchParams.get('limit')) || 10
- if (!query) {
- return Response.json({ error: 'Missing q parameter' }, { status: 400, headers: corsHeaders })
+ if (!query) {
+ return Response.json({ error: 'Missing q parameter' }, { status: 400, headers: corsHeaders })
+ }
+
+ const { data, error } = await supabaseSearchV2().rpc('search_docs', {
+ query_text: query,
+ match_limit: limit,
+ })
+
+ if (error) {
+ console.error('Error running docs search v2:', error)
+ Sentry.captureException(new Error(error.message), {
+ tags: { route: 'search_v2' },
+ extra: { query, limit, error },
+ })
+ return Response.json({ error: error.message }, { status: 500, headers: corsHeaders })
+ }
+
+ return Response.json(data, { headers: corsHeaders })
+ } catch (error) {
+ console.error('Error handling docs search v2 request:', error)
+ Sentry.captureException(error, { tags: { route: 'search_v2' } })
+ return Response.json(
+ { error: 'There was an error processing your request' },
+ { status: 500, headers: corsHeaders }
+ )
}
-
- const { data, error } = await supabaseSearchV2().rpc('search_docs', {
- query_text: query,
- match_limit: limit,
- })
-
- if (error) {
- console.error('Error running docs search v2:', error)
- return Response.json({ error: error.message }, { status: 500, headers: corsHeaders })
- }
-
- return Response.json(data, { headers: corsHeaders })
}
From 53ecbf9f2ab644339050ff5a127aa266b358c806 Mon Sep 17 00:00:00 2001
From: Jeremias Menichelli
Date: Mon, 5 Oct 2026 13:22:22 -0300
Subject: [PATCH 19/41] chore: Add telemetry to search v2 user actions (#51146)
## Problem
We need to collect data from search v2 experiment usage.
## Solution
Add telemetry to search v2 modal being opened, closing, sending a query
and clicking a search v2 result.
## Review instructions
1. Open the preview link and add the search v2 flag query:
`?docs-search-v2=search-v2-active`
2. Trigger all actions mentioned above
3. Telemetry data should be sent on the network tab
## Checklist
Check all before review:
- [x] I have read
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
- [x] If I wrote a new docs topic or edited an existing topic, I used
the `/write-the-docs` or `/edit-the-docs` skill, which references
[WORD_LIST](https://github.com/supabase/supabase/blob/master/apps/docs/WORD_LIST.md)
and the docs
[CONTRIBUTING](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md)
guide
## Summary by CodeRabbit
* **Improvements**
* Documentation search activity is now recorded when the dialog opens
from the keyboard shortcut or search input, and when it closes. Search
submissions include the query and whether results were found; selected
results include their destination and the highlighted query. This adds
visibility into key search interactions without changing how search
results or highlighting work.
---
.../docs/features/SearchV2/SearchV2Dialog.tsx | 12 +++-
.../features/SearchV2/SearchV2Trigger.tsx | 30 +++++++--
packages/common/telemetry-constants.ts | 66 +++++++++++++++++++
3 files changed, 103 insertions(+), 5 deletions(-)
diff --git a/apps/docs/features/SearchV2/SearchV2Dialog.tsx b/apps/docs/features/SearchV2/SearchV2Dialog.tsx
index ee12c97675a..d475a107065 100644
--- a/apps/docs/features/SearchV2/SearchV2Dialog.tsx
+++ b/apps/docs/features/SearchV2/SearchV2Dialog.tsx
@@ -19,6 +19,7 @@ import {
} from 'ui'
import { formatHeadingPath, highlightMatches } from './SearchV2.utils'
+import { useSendTelemetryEvent } from '@/lib/telemetry'
interface SearchV2DialogProps {
open: boolean
@@ -27,6 +28,7 @@ interface SearchV2DialogProps {
export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {
const router = useRouter()
+ const sendTelemetryEvent = useSendTelemetryEvent()
const { searchState, handleDocsSearchDebounced, resetSearch } = useDocsSearchV2()
const [highlightQuery, setHighlightQuery] = useState('')
@@ -40,10 +42,14 @@ export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {
useEffect(() => {
if (searchState.status === 'results' || searchState.status === 'noResults') {
setHighlightQuery(searchState.query)
+ sendTelemetryEvent({
+ action: 'docs_search_v2_search_submitted',
+ properties: { query: searchState.query },
+ })
} else if (searchState.status === 'initial') {
setHighlightQuery('')
}
- }, [searchState])
+ }, [searchState, sendTelemetryEvent])
const results: DocsSearchV2Result[] =
'results' in searchState
@@ -61,6 +67,10 @@ export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {
}
function handleSelect(path: string) {
+ sendTelemetryEvent({
+ action: 'docs_search_v2_result_clicked',
+ properties: { resultPath: path, query: highlightQuery },
+ })
router.push(path)
onOpenChange(false)
}
diff --git a/apps/docs/features/SearchV2/SearchV2Trigger.tsx b/apps/docs/features/SearchV2/SearchV2Trigger.tsx
index ae91f54d1f8..21d9c73cda2 100644
--- a/apps/docs/features/SearchV2/SearchV2Trigger.tsx
+++ b/apps/docs/features/SearchV2/SearchV2Trigger.tsx
@@ -1,10 +1,11 @@
'use client'
import { Search } from 'lucide-react'
-import { useEffect, useState, type ReactNode } from 'react'
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
import { cn, KeyboardShortcut } from 'ui'
import { SearchV2Dialog } from './SearchV2Dialog'
+import { useSendTelemetryEvent } from '@/lib/telemetry'
interface SearchV2TriggerProps {
className?: string
@@ -13,6 +14,17 @@ interface SearchV2TriggerProps {
export function SearchV2Trigger({ className, placeholder = 'Search...' }: SearchV2TriggerProps) {
const [open, setOpen] = useState(false)
+ const sendTelemetryEvent = useSendTelemetryEvent()
+
+ const handleOpenChange = useCallback(
+ (next: boolean) => {
+ setOpen(next)
+ if (!next) {
+ sendTelemetryEvent({ action: 'docs_search_v2_closed' })
+ }
+ },
+ [sendTelemetryEvent]
+ )
useEffect(() => {
function openOnKeyDown(event: globalThis.KeyboardEvent) {
@@ -25,6 +37,10 @@ export function SearchV2Trigger({ className, placeholder = 'Search...' }: Search
event.preventDefault()
setOpen(true)
+ sendTelemetryEvent({
+ action: 'docs_search_v2_opened',
+ properties: { triggerType: 'keyboard_shortcut' },
+ })
}
}
@@ -33,7 +49,7 @@ export function SearchV2Trigger({ className, placeholder = 'Search...' }: Search
return () => {
window.removeEventListener('keydown', openOnKeyDown, { capture: true })
}
- }, [])
+ }, [sendTelemetryEvent])
return (
<>
@@ -42,7 +58,13 @@ export function SearchV2Trigger({ className, placeholder = 'Search...' }: Search
tabIndex={0}
aria-haspopup="dialog"
aria-expanded={open}
- onClick={() => setOpen(true)}
+ onClick={() => {
+ setOpen(true)
+ sendTelemetryEvent({
+ action: 'docs_search_v2_opened',
+ properties: { triggerType: 'search_input' },
+ })
+ }}
className={cn(
'group cursor-pointer',
'grow md:min-w-44 xl:min-w-56 h-[30px] rounded-md',
@@ -69,7 +91,7 @@ export function SearchV2Trigger({ className, placeholder = 'Search...' }: Search
className="hidden md:inline-flex border border-default bg-surface-300 text-foreground-lighter shadow-xs shadow-background-surface-100"
/>
-
Date: Mon, 5 Oct 2026 11:22:13 -0700
Subject: [PATCH 20/41] docs(cli): restructure and tighten the CLI getting
started guide (#50736)
Closes DOCS-1320
Was the bottom of a two-PR stack. The commit from #50680 moved here, so
that PR is closed and this one carries both changes.
## Problem
The CLI getting started guide had accumulated structural and prose
problems, none of which change what the page claims:
- **Nine flat H2 headings**, with Beta channel and Updating the Supabase
CLI sitting between installing and running. A first-time reader crossed
about 150 lines of beta and upgrade tabs before reaching `supabase
init`.
- **The introduction opened with a two-step procedure under no
heading**, listing `init` and `start` before the CLI is installed. Its
first sentence named the tool and where it runs rather than what the
reader gets.
- **Running a local Supabase project ran concept, fact, procedure, and
process together** as one stretch of prose, so the two commands the
reader has to run sat in paragraphs between the Docker background and
the first-run note.
- **Task headings mixed gerunds with imperatives:** Installing, Running,
Stopping, and Updating next to Access and Manage.
- **No navigation.** A long guide that mixes information types opened
straight into commands, with no outline of its major groups. The sidebar
contents is not a substitute: it isn't part of the document, and the
generated markdown an agent reads has no sidebar at all.
- **Four more sequences were prose.** Installing via npm, installing a
Linux package, the pre-upgrade backup, and opting out of telemetry each
had to be followed in order with nothing marking the order.
- **Smaller things:** the Studio screenshot's alt text named the topic
its heading already states, two links used "note above" and "here" as
their text, and an admonition restated where `sb_publishable_...` comes
from.
## Solution
Twelve commits, one change type each, plus a master merge and its fixup.
- **Style.** The install-method callout drops from four blocks to two
paragraphs and uses the documented `title` prop. Active voice on the
Postgres, analytics, and telemetry instructions. Descriptive link text.
Alt text that describes the Studio screenshot rather than naming it. Cut
the admonition restating `sb_publishable_...`.
- **Structure.** Beta channel and Updating the Supabase CLI move out of
the getting started path.
- **Grouping.** Local setup goes under Set up a local project, updating
and beta builds under Change your CLI version. The intro's `init` and
`start` list gets a Quickstart heading.
- **Value statement.** The opening sentence now says what the reader
gets.
- **Procedure format.** Running a local Supabase project leads with the
container runtime prerequisite, then four numbered actions, then the
first-run download as an outcome. Starting the container runtime is its
own step, since the old prose only assumed it with "with a container
runtime running".
- **Imperative headings.** Install, Run, Access, Stop, Update, Use the
beta channel.
- **Four more procedures.** npm install, Linux packages, the pre-upgrade
backup, and telemetry opt-out. The three pre-upgrade commands were one
unexplained block inside an admonition, so each step now says what its
command does. Re-enabling telemetry moves to a sentence, since it's the
reverse action rather than a step.
- **Intro navigation** listing the major groups, each line saying what
the reader gets from it.
- **Connect to a hosted project** (from #50680). A new section between
Stop local services and Change your CLI version, saying the stack runs
only on the reader's machine and nothing reaches a hosted project until
they sign in and link one, then pointing at the page that owns the
procedure. No commands. The `init` step gains a sentence saying it
creates local files only, and the value statement and intro navigation
cover the added goal.
- **Style guide and word list fixes** from an audit of the page against
`CONTRIBUTING.md` and `WORD_LIST.md`. `directory` over `folder` in
command-line contexts, `might` over `may`, present tense over `will`, a
noun after `this`, no `above` as a pointer, concrete verbs over
`manage`, no time-relative `latest`, no parentheses for supplementary
information, and an impact-first `caution` on the pre-upgrade callout.
The container runtime list becomes a table of tool and platforms, and
the group heading becomes Change your CLI version.
## Preview links
| Site | Live | Preview | Search for |
| ---- | ---- | ------- | ---------- |
| Docs |
[/docs/guides/local-development/cli/getting-started](https://supabase.com/docs/guides/local-development/cli/getting-started)
|
[/docs/guides/local-development/cli/getting-started](https://docs-git-docs-cli-getting-started-edits-supabase.vercel.app/docs/guides/local-development/cli/getting-started)
| Change your CLI version, Connect to a hosted project |
## Manual testing
1. Open the docs preview link above.
2. Read the introduction. It opens with a value statement, then links
the four major groups. Under Quickstart, the install-method callout
explains how the install method changes the command you run.
3. Read the On this page list. It nests: Quickstart, Set up a local
project with four sections under it, Change your CLI version with two
sections under it, Telemetry, Learn more.
4. Check Run a local Supabase project renders four numbered steps, with
code blocks inside steps 3 and 4. Check the npm tab of Install the
Supabase CLI renders three, and How to opt out renders two.
5. Load the page at `#installing-the-supabase-cli`, `#beta-channel`, and
`#updating-the-supabase-cli`. All three land on their sections despite
the renamed headings.
6. Load the legacy path
`/docs/guides/cli/getting-started#updating-the-supabase-cli`. It
redirects to the current path and keeps the fragment.
7. Check the introduction's group list includes Connect to a hosted
project, and that the section appears in the On this page list between
Stop local services and Change your CLI version.
8. Check that section is two sentences and a pointer, with no commands.
9. In Run a local Supabase project, select the "Connect to a hosted
project" link in step 3. The page scrolls to that section.
10. Follow both outbound links from the new section and confirm they
resolve, including the `#configure-github-actions` fragment.
## Summary by CodeRabbit
* **Documentation**
* Reorganized the local development guide with a clearer quickstart,
setup steps, service access instructions, and CLI version guidance.
* Expanded installation examples to include bun and clarified
package-runner commands.
* Clarified upgrade, backup, container cleanup, and telemetry
instructions.
* Added a reference to the Microsoft Writing Style Guide.
---
.../local-development/cli/getting-started.mdx | 448 ++++++++++--------
apps/docs/style-guide/WORD_LIST.md | 4 +
2 files changed, 246 insertions(+), 206 deletions(-)
diff --git a/apps/docs/content/guides/local-development/cli/getting-started.mdx b/apps/docs/content/guides/local-development/cli/getting-started.mdx
index 81f7b228c27..70b24e7c33d 100644
--- a/apps/docs/content/guides/local-development/cli/getting-started.mdx
+++ b/apps/docs/content/guides/local-development/cli/getting-started.mdx
@@ -4,25 +4,34 @@ description: 'The Supabase CLI provides tools to develop your project locally, d
subtitle: 'Develop locally, deploy to the Supabase Platform, and set up CI/CD workflows'
---
-The Supabase CLI enables you to run the entire Supabase stack locally, on your machine or in a CI environment. With two commands, you can set up and start a new local project:
+The Supabase CLI runs the entire Supabase stack on your own machine or in a CI environment, so you can build and test locally, then connect your project to a hosted one when you're ready to deploy.
-1. `supabase init` to create a new local project
-2. `supabase start` to launch the Supabase services
+- [Quickstart](#quickstart) is the two-command version, if you already have the CLI and a container runtime.
+- [Set up a local project](#set-up-a-local-project) installs the CLI and brings the stack up on your machine. Start here if you haven't run it before.
+- [Connect to a hosted project](#connect-to-a-hosted-project) links your local directory to a project on the Supabase Platform.
+- [Change your CLI version](#change-your-cli-version) updates the CLI and switches between stable and pre-release builds.
+- [Telemetry](#telemetry) covers what the CLI collects and how to opt out.
-
+## Quickstart
-There are two ways to install the CLI, and they change the command you type:
+With two commands, you can set up and start a new local project:
-- **Project dependency** with `npm`, `pnpm`, or `yarn` installs the CLI into a single project (there is no global `supabase` command with this method). Run it through your package runner instead, for example `npx supabase `.
-- **Global install** with Homebrew, Scoop, or Linux packages. Run commands as `supabase `.
+1. Run `supabase init` to create a new local project.
+2. Run `supabase start` to launch the Supabase services.
-Either way, the CLI is **project-scoped**: most commands (including `start`) expect to run inside a directory that has been initialized with `supabase init`, which creates the `supabase/` folder and `config.toml`. Run `init` first, then the other commands from the same directory.
+
-The rest of this page writes examples as `supabase `; translate them to `npx supabase ` if you installed the CLI as a project dependency.
+How you run a CLI command depends on how you install it. Homebrew, Scoop, and the Linux packages give you a global `supabase` command. Installing with npm, pnpm, yarn, or bun adds the CLI to one project instead, so you run it through your package runner as `npx supabase `. This page writes every example as `supabase `.
+
+The CLI is project-scoped either way. Most commands, including `start`, expect a directory that `supabase init` has already set up with a `supabase` directory and a `config.toml`. Run `init` first, then the rest from the same directory.
-## Installing the Supabase CLI
+## Set up a local project
+
+Install the CLI, bring the Supabase stack up on your machine, and stop it when you're done.
+
+### Install the Supabase CLI [#installing-the-supabase-cli]
`; translate them to
>
-Install the CLI as a project dev dependency. This adds it to a single project rather than installing a global command:
+1. Install the CLI as a project dev dependency. This command adds the CLI to a single project rather than installing a global command:
-```sh
-npm install supabase --save-dev
-# or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase
-```
+ ```sh
+ npm install supabase --save-dev
+ # or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase
+ ```
-Pin the version in `package.json` so your whole team uses the same CLI version. Then run every command through your package runner:
+2. Pin the version in `package.json` so your whole team uses the same CLI version.
-```sh
-npx supabase --help
-# or: pnpm supabase / yarn supabase / bunx supabase
-```
+3. Run the CLI through your package runner:
+
+ ```sh
+ npx supabase --help
+ # or: pnpm supabase / yarn supabase / bunx supabase
+ ```
@@ -86,19 +97,193 @@ brew install supabase/tap/supabase
#### Linux packages
Linux packages are provided in [Releases](https://github.com/supabase/cli/releases).
-To install, download the `.apk`/`.deb`/`.rpm` file depending on your package manager
-and run one of the following:
-- `sudo apk add --allow-untrusted <...>.apk`
-- `sudo dpkg -i <...>.deb`
-- `sudo rpm -i <...>.rpm`
+1. Download the `.apk`, `.deb`, or `.rpm` file for your package manager.
+2. Install the package:
+ - `sudo apk add --allow-untrusted <...>.apk`
+ - `sudo dpkg -i <...>.deb`
+ - `sudo rpm -i <...>.rpm`
-## Beta channel
+### Run a local Supabase project [#running-a-local-supabase-project]
-Pre-release CLI builds ship from the development branch (`X.Y.Z-beta.N` versions). Use the npm `beta` dist-tag, or install `supabase-beta` via Homebrew / Scoop (separate packages from stable).
+The most common thing you'll do with the CLI is run the full Supabase stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. On Windows and Linux, follow the official guide to install and configure [Docker Desktop](https://docs.docker.com/desktop).
+
+On macOS, we recommend [OrbStack](https://orbstack.dev/) instead of Docker Desktop. It's a drop-in replacement that handles extended file attributes (xattrs) on mounted volumes and container networking more reliably than Docker Desktop. It also starts faster and uses less CPU, memory, and disk, which makes a noticeable difference when running the full Supabase stack.
+
+Alternatively, you can use a different container tool that offers Docker-compatible APIs:
+
+| Tool | Platforms |
+| --------------------------------------------- | --------------------- |
+| [Rancher Desktop](https://rancherdesktop.io/) | macOS, Windows, Linux |
+| [Podman](https://podman.io/) | macOS, Windows, Linux |
+| [colima](https://github.com/abiosoft/colima) | macOS |
+
+To bring the stack up:
+
+1. Start your container runtime.
+
+2. Open a terminal in the directory where you want to create your project.
+
+3. Initialize the project:
+
+ ```bash
+ supabase init
+ ```
+
+ The command creates a `supabase` directory, which is safe to commit to version control. `init` creates local files only: it doesn't sign you in or connect the directory to a project on the Supabase Platform. To connect one, see [Connect to a hosted project](#connect-to-a-hosted-project).
+
+4. Start the Supabase services from the same directory:
+
+ ```bash
+ supabase start
+ ```
+
+
+
+If you installed the CLI as a project dependency with npm, pnpm, yarn, or bun, run `npx supabase init` and `npx supabase start` instead. See [Install the Supabase CLI](#installing-the-supabase-cli).
+
+
+
+The first run takes time while the CLI downloads the Docker images. It pulls the entire Supabase stack, plus a few extra images useful for local development, such as a local SMTP server and a database diff tool.
+
+### Access your project's services
+
+After all the Supabase services are running, the CLI prints your local credentials. The output looks like this, with the URLs and keys you use in your local project:
+
+```
+Started supabase local development setup.
+
+╭──────────────────────────────────────╮
+│ 🔧 Development Tools │
+├─────────┬────────────────────────────┤
+│ Studio │ http://127.0.0.1:54323 │
+│ Mailpit │ http://127.0.0.1:54324 │
+│ MCP │ http://127.0.0.1:54321/mcp │
+╰─────────┴────────────────────────────╯
+
+╭──────────────────────────────────────────────────────╮
+│ 🌐 APIs │
+├────────────────┬─────────────────────────────────────┤
+│ Project URL │ http://127.0.0.1:54321 │
+│ REST │ http://127.0.0.1:54321/rest/v1 │
+│ GraphQL │ http://127.0.0.1:54321/graphql/v1 │
+│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
+╰────────────────┴─────────────────────────────────────╯
+
+╭───────────────────────────────────────────────────────────────╮
+│ ⛁ Database │
+├─────┬─────────────────────────────────────────────────────────┤
+│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
+╰─────┴─────────────────────────────────────────────────────────╯
+
+╭──────────────────────────────────────────────────────────────╮
+│ 🔑 Authentication Keys │
+├─────────────┬────────────────────────────────────────────────┤
+│ Publishable │ sb_publishable_... │
+│ Secret │ sb_secret_... │
+╰─────────────┴────────────────────────────────────────────────╯
+```
+
+
+
+
+```sh
+# Default URL:
+http://localhost:54323
+```
+
+The local development environment includes Supabase Studio, a graphical interface for querying and editing your database.
+
+
+
+
+
+
+```sh
+# Default URL:
+postgresql://postgres:postgres@localhost:54322/postgres
+```
+
+Access the local Postgres instance with [`psql`](https://www.postgresql.org/docs/current/app-psql.html) or any other Postgres client, such as [pgAdmin](https://www.pgadmin.org/). For example:
+
+```bash
+psql 'postgresql://postgres:postgres@localhost:54322/postgres'
+```
+
+
+
+To access the database from an edge function in your local Supabase setup, replace `localhost` with `host.docker.internal`.
+
+
+
+
+
+
+```sh
+# Default URL:
+http://localhost:54321
+```
+
+If you are accessing these services without the client libraries, you might need to pass the client keys as an `Authorization` header. Learn more about [JWT headers](/docs/learn/auth-deep-dive/auth-deep-dive-jwts).
+
+```sh
+curl 'http://localhost:54321/rest/v1/' \
+ -H "apikey: sb_publishable_..."
+
+http://localhost:54321/rest/v1/ # REST (PostgREST)
+http://localhost:54321/realtime/v1/ # Realtime
+http://localhost:54321/storage/v1/ # Storage
+http://localhost:54321/auth/v1/ # Auth (GoTrue)
+```
+
+
+
+
+Local logs rely on the Supabase Analytics Server, which reads the Docker logging driver. On Linux and macOS, mount the `/var/run/docker.sock` domain socket. On Windows, expose the `tcp://localhost:2375` daemon socket. Configure the socket manually after [installing the CLI](#installing-the-supabase-cli).
+
+
+
+For advanced logs analysis using the Logs Explorer, use the BigQuery backend instead of the default Postgres backend. See [Using the BigQuery backend](/docs/reference/self-hosting-analytics/introduction#using-the-bigquery-backend).
+
+
+
+All logs are stored in the local database under the `_analytics` schema.
+
+
+
+
+### Stop local services [#stopping-local-services]
+
+When you finish working, stop the stack. Stopping doesn't reset your local database:
+
+```bash
+supabase stop
+```
+
+With the default ports, `supabase start` runs one local project per machine, because every project's `config.toml` uses the same ports. To run several local projects or git worktrees at the same time, see [Running multiple local projects](/docs/guides/local-development/running-multiple-local-projects).
+
+## Connect to a hosted project
+
+The stack you started in [Run a local Supabase project](#running-a-local-supabase-project) runs only on your machine. Nothing reaches a hosted project until you sign in to the CLI and link your local directory to one.
+
+For the steps, see [Pushing to a remote project](/docs/guides/local-development/cli-workflows#pushing-to-a-remote-project). To run deployments from CI, see [Configure GitHub Actions](/docs/guides/deployment/managing-environments#configure-github-actions).
+
+## Change your CLI version
+
+These sections cover the CLI itself rather than your local project.
+
+### Use the beta channel [#beta-channel]
+
+Pre-release CLI builds ship from the development branch and are versioned `X.Y.Z-beta.N`. Use the npm `beta` dist-tag, or install `supabase-beta` with Homebrew or Scoop. `supabase-beta` is a separate package from `supabase`.
-## Updating the Supabase CLI
+### Update the Supabase CLI [#updating-the-supabase-cli]
-When a new [version](https://github.com/supabase/cli/releases) is released, you can update the CLI using the same channels.
+Update the CLI with the same package manager you installed it with. See the [CLI releases page](https://github.com/supabase/cli/releases) for available versions.
.apk`
- `sudo dpkg -i <...>.deb`
@@ -231,181 +416,31 @@ brew upgrade supabase-beta
-If you have any Supabase containers running locally, stop them and delete their data volumes before proceeding with the upgrade. This ensures that Supabase managed services can apply new migrations on a clean state of the local database.
+If you have any Supabase containers running locally, stop them and delete their data volumes before upgrading. Deleting the volumes lets Supabase managed services apply new migrations on a clean local database.
-
+
-Remember to save any local schema and data changes before stopping because the `--no-backup` flag will delete them.
-
-```sh
-supabase db diff -f my_schema
-supabase db dump --local --data-only > supabase/seed.sql
-supabase stop --no-backup
-```
+`supabase stop --no-backup` deletes your local schema and data changes. Save them first.
-## Running a local Supabase project
+1. Save local schema changes as a migration:
-The most common thing you'll do with the CLI is run the full Supabase stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. On Windows and Linux, follow the official guide to install and configure [Docker Desktop](https://docs.docker.com/desktop).
+ ```sh
+ supabase db diff -f my_schema
+ ```
-On macOS, we recommend [OrbStack](https://orbstack.dev/) instead of Docker Desktop. It's a drop-in replacement that handles extended file attributes (xattrs) on mounted volumes and container networking more reliably than Docker Desktop. It also starts faster and uses less CPU, memory, and disk, which makes a noticeable difference when running the full Supabase stack.
+2. Dump local data to your seed file:
-Alternately, you can use a different container tool that offers Docker compatible APIs.
+ ```sh
+ supabase db dump --local --data-only > supabase/seed.sql
+ ```
-- [Rancher Desktop](https://rancherdesktop.io/) (macOS, Windows, Linux)
-- [Podman](https://podman.io/) (macOS, Windows, Linux)
-- [colima](https://github.com/abiosoft/colima) (macOS)
+3. Stop the containers and delete their data volumes:
-With a container runtime running, go to the folder where you want to create your project and initialize it:
-
-```bash
-supabase init
-```
-
-This creates a new `supabase` folder. It's safe to commit this folder to version control.
-
-Now, from the same folder, start the Supabase stack:
-
-```bash
-supabase start
-```
-
-
-
-If you installed the CLI as a project dependency (npm, pnpm, yarn, or bun), run these as `npx supabase init` and `npx supabase start` instead. See the [note above](#installing-the-supabase-cli).
-
-
-
-This takes time on your first run because the CLI needs to download the Docker images to your local machine. The CLI includes the entire Supabase stack, and a few additional images useful for local development (like a local SMTP server and a database diff tool).
-
-## Access your project's services
-
-Once all the Supabase services are running, you'll see output containing your local Supabase credentials. It should look like the below, with urls and keys that you use in your local project:
-
-```
-Started supabase local development setup.
-
-╭──────────────────────────────────────╮
-│ 🔧 Development Tools │
-├─────────┬────────────────────────────┤
-│ Studio │ http://127.0.0.1:54323 │
-│ Mailpit │ http://127.0.0.1:54324 │
-│ MCP │ http://127.0.0.1:54321/mcp │
-╰─────────┴────────────────────────────╯
-
-╭──────────────────────────────────────────────────────╮
-│ 🌐 APIs │
-├────────────────┬─────────────────────────────────────┤
-│ Project URL │ http://127.0.0.1:54321 │
-│ REST │ http://127.0.0.1:54321/rest/v1 │
-│ GraphQL │ http://127.0.0.1:54321/graphql/v1 │
-│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
-╰────────────────┴─────────────────────────────────────╯
-
-╭───────────────────────────────────────────────────────────────╮
-│ ⛁ Database │
-├─────┬─────────────────────────────────────────────────────────┤
-│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
-╰─────┴─────────────────────────────────────────────────────────╯
-
-╭──────────────────────────────────────────────────────────────╮
-│ 🔑 Authentication Keys │
-├─────────────┬────────────────────────────────────────────────┤
-│ Publishable │ sb_publishable_... │
-│ Secret │ sb_secret_... │
-╰─────────────┴────────────────────────────────────────────────╯
-```
-
-
-
-
-```sh
-# Default URL:
-http://localhost:54323
-```
-
-The local development environment includes Supabase Studio, a graphical interface for working with your database.
-
-
-
-
-
-
-```sh
-# Default URL:
-postgresql://postgres:postgres@localhost:54322/postgres
-```
-
-The local Postgres instance can be accessed through [`psql`](https://www.postgresql.org/docs/current/app-psql.html) or any other Postgres client, such as [pgAdmin](https://www.pgadmin.org/). For example:
-
-```bash
-psql 'postgresql://postgres:postgres@localhost:54322/postgres'
-```
-
-
-
-To access the database from an edge function in your local Supabase setup, replace `localhost` with `host.docker.internal`.
-
-
-
-
-
-
-```sh
-# Default URL:
-http://localhost:54321
-```
-
-If you are accessing these services without the client libraries, you may need to pass the client keys as an `Authorization` header. Learn more about [JWT headers](/docs/learn/auth-deep-dive/auth-deep-dive-jwts).
-
-```sh
-curl 'http://localhost:54321/rest/v1/' \
- -H "apikey: sb_publishable_..."
-
-http://localhost:54321/rest/v1/ # REST (PostgREST)
-http://localhost:54321/realtime/v1/ # Realtime
-http://localhost:54321/storage/v1/ # Storage
-http://localhost:54321/auth/v1/ # Auth (GoTrue)
-```
-
-
-
-`sb_publishable_...` is the publishable key output when you run the command `supabase start`.
-
-
-
-
-
-
-Local logs rely on the Supabase Analytics Server which accesses the docker logging driver by either volume mounting `/var/run/docker.sock` domain socket on Linux and macOS, or exposing `tcp://localhost:2375` daemon socket on Windows. These settings must be configured manually after [installing](/docs/guides/local-development/cli/getting-started#installing-the-supabase-cli) the Supabase CLI.
-
-
-
-For advanced logs analysis using the Logs Explorer, it is advised to use the BigQuery backend instead of the default Postgres backend. Read about the steps [here](/docs/reference/self-hosting-analytics/introduction#using-the-bigquery-backend).
-
-
-
-All logs are stored in the local database under the `_analytics` schema.
-
-
-
-
-## Stopping local services
-
-When you are finished working on your Supabase project, you can stop the stack (without resetting your local database):
-
-```bash
-supabase stop
-```
-
-With the default ports, `supabase start` runs one local project per machine, because every project's `config.toml` uses the same ports. To run several local projects or git worktrees at the same time, see [Running multiple local projects](/docs/guides/local-development/running-multiple-local-projects).
+ ```sh
+ supabase stop --no-backup
+ ```
## Telemetry
@@ -413,18 +448,19 @@ The Supabase CLI collects telemetry data about general usage. Participating in t
### How to opt out
-You can disable telemetry by running:
+1. Disable telemetry:
-```bash
-supabase telemetry disable
-```
+ ```bash
+ supabase telemetry disable
+ ```
-You can check the current status and re-enable with:
+2. Confirm the current setting:
-```bash
-supabase telemetry status
-supabase telemetry enable
-```
+ ```bash
+ supabase telemetry status
+ ```
+
+To enable telemetry again, run `supabase telemetry enable`.
You can also opt out using the `SUPABASE_TELEMETRY_DISABLED=1` environment variable. The broader `DO_NOT_TRACK=1` convention is also respected.
diff --git a/apps/docs/style-guide/WORD_LIST.md b/apps/docs/style-guide/WORD_LIST.md
index 61470ca93bc..050a71180fb 100644
--- a/apps/docs/style-guide/WORD_LIST.md
+++ b/apps/docs/style-guide/WORD_LIST.md
@@ -982,6 +982,10 @@ Don't use these phrases:
Don't use _tl;dr_, _ymmv_, _rtfm_, _imo_, or _fwiw_. Write out the
meaning or remove the aside.
+## Further reference
+
+- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
+
## Attribution
Portions of this word list are modifications based on work created and shared by
From 09a245d72de97bf72443cd5f878a849673103516 Mon Sep 17 00:00:00 2001
From: Alaister Young
Date: Mon, 5 Oct 2026 12:05:21 -0700
Subject: [PATCH 21/41] [FE-4520] fix(studio): hide Realtime setup for
published tables (#51152)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The Realtime Inspector now checks the Realtime publication before
showing setup guidance. Projects with published tables get the
join-channel view even before this Inspector session receives any
messages; unconfigured projects keep the setup guide.
Setup guidance also stays hidden while publications are loading or
unavailable. Joining a channel and displaying received messages retain
their existing behavior.
Addresses
[FE-4520](https://linear.app/supabase/issue/FE-4520/realtime-inspector-ui-implies-i-am-not-using-realtime-despite-already).
## To test
- With no tables in `supabase_realtime`, open Realtime → Inspector and
confirm the setup guide appears.
- Enable Realtime on a table and confirm a client receives a database
change. Open the Inspector without joining a channel: it should show
“Join a channel to start listening to messages” and no setup guide.
- Join a channel, trigger a table change, and check the event and
payload appear. Stop listening and confirm messages remain visible.
- Open Policies, then return to the Inspector and confirm the setup
guide stays hidden for the configured project.
- Join a broadcast-only channel with no incoming messages and confirm
the messages view appears immediately.
## Validation
Reproduced the original prompt locally with a working Realtime table,
then verified the fix in the browser, including an independent client
subscription, a live INSERT in the Inspector, navigation, stopping, and
the unconfigured state. Temporary test data and services were cleaned
up.
All nine new regression tests pass; four fail against the original code.
Typecheck, formatting, lint ratchet, Knip, and the case-sensitivity
check pass. The full Studio suite passed 7,799 tests with one unrelated
Explorer test failure; that test passed on a focused rerun alongside the
Inspector tests.
## Summary by CodeRabbit
* **Bug Fixes**
* The Realtime inspector keeps the messages view visible while
publication status is loading or unavailable, and when a channel is
joined or messages are present.
* Setup guidance appears only after publications load successfully and
confirm that Realtime is unavailable, with no channel or messages to
show. This includes cases where there are no publications, the Realtime
publication has no tables, or only a differently named publication
exists.
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Co-authored-by: Joshen Lim
Co-authored-by: Claude Sonnet 5
---
.../Realtime/Inspector/MessagesTable.tsx | 2 +-
.../Inspector/RealtimeInspector.test.tsx | 182 ++++++++++++++++++
.../interfaces/Realtime/Inspector/index.tsx | 10 +-
e2e/studio/utils/realtime-helpers.ts | 4 +-
4 files changed, 191 insertions(+), 7 deletions(-)
create mode 100644 apps/studio/components/interfaces/Realtime/Inspector/RealtimeInspector.test.tsx
diff --git a/apps/studio/components/interfaces/Realtime/Inspector/MessagesTable.tsx b/apps/studio/components/interfaces/Realtime/Inspector/MessagesTable.tsx
index 555a8dc749f..1c30f3cec67 100644
--- a/apps/studio/components/interfaces/Realtime/Inspector/MessagesTable.tsx
+++ b/apps/studio/components/interfaces/Realtime/Inspector/MessagesTable.tsx
@@ -184,7 +184,7 @@ const MessagesTable = ({
Inspector messages
}))
+vi.mock('./EmptyRealtime', () => ({
+ EmptyRealtime: () => ,
+}))
+vi.mock('./SendMessageModal', () => ({ SendMessageModal: () => null }))
+
+const PROJECT: ProjectDetail = {
+ cloud_provider: 'AWS',
+ connectionString: 'postgresql://postgres@localhost:5432/postgres',
+ db_host: 'db.default.supabase.co',
+ high_availability: false,
+ id: 1,
+ inserted_at: '2026-01-01T00:00:00.000Z',
+ integration_source: null,
+ is_branch_enabled: false,
+ is_hibernating: false,
+ is_physical_backups_enabled: false,
+ name: 'Test project',
+ organization_id: 1,
+ ref: 'default',
+ region: 'us-east-1',
+ restUrl: 'https://default.supabase.co/rest/v1',
+ status: 'ACTIVE_HEALTHY',
+ subscription_id: 'subscription-1',
+ updated_at: '2026-01-01T00:00:00.000Z',
+}
+
+const publication = (
+ tables: PGPublication['tables'],
+ name = 'supabase_realtime'
+): PGPublication => ({
+ id: 1,
+ name,
+ owner: 'postgres',
+ publish_insert: true,
+ publish_update: true,
+ publish_delete: true,
+ publish_truncate: true,
+ tables,
+})
+
+function mockPublications(publications: PGPublication[]) {
+ addAPIMock({
+ method: 'post',
+ path: '/platform/pg-meta/:ref/query',
+ response: () => HttpResponse.json+ When you run a game as a service, you worry about what's going to break while you're not at work, + over a weekend or on holiday. Just knowing how battle-tested Supabase is takes a level of stress + off. ++ +[Flick](https://flick.games) is an indie games studio based in the UK. Ian Masters, the studio's founder, has been making video games for close to three decades. Alongside engineer Alan Thomson, he now runs two live products on Supabase: Art of Solitaire, a card game on iOS, Android, and Steam Early Access, and Goalman, a very silly penalty shootout browser game that launched in time for the World Cup. + +Art of Solitaire has built an audience that differs from the typical solitaire crowd. Where most classic solitaire games skew 65 and older, Flick's version pulls in players aged 18 to 25, largely on the strength of its art. The studio has commissioned more than 70 artists from around the world to design its card decks, adding a new one every month, including collaborations for Pride, Black History Month, and International Women's Month, and more. + +## The challenge + +Before landing on its current setup, Flick pieced together a different backend service for each platform, and none of them held up. Google Play Game Services and Game Center covered authentication on mobile, but treated Android and iOS as separate identities entirely, with no way to recognize the same player moving between them. + +
+ Android users could only authenticate on Android. If they also had an iOS device, tough. We don't + know that they're the same person, and that's a pretty big problem. ++ +Flick used ChilliConnect for backups and save data until Unity acquired it and shut the service down, forcing a move. The team evaluated Firebase, but it didn't fit how they worked, so they settled on each platform's native option: iCloud on iOS and Google Play on Android. That held up while Flick was mobile-only, but it was never cross-platform, and once Steam arrived as a third platform it stopped making sense. + +## Why they chose Supabase + +Adding a third channel meant Flick didn't want to bolt on a third separate backend service. Supabase covered authentication, database, and storage together, and the team could see it working almost immediately. + +
+ It was just really easy to use. It had authentication, it had all the database stuff, it had + storage. It ticked loads of boxes very quickly. ++ +## How Flick runs on Supabase + +Art of Solitaire's authentication now runs on a passwordless email flow through Supabase Auth, with no passwords stored anywhere. The studio recently migrated from a magic link players clicked in their email to a one-time code players type in directly, a change made to better support platforms like Steam Deck, which doesn't have its own email client. + +
+ We were actually able to have both services live at the same time. So as people update the game + from one version to another, it never breaks, because both services are working simultaneously. ++ +Rather than adopt a separate SDK for each platform, Flick built one lightweight Lua wrapper around Supabase's REST endpoints and reused it across iOS, Android, and Steam, so adding a platform never means maintaining another SDK in parallel. + +
+ Supabase having REST endpoints is massive. There are some tools where they're SDK only, and that's + problematic when you're cross-platform, because you're suddenly managing two, three, four SDKs, + and they're not always kept in sync. Whereas REST endpoints with our Lua code base means we just + write a very lightweight wrapper and we're done. It's very easy for us to expand to other + platforms. ++ +Steam added its own challenge: unlike iOS and Android, it has no native way to check whether a player has already made an in-game purchase. Flick now records every Steam transaction directly in Supabase, and even players who haven't logged in are tracked as anonymous Supabase users so the game still has somewhere to store their activity. + +## Keeping three platforms and one experience in sync + +Players who move between a phone and Steam expect their progress and purchases to already be there, so Flick built merge logic that reconciles saves across devices on login. Progress adds up rather than overwrites: currency collected on two different devices adds together instead of picking one number, and progress made offline catches up correctly once a device reconnects. + +
+ That requires some sort of record of those things on all the devices that can then be married up + and turned into one single source of truth. We were able to do that through the Supabase database + tables. ++ +Remote delivery solved a different problem for Flick: shipping new content without shipping a new build. Art of Solitaire's card decks used to ship embedded inside the game binary, which meant a store submission and approval cycle every time a new deck went out, and the team often had to turn a deck around on a tight deadline when an artist delivered late in the month. The studio now serves deck data remotely through Supabase, so a new deck can go out without a single update to the game itself. + +
+ We can now roll decks out remotely. We don't have to update the game at all. It was always a big + source of stress that's now gone. ++ +## The results + +Flick is two people running two live games, with backend work in place that would normally take a much bigger team to build. + +
+ If we were to write all of this authentication, cloud saves, and remote config ourselves, the + stuff we use Supabase for, I think it's realistic to say we wouldn't have all of those features + built out for users. We've got limited resources so Supabase has really helped us be way ahead + from when we started. ++ +For a team this size, cost matters every bit as much as capability. + +
+ You're building a game, you hope it will be successful and grow, but the truth is most games + won't. Supabase's pricing is really accessible, and it feels like you're intentionally trying to + support smaller developers with that kind of structure. ++ +## What's next + +Flick's next moves build on the same backend. The team is opening up an artist portal on its own website, powered by Supabase. The artists it commissions will be able to log in to test their assets today and, soon, upload them directly. Players will get a similar login to view their card collection outside the game itself. + +Separately, Art of Solitaire is collaborating with another Steam game, Forbidden Solitaire, still with a two-person team behind it. diff --git a/apps/www/public/images/blog/avatars/alan-thomson-flick.jpg b/apps/www/public/images/blog/avatars/alan-thomson-flick.jpg new file mode 100644 index 0000000000000000000000000000000000000000..793c9c5e0e85093f16da2be72399d2863a2a6f07 GIT binary patch literal 67305 zcmb5UWmFtdvo<>D;O?#i0fM_b0S5OV0S0$>4ek(Z1_|zNL4t