diff --git a/apps/docs/spec/common-client-libs-sections.json b/apps/docs/spec/common-client-libs-sections.json index 41b1c3e611f..dab675d959b 100644 --- a/apps/docs/spec/common-client-libs-sections.json +++ b/apps/docs/spec/common-client-libs-sections.json @@ -1548,13 +1548,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "createindex", "title": "Creates a new vector index in this bucket", @@ -1590,13 +1583,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "throwonerror", "title": "Enable throwing errors instead of returning them in the response", @@ -1604,13 +1590,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "createindex", "title": "Creates a new vector index within a bucket", @@ -1646,20 +1625,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "from", "title": "Perform file operation in a bucket", @@ -1667,13 +1632,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "throwonerror", "title": "Enable throwing errors instead of returning them", @@ -1681,13 +1639,6 @@ "product": "storage", "type": "function" }, - { - "id": "constructor", - "title": "Create a Storage client instance", - "slug": "storage-constructor", - "product": "storage", - "type": "function" - }, { "id": "exists", "title": "Checks the existence of a file", diff --git a/apps/docs/spec/supabase_js_v2.yml b/apps/docs/spec/supabase_js_v2.yml index 3a6dec4319f..3e05e8cdf79 100644 --- a/apps/docs/spec/supabase_js_v2.yml +++ b/apps/docs/spec/supabase_js_v2.yml @@ -3,7 +3,7 @@ info: id: reference/supabase-js title: Supabase Javascript Client description: | - + Supabase JavaScript. definition: spec/enrichments/tsdoc_v2/combined.json specUrl: https://github.com/supabase/supabase/edit/master/apps/docs/spec/supabase_js_v2.yml @@ -14,37 +14,54 @@ info: functions: - id: initializing title: Initializing - $ref: '@supabase/supabase-js.SupabaseClient.constructor' - description: | - You can initialize a new Supabase client using the `createClient()` method. + $ref: "@supabase/supabase-js.SupabaseClient.constructor" + description: > + You can initialize a new Supabase client using the `createClient()` + method. - The Supabase client is your entrypoint to the rest of the Supabase functionality - and is the easiest way to interact with everything we offer within the Supabase ecosystem. + + The Supabase client is your entrypoint to the rest of the Supabase + functionality + + and is the easiest way to interact with everything we offer within the + Supabase ecosystem. examples: - id: create-client name: Creating a client - code: | + code: > ```js + import { createClient } from '@supabase/supabase-js' + // Create a single supabase client for interacting with your database - const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key') + + const supabase = createClient('https://xyzcompany.supabase.co', + 'publishable-or-anon-key') + ``` - id: with-custom-domain name: With a custom domain - code: | + code: > ```js + import { createClient } from '@supabase/supabase-js' + // Use a custom domain as the supabase URL - const supabase = createClient('https://my-custom-domain.com', 'publishable-or-anon-key') + + const supabase = createClient('https://my-custom-domain.com', + 'publishable-or-anon-key') + ``` - id: with-additional-parameters name: With additional parameters - code: | + code: > ```js + import { createClient } from '@supabase/supabase-js' + const options = { db: { schema: 'public', @@ -58,47 +75,76 @@ functions: headers: { 'x-my-custom-header': 'my-app-name' }, }, } - const supabase = createClient("https://xyzcompany.supabase.co", "publishable-or-anon-key", options) + + const supabase = createClient("https://xyzcompany.supabase.co", + "publishable-or-anon-key", options) + ``` - id: api-schemas name: With custom schemas - code: | + code: > ```js + import { createClient } from '@supabase/supabase-js' - const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key', { + + const supabase = createClient('https://xyzcompany.supabase.co', + 'publishable-or-anon-key', { // Provide a custom schema. Defaults to "public". db: { schema: 'other_schema' } }) - ``` - description: | - By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard. - Go to [Settings > API > Exposed schemas](/dashboard/project/_/settings/api) and add the schema which you want to expose to the API. - Note: each client connection can only access a single schema, so the code above can access the `other_schema` schema but cannot access the `public` schema. + ``` + description: > + By default the API server points to the `public` schema. You can + enable other database schemas within the Dashboard. + + Go to [Settings > API > Exposed + schemas](/dashboard/project/_/settings/api) and add the schema which + you want to expose to the API. + + + Note: each client connection can only access a single schema, so the + code above can access the `other_schema` schema but cannot access the + `public` schema. - id: custom-fetch-implementation name: Custom fetch implementation - code: | + code: > ```js + import { createClient } from '@supabase/supabase-js' - const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key', { + + const supabase = createClient('https://xyzcompany.supabase.co', + 'publishable-or-anon-key', { global: { fetch: fetch.bind(globalThis) } }) + ``` - description: | - `supabase-js` uses the [`cross-fetch`](https://www.npmjs.com/package/cross-fetch) library to make HTTP requests, - but an alternative `fetch` implementation can be provided as an option. - This is most useful in environments where `cross-fetch` is not compatible (for instance Cloudflare Workers). + description: > + `supabase-js` uses the + [`cross-fetch`](https://www.npmjs.com/package/cross-fetch) library to + make HTTP requests, + + but an alternative `fetch` implementation can be provided as an + option. + + This is most useful in environments where `cross-fetch` is not + compatible (for instance Cloudflare Workers). - id: react-native-options-async-storage name: React Native options with AsyncStorage - code: | + code: > ```js + import 'react-native-url-polyfill/auto' + import { createClient } from '@supabase/supabase-js' + import AsyncStorage from "@react-native-async-storage/async-storage"; - const supabase = createClient("https://xyzcompany.supabase.co", "publishable-or-anon-key", { + + const supabase = createClient("https://xyzcompany.supabase.co", + "publishable-or-anon-key", { auth: { storage: AsyncStorage, autoRefreshToken: true, @@ -106,23 +152,35 @@ functions: detectSessionInUrl: false, }, }); + ``` - description: | - For React Native we recommend using `AsyncStorage` as the storage implementation for Supabase Auth. + description: > + For React Native we recommend using `AsyncStorage` as the storage + implementation for Supabase Auth. - id: react-native-options-secure-storage name: React Native options with Expo SecureStore - code: | + code: > ```js + import 'react-native-url-polyfill/auto' + import { createClient } from '@supabase/supabase-js' + import AsyncStorage from '@react-native-async-storage/async-storage'; + import * as SecureStore from 'expo-secure-store'; + import * as aesjs from 'aes-js'; + import 'react-native-get-random-values'; + // As Expo's SecureStore does not support values larger than 2048 + // bytes, an AES-256 key is generated and stored in SecureStore, while + // it is used to encrypt/decrypt values stored in AsyncStorage. + class LargeSecureStore { private async _encrypt(key: string, value: string) { const encryptionKey = crypto.getRandomValues(new Uint8Array(256 / 8)); @@ -166,7 +224,9 @@ functions: } } - const supabase = createClient("https://xyzcompany.supabase.co", "publishable-or-anon-key", { + + const supabase = createClient("https://xyzcompany.supabase.co", + "publishable-or-anon-key", { auth: { storage: new LargeSecureStore(), autoRefreshToken: true, @@ -174,6 +234,7 @@ functions: detectSessionInUrl: false, }, }); + ``` description: | If you wish to encrypt the user's session information, you can use `aes-js` and store the encryption key in Expo SecureStore. The `aes-js` library, a reputable JavaScript-only implementation of the AES encryption algorithm in CTR mode. A new 256-bit encryption key is generated using the `react-native-get-random-values` library. This key is stored inside Expo's SecureStore, while the value is encrypted and placed inside AsyncStorage. @@ -184,15 +245,25 @@ functions: - Carefully consider optimizations or other modifications to the above example, as those can lead to introducing subtle security vulnerabilities. - id: auth-api title: Overview - notes: | + notes: > - The auth methods can be accessed via the `supabase.auth` namespace. - - By default, the supabase client sets `persistSession` to true and attempts to store the session in local storage. When using the supabase client in an environment that doesn't support local storage, you might notice the following warning message being logged: + + - By default, the supabase client sets `persistSession` to true and + attempts to store the session in local storage. When using the supabase + client in an environment that doesn't support local storage, you might + notice the following warning message being logged: > No storage option exists to persist the session, which may result in unexpected behavior when using auth. If you want to set `persistSession` to true, please provide a storage option or you may set `persistSession` to false to disable this warning. This warning message can be safely ignored if you're not using auth on the server-side. If you are using auth and you want to set `persistSession` to true, you will need to provide a custom storage implementation that follows [this interface](https://github.com/supabase/gotrue-js/blob/master/src/lib/types.ts#L1027). - - Any email links and one-time passwords (OTPs) sent have a default expiry of 24 hours. We have the following [rate limits](/docs/guides/platform/going-into-prod#auth-rate-limits) in place to guard against brute force attacks. - - The expiry of an access token can be set in the "JWT expiry limit" field in [your project's auth settings](/dashboard/project/_/settings/auth). A refresh token never expires and can only be used once. + - Any email links and one-time passwords (OTPs) sent have a default expiry + of 24 hours. We have the following [rate + limits](/docs/guides/platform/going-into-prod#auth-rate-limits) in place + to guard against brute force attacks. + + - The expiry of an access token can be set in the "JWT expiry limit" field + in [your project's auth settings](/dashboard/project/_/settings/auth). A + refresh token never expires and can only be used once. examples: - id: create-auth-client name: Create auth client @@ -220,7 +291,7 @@ functions: ``` - id: sign-up title: signUp() - $ref: '@supabase/auth-js.GoTrueClient.signUp' + $ref: "@supabase/auth-js.GoTrueClient.signUp" notes: | - By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](/dashboard/project/_/auth/providers). - **Confirm email** determines if users need to confirm their email address after signing up. @@ -346,8 +417,11 @@ functions: - id: sign-up-phone-whatsapp name: Sign up with a phone number and password (whatsapp) isSpotlight: true - description: | - The user will be sent a WhatsApp message which contains a OTP. By default, a given user can only request a OTP once every 60 seconds. Note that a user will need to have a valid WhatsApp account that is linked to Twilio in order to use this feature. + description: > + The user will be sent a WhatsApp message which contains a OTP. By + default, a given user can only request a OTP once every 60 seconds. + Note that a user will need to have a valid WhatsApp account that is + linked to Twilio in order to use this feature. code: | ```js const { data, error } = await supabase.auth.signUp({ @@ -394,12 +468,21 @@ functions: ``` - id: on-auth-state-change title: onAuthStateChange() - $ref: '@supabase/auth-js.GoTrueClient.onAuthStateChange' - notes: | + $ref: "@supabase/auth-js.GoTrueClient.onAuthStateChange" + notes: > - Subscribes to important events occurring on the user's session. + - Use on the frontend/client. It is less useful on the server. - - Events are emitted across tabs to keep your application's UI up-to-date. Some events can fire very frequently, based on the number of tabs open. Use a quick and efficient callback function, and defer or debounce as many operations as you can to be performed outside of the callback. - - **Important:** A callback can be an `async` function and it runs synchronously during the processing of the changes causing the event. You can easily create a dead-lock by using `await` on a call to another method of the Supabase library. + + - Events are emitted across tabs to keep your application's UI up-to-date. + Some events can fire very frequently, based on the number of tabs open. + Use a quick and efficient callback function, and defer or debounce as many + operations as you can to be performed outside of the callback. + + - **Important:** A callback can be an `async` function and it runs + synchronously during the processing of the changes causing the event. You + can easily create a dead-lock by using `await` on a call to another method + of the Supabase library. - Avoid using `async` functions as callbacks. - Limit the number of `await` calls in `async` callbacks. - Do not use other Supabase functions in the callback function. If you must, dispatch the functions once the callback has finished executing. Use this as a quick way to achieve this: @@ -467,8 +550,9 @@ functions: ``` - id: listen-to-sign-out name: Listen to sign out - description: | - Make sure you clear out any local data, such as local and session storage, after the client library has detected the user's sign out. + description: > + Make sure you clear out any local data, such as local and session + storage, after the client library has detected the user's sign out. code: | ```js supabase.auth.onAuthStateChange((event, session) => { @@ -490,17 +574,35 @@ functions: ``` - id: store-provider-tokens name: Store OAuth provider tokens on sign in - description: | - When using [OAuth (Social Login)](/docs/guides/auth/social-login) you sometimes wish to get access to the provider's access token and refresh token, in order to call provider APIs in the name of the user. + description: > + When using [OAuth (Social Login)](/docs/guides/auth/social-login) you + sometimes wish to get access to the provider's access token and + refresh token, in order to call provider APIs in the name of the user. - For example, if you are using [Sign in with Google](/docs/guides/auth/social-login/auth-google) you may want to use the provider token to call Google APIs on behalf of the user. Supabase Auth does not keep track of the provider access and refresh token, but does return them for you once, immediately after sign in. You can use the `onAuthStateChange` method to listen for the presence of the provider tokens and store them in local storage. You can further send them to your server's APIs for use on the backend. - Finally, make sure you remove them from local storage on the `SIGNED_OUT` event. If the OAuth provider supports token revocation, make sure you call those APIs either from the frontend or schedule them to be called on the backend. - code: | + For example, if you are using [Sign in with + Google](/docs/guides/auth/social-login/auth-google) you may want to + use the provider token to call Google APIs on behalf of the user. + Supabase Auth does not keep track of the provider access and refresh + token, but does return them for you once, immediately after sign in. + You can use the `onAuthStateChange` method to listen for the presence + of the provider tokens and store them in local storage. You can + further send them to your server's APIs for use on the backend. + + + Finally, make sure you remove them from local storage on the + `SIGNED_OUT` event. If the OAuth provider supports token revocation, + make sure you call those APIs either from the frontend or schedule + them to be called on the backend. + code: > ```js + // Register this immediately after calling createClient! + // Because signInWithOAuth causes a redirect, you need to fetch the + // provider tokens from the callback. + supabase.auth.onAuthStateChange((event, session) => { if (session && session.provider_token) { window.localStorage.setItem('oauth_provider_token', session.provider_token) @@ -515,11 +617,16 @@ functions: window.localStorage.removeItem('oauth_provider_refresh_token') } }) + ``` - id: react-user-session-context name: Use React Context for the User's session - description: | - Instead of relying on `supabase.auth.getSession()` within your React components, you can use a [React Context](https://react.dev/reference/react/createContext) to store the latest session information from the `onAuthStateChange` callback and access it that way. + description: > + Instead of relying on `supabase.auth.getSession()` within your React + components, you can use a [React + Context](https://react.dev/reference/react/createContext) to store the + latest session information from the `onAuthStateChange` callback and + access it that way. code: | ```js const SessionContext = React.createContext(null) @@ -571,11 +678,13 @@ functions: ``` - id: listen-to-token-refresh name: Listen to token refresh - code: | + code: > ```js + supabase.auth.onAuthStateChange((event, session) => { if (event === 'TOKEN_REFRESHED') console.log('TOKEN_REFRESHED', session) }) + ``` - id: listen-to-user-updates name: Listen to user updates @@ -587,10 +696,12 @@ functions: ``` - id: sign-in-anonymously title: signInAnonymously() - $ref: '@supabase/auth-js.GoTrueClient.signInAnonymously' - notes: | + $ref: "@supabase/auth-js.GoTrueClient.signInAnonymously" + notes: > - Returns an anonymous user - - It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the `options` param. + + - It is recommended to set up captcha for anonymous sign-ins to prevent + abuse. You can pass in the captcha token in the `options` param. examples: - id: sign-in-anonymously name: Create an anonymous user @@ -659,7 +770,7 @@ functions: ``` - id: sign-in-with-password title: signInWithPassword() - $ref: '@supabase/auth-js.GoTrueClient.signInWithPassword' + $ref: "@supabase/auth-js.GoTrueClient.signInWithPassword" notes: | - Requires either an email and password or a phone number and password. examples: @@ -772,7 +883,7 @@ functions: ``` - id: sign-in-with-otp title: signInWithOtp() - $ref: '@supabase/auth-js.GoTrueClient.signInWithOtp' + $ref: "@supabase/auth-js.GoTrueClient.signInWithOtp" notes: | - Requires either an email or phone number. - This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number. @@ -787,7 +898,9 @@ functions: - id: sign-in-with-email name: Sign in with email isSpotlight: true - description: The user will be sent an email which contains either a magiclink or a OTP or both. By default, a given user can only request a OTP once every 60 seconds. + description: The user will be sent an email which contains either a magiclink or + a OTP or both. By default, a given user can only request a OTP once + every 60 seconds. code: | ```js const { data, error } = await supabase.auth.signInWithOtp({ @@ -810,7 +923,8 @@ functions: - id: sign-in-with-sms-otp name: Sign in with SMS OTP isSpotlight: false - description: The user will be sent a SMS which contains a OTP. By default, a given user can only request a OTP once every 60 seconds. + description: The user will be sent a SMS which contains a OTP. By default, a + given user can only request a OTP once every 60 seconds. code: | ```js const { data, error } = await supabase.auth.signInWithOtp({ @@ -820,7 +934,10 @@ functions: - id: sign-in-with-whatsapp-otp name: Sign in with WhatsApp OTP isSpotlight: false - description: The user will be sent a WhatsApp message which contains a OTP. By default, a given user can only request a OTP once every 60 seconds. Note that a user will need to have a valid WhatsApp account that is linked to Twilio in order to use this feature. + description: The user will be sent a WhatsApp message which contains a OTP. By + default, a given user can only request a OTP once every 60 seconds. + Note that a user will need to have a valid WhatsApp account that is + linked to Twilio in order to use this feature. code: | ```js const { data, error } = await supabase.auth.signInWithOtp({ @@ -832,10 +949,13 @@ functions: ``` - id: sign-in-with-oauth title: signInWithOAuth() - $ref: '@supabase/auth-js.GoTrueClient.signInWithOAuth' - notes: | - - This method is used for signing in using [Social Login (OAuth) providers](/docs/guides/auth#configure-third-party-providers). - - It works by redirecting your application to the provider's authorization screen, before bringing back the user to your app. + $ref: "@supabase/auth-js.GoTrueClient.signInWithOAuth" + notes: > + - This method is used for signing in using [Social Login (OAuth) + providers](/docs/guides/auth#configure-third-party-providers). + + - It works by redirecting your application to the provider's authorization + screen, before bringing back the user to your app. examples: - id: sign-in-using-a-third-party-provider name: Sign in using a third-party provider @@ -874,17 +994,37 @@ functions: - id: sign-in-with-scopes name: Sign in with scopes and access provider tokens isSpotlight: false - description: | - If you need additional access from an OAuth provider, in order to access provider specific APIs in the name of the user, you can do this by passing in the scopes the user should authorize for your application. Note that the `scopes` option takes in **a space-separated list** of scopes. + description: > + If you need additional access from an OAuth provider, in order to + access provider specific APIs in the name of the user, you can do this + by passing in the scopes the user should authorize for your + application. Note that the `scopes` option takes in **a + space-separated list** of scopes. - Because OAuth sign-in often includes redirects, you should register an `onAuthStateChange` callback immediately after you create the Supabase client. This callback will listen for the presence of `provider_token` and `provider_refresh_token` properties on the `session` object and store them in local storage. The client library will emit these values **only once** immediately after the user signs in. You can then access them by looking them up in local storage, or send them to your backend servers for further processing. - Finally, make sure you remove them from local storage on the `SIGNED_OUT` event. If the OAuth provider supports token revocation, make sure you call those APIs either from the frontend or schedule them to be called on the backend. - code: | + Because OAuth sign-in often includes redirects, you should register an + `onAuthStateChange` callback immediately after you create the Supabase + client. This callback will listen for the presence of `provider_token` + and `provider_refresh_token` properties on the `session` object and + store them in local storage. The client library will emit these values + **only once** immediately after the user signs in. You can then access + them by looking them up in local storage, or send them to your backend + servers for further processing. + + + Finally, make sure you remove them from local storage on the + `SIGNED_OUT` event. If the OAuth provider supports token revocation, + make sure you call those APIs either from the frontend or schedule + them to be called on the backend. + code: > ```js + // Register this immediately after calling createClient! + // Because signInWithOAuth causes a redirect, you need to fetch the + // provider tokens from the callback. + supabase.auth.onAuthStateChange((event, session) => { if (session && session.provider_token) { window.localStorage.setItem('oauth_provider_token', session.provider_token) @@ -900,18 +1040,22 @@ functions: } }) + // Call this on your Sign in with GitHub button to initiate OAuth + // with GitHub with the requested elevated scopes. + await supabase.auth.signInWithOAuth({ provider: 'github', options: { scopes: 'repo gist notifications' } }) + ``` - id: sign-in-with-id-token title: signInWithIdToken - $ref: '@supabase/auth-js.GoTrueClient.signInWithIdToken' + $ref: "@supabase/auth-js.GoTrueClient.signInWithIdToken" notes: | - Use an ID token to sign in. - Especially useful when implementing sign in using native platform dialogs in mobile or desktop apps using Sign in with Apple or Sign in with Google on iOS and Android. @@ -983,7 +1127,7 @@ functions: ``` - id: sign-in-with-sso title: signInWithSSO() - $ref: '@supabase/auth-js.GoTrueClient.signInWithSSO' + $ref: "@supabase/auth-js.GoTrueClient.signInWithSSO" notes: | - Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this. - If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow. @@ -994,7 +1138,7 @@ functions: - id: sign-in-with-domain name: Sign in with email domain isSpotlight: true - code: | + code: > ```js // You can extract the user's email domain and use it to trigger the // authentication flow with the correct identity provider. @@ -1011,7 +1155,7 @@ functions: - id: sign-in-with-provider-uuid name: Sign in with provider UUID isSpotlight: true - code: | + code: > ```js // Useful when you need to map a user's sign in request according // to different rules that can't use email domains. @@ -1027,15 +1171,17 @@ functions: ``` - id: sign-in-with-web3 title: signInWithWeb3() - $ref: '@supabase/auth-js.GoTrueClient.signInWithWeb3' - notes: | + $ref: "@supabase/auth-js.GoTrueClient.signInWithWeb3" + notes: > - Uses a Web3 (Ethereum, Solana) wallet to sign a user in. - - Read up on the [potential for abuse](/docs/guides/auth/auth-web3#potential-for-abuse) before using it. + + - Read up on the [potential for + abuse](/docs/guides/auth/auth-web3#potential-for-abuse) before using it. examples: - id: sign-in-with-solana-window name: Sign in with Solana or Ethereum (Window API) isSpotlight: true - code: | + code: > ```js // uses window.ethereum for the wallet const { data, error } = await supabase.auth.signInWithWeb3({ @@ -1063,7 +1209,7 @@ functions: - id: sign-in-with-solana-brave name: Sign in with Solana (Brave) isSpotlight: false - code: | + code: > ```js const { data, error } = await supabase.auth.signInWithWeb3({ chain: 'solana', @@ -1074,7 +1220,7 @@ functions: - id: sign-in-with-solana-wallet-adapter name: Sign in with Solana (Wallet Adapter) isSpotlight: false - code: | + code: > ```jsx function SignInButton() { const wallet = useWallet() @@ -1100,6 +1246,7 @@ functions: ) } + function App() { const endpoint = clusterApiUrl('devnet') const wallets = useMemo(() => [], []) @@ -1114,17 +1261,41 @@ functions: ) } + ``` - id: get-claims title: getClaims() - $ref: '@supabase/auth-js.GoTrueClient.getClaims' - notes: | - - Parses the user's [access token](/docs/guides/auth/sessions#access-token-jwt-claims) as a [JSON Web Token (JWT)](/docs/guides/auth/jwts) and returns its components if valid and not expired. - - If your project is using asymmetric JWT signing keys, then the verification is done locally usually without a network request using the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). - - A network request is sent to your project's JWT signing key discovery endpoint `https://project-id.supabase.co/auth/v1/.well-known/jwks.json`, which is cached locally. If your environment is ephemeral, such as a Lambda function that is destroyed after every request, a network request will be sent for each new invocation. Supabase provides a network-edge cache providing fast responses for these situations. - - If the user's access token is about to expire when calling this function, the user's session will first be refreshed before validating the JWT. - - If your project is using a symmetric secret to sign the JWT, it always sends a request similar to `getUser()` to validate the JWT at the server before returning the decoded token. This is also used if the WebCrypto API is not available in the environment. Make sure you polyfill it in such situations. - - The returned claims can be customized per project using the [Custom Access Token Hook](/docs/guides/auth/auth-hooks/custom-access-token-hook). + $ref: "@supabase/auth-js.GoTrueClient.getClaims" + notes: > + - Parses the user's [access + token](/docs/guides/auth/sessions#access-token-jwt-claims) as a [JSON Web + Token (JWT)](/docs/guides/auth/jwts) and returns its components if valid + and not expired. + + - If your project is using asymmetric JWT signing keys, then the + verification is done locally usually without a network request using the + [WebCrypto + API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). + + - A network request is sent to your project's JWT signing key discovery + endpoint `https://project-id.supabase.co/auth/v1/.well-known/jwks.json`, + which is cached locally. If your environment is ephemeral, such as a + Lambda function that is destroyed after every request, a network request + will be sent for each new invocation. Supabase provides a network-edge + cache providing fast responses for these situations. + + - If the user's access token is about to expire when calling this + function, the user's session will first be refreshed before validating the + JWT. + + - If your project is using a symmetric secret to sign the JWT, it always + sends a request similar to `getUser()` to validate the JWT at the server + before returning the decoded token. This is also used if the WebCrypto API + is not available in the environment. Make sure you polyfill it in such + situations. + + - The returned claims can be customized per project using the [Custom + Access Token Hook](/docs/guides/auth/auth-hooks/custom-access-token-hook). examples: - id: get-claims name: Get JWT claims, header and signature @@ -1167,11 +1338,19 @@ functions: ``` - id: sign-out title: signOut() - $ref: '@supabase/auth-js.GoTrueClient.signOut' - notes: | - - In order to use the `signOut()` method, the user needs to be signed in first. - - By default, `signOut()` uses the global scope, which signs out all other sessions that the user is logged into as well. Customize this behavior by passing a scope parameter. - - Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires. + $ref: "@supabase/auth-js.GoTrueClient.signOut" + notes: > + - In order to use the `signOut()` method, the user needs to be signed in + first. + + - By default, `signOut()` uses the global scope, which signs out all other + sessions that the user is logged into as well. Customize this behavior by + passing a scope parameter. + + - Since Supabase Auth uses JWTs for authentication, the access token JWT + will be valid until it's expired. When the user signs out, Supabase + revokes the refresh token and deletes the JWT from the client-side. This + does not revoke the JWT and it will still be valid until it expires. examples: - id: sign-out name: Sign out (all sessions) @@ -1196,7 +1375,7 @@ functions: ``` - id: verify-otp title: verifyOtp() - $ref: '@supabase/auth-js.GoTrueClient.verifyOtp' + $ref: "@supabase/auth-js.GoTrueClient.verifyOtp" notes: | - The `verifyOtp` method takes in different verification types. - If a phone number is used, the type can either be: @@ -1213,9 +1392,12 @@ functions: - id: verify-signup-one-time-password(otp) name: Verify Signup One-Time Password (OTP) isSpotlight: false - code: | + code: > ```js - const { data, error } = await supabase.auth.verifyOtp({ email, token, type: 'email'}) + + const { data, error } = await supabase.auth.verifyOtp({ email, token, + type: 'email'}) + ``` response: | ```json @@ -1323,20 +1505,26 @@ functions: - id: verify-sms-one-time-password(otp) name: Verify SMS One-Time Password (OTP) isSpotlight: true - code: | + code: > ```js - const { data, error } = await supabase.auth.verifyOtp({ phone, token, type: 'sms'}) + + const { data, error } = await supabase.auth.verifyOtp({ phone, token, + type: 'sms'}) + ``` - id: verify-email-auth(tokenhash) name: Verify Email Auth (Token Hash) isSpotlight: false - code: | + code: > ```js - const { data, error } = await supabase.auth.verifyOtp({ token_hash: tokenHash, type: 'email'}) + + const { data, error } = await supabase.auth.verifyOtp({ token_hash: + tokenHash, type: 'email'}) + ``` - id: get-session title: getSession() - $ref: '@supabase/auth-js.GoTrueClient.getSession' + $ref: "@supabase/auth-js.GoTrueClient.getSession" notes: | - Since the introduction of [asymmetric JWT signing keys](/docs/guides/auth/signing-keys), this method is considered low-level and we encourage you to use `getClaims()` or `getUser()` instead. - Retrieves the current [user session](/docs/guides/auth/sessions) from the storage medium (local storage, cookies). @@ -1412,12 +1600,21 @@ functions: ``` - id: start-auto-refresh title: startAutoRefresh() - $ref: '@supabase/auth-js.GoTrueClient.startAutoRefresh' - notes: | - - Only useful in non-browser environments such as React Native or Electron. - - The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not. - - On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is _focused_ or not. - - To give this hint to the application, you should be calling this method when the app is in focus and calling `supabase.auth.stopAutoRefresh()` when it's out of focus. + $ref: "@supabase/auth-js.GoTrueClient.startAutoRefresh" + notes: > + - Only useful in non-browser environments such as React Native or + Electron. + + - The Supabase Auth library automatically starts and stops proactively + refreshing the session when a tab is focused or not. + + - On non-browser platforms, such as mobile or desktop apps built with web + technologies, the library is not able to effectively determine whether the + application is _focused_ or not. + + - To give this hint to the application, you should be calling this method + when the app is in focus and calling `supabase.auth.stopAutoRefresh()` + when it's out of focus. examples: - id: start-stop-auto-refresh-react-native name: Start and stop auto refresh in React Native @@ -1437,12 +1634,20 @@ functions: ``` - id: stop-auto-refresh title: stopAutoRefresh() - $ref: '@supabase/auth-js.GoTrueClient.stopAutoRefresh' - notes: | - - Only useful in non-browser environments such as React Native or Electron. - - The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not. - - On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is _focused_ or not. - - When your application goes in the background or out of focus, call this method to stop the proactive refreshing of the session. + $ref: "@supabase/auth-js.GoTrueClient.stopAutoRefresh" + notes: > + - Only useful in non-browser environments such as React Native or + Electron. + + - The Supabase Auth library automatically starts and stops proactively + refreshing the session when a tab is focused or not. + + - On non-browser platforms, such as mobile or desktop apps built with web + technologies, the library is not able to effectively determine whether the + application is _focused_ or not. + + - When your application goes in the background or out of focus, call this + method to stop the proactive refreshing of the session. examples: - id: start-stop-auto-refresh-react-native name: Start and stop auto refresh in React Native @@ -1462,11 +1667,17 @@ functions: ``` - id: get-user title: getUser() - $ref: '@supabase/auth-js.GoTrueClient.getUser' - notes: | - - This method fetches the user object from the database instead of local session. - - This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server. - - Should always be used when checking for user authorization on the server. On the client, you can instead use `getSession().session.user` for faster results. `getSession` is insecure on the server. + $ref: "@supabase/auth-js.GoTrueClient.getUser" + notes: > + - This method fetches the user object from the database instead of local + session. + + - This method is useful for checking if the user is authorized because it + validates the user's access token JWT on the server. + + - Should always be used when checking for user authorization on the + server. On the client, you can instead use `getSession().session.user` for + faster results. `getSession` is insecure on the server. examples: - id: get-the-logged-in-user-with-the-current-existing-session name: Get the logged in user with the current existing session @@ -1535,16 +1746,27 @@ functions: ``` - id: update-user title: updateUser() - $ref: '@supabase/auth-js.GoTrueClient.updateUser' - notes: | - - In order to use the `updateUser()` method, the user needs to be signed in first. - - By default, email updates sends a confirmation link to both the user's current and new email. - To only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](/dashboard/project/_/auth/providers). + $ref: "@supabase/auth-js.GoTrueClient.updateUser" + notes: > + - In order to use the `updateUser()` method, the user needs to be signed + in first. + + - By default, email updates sends a confirmation link to both the user's + current and new email. + + To only send a confirmation link to the user's new email, disable **Secure + email change** in your project's [email auth provider + settings](/dashboard/project/_/auth/providers). examples: - id: update-the-email-for-an-authenticated-user name: Update the email for an authenticated user - description: | - Sends a "Confirm Email Change" email to the new address. If **Secure Email Change** is enabled (default), confirmation is also required from the **old email** before the change is applied. To skip dual confirmation and apply the change after only the new email is verified, disable **Secure Email Change** in the [Email Auth Provider settings](/dashboard/project/_/auth/providers?provider=Email). + description: > + Sends a "Confirm Email Change" email to the new address. If **Secure + Email Change** is enabled (default), confirmation is also required + from the **old email** before the change is applied. To skip dual + confirmation and apply the change after only the new email is + verified, disable **Secure Email Change** in the [Email Auth Provider + settings](/dashboard/project/_/auth/providers?provider=Email). isSpotlight: false code: | ```js @@ -1626,10 +1848,13 @@ functions: ``` - id: update-the-users-metadata name: Update the user's metadata - description: | + description: > Updates the user's custom metadata. - **Note**: The `data` field maps to the `auth.users.raw_user_meta_data` column in your Supabase database. When calling `getUser()`, the data will be available as `user.user_metadata`. + + **Note**: The `data` field maps to the `auth.users.raw_user_meta_data` + column in your Supabase database. When calling `getUser()`, the data + will be available as `user.user_metadata`. isSpotlight: true code: | ```js @@ -1639,8 +1864,13 @@ functions: ``` - id: update-password-with-reauthentication name: Update the user's password with a nonce - description: | - If **Secure password change** is enabled in your [project's email provider settings](/dashboard/project/_/auth/providers), updating the user's password would require a nonce if the user **hasn't recently signed in**. The nonce is sent to the user's email or phone number. A user is deemed recently signed in if the session was created in the last 24 hours. + description: > + If **Secure password change** is enabled in your [project's email + provider settings](/dashboard/project/_/auth/providers), updating the + user's password would require a nonce if the user **hasn't recently + signed in**. The nonce is sent to the user's email or phone number. A + user is deemed recently signed in if the session was created in the + last 24 hours. isSpotlight: true code: | ```js @@ -1651,7 +1881,7 @@ functions: ``` - id: get-user-identities title: getUserIdentities() - $ref: '@supabase/auth-js.GoTrueClient.getUserIdentities' + $ref: "@supabase/auth-js.GoTrueClient.getUserIdentities" notes: | - The user needs to be signed in to call `getUserIdentities()`. examples: @@ -1690,12 +1920,19 @@ functions: ``` - id: link-identity title: linkIdentity() - $ref: '@supabase/auth-js.GoTrueClient.linkIdentity' - notes: | - - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/settings/auth). + $ref: "@supabase/auth-js.GoTrueClient.linkIdentity" + notes: > + - The **Enable Manual Linking** option must be enabled from your + [project's authentication settings](/dashboard/project/_/settings/auth). + - The user needs to be signed in to call `linkIdentity()`. - - If the candidate identity is already linked to the existing user or another user, `linkIdentity()` will fail. - - If `linkIdentity` is run in the browser, the user is automatically redirected to the returned URL. On the server, you should handle the redirect. + + - If the candidate identity is already linked to the existing user or + another user, `linkIdentity()` will fail. + + - If `linkIdentity` is run in the browser, the user is automatically + redirected to the returned URL. On the server, you should handle the + redirect. examples: - id: link-identity name: Link an identity to a user @@ -1718,11 +1955,15 @@ functions: ``` - id: unlink-identity title: unlinkIdentity() - $ref: '@supabase/auth-js.GoTrueClient.unlinkIdentity' - notes: | - - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/settings/auth). + $ref: "@supabase/auth-js.GoTrueClient.unlinkIdentity" + notes: > + - The **Enable Manual Linking** option must be enabled from your + [project's authentication settings](/dashboard/project/_/settings/auth). + - The user needs to be signed in to call `unlinkIdentity()`. + - The user must have at least 2 identities in order to unlink an identity. + - The identity to be unlinked must belong to the user. examples: - id: unlink-identity @@ -1743,13 +1984,26 @@ functions: ``` - id: send-password-reauthentication title: reauthenticate() - $ref: '@supabase/auth-js.GoTrueClient.reauthenticate' - notes: | - - This method is used together with `updateUser()` when a user's password needs to be updated. - - If you require your user to reauthenticate before updating their password, you need to enable the **Secure password change** option in your [project's email provider settings](/dashboard/project/_/auth/providers). - - A user is only require to reauthenticate before updating their password if **Secure password change** is enabled and the user **hasn't recently signed in**. A user is deemed recently signed in if the session was created in the last 24 hours. - - This method will send a nonce to the user's email. If the user doesn't have a confirmed email address, the method will send the nonce to the user's confirmed phone number instead. - - After receiving the OTP, include it as the `nonce` in your `updateUser()` call to finalize the password change. + $ref: "@supabase/auth-js.GoTrueClient.reauthenticate" + notes: > + - This method is used together with `updateUser()` when a user's password + needs to be updated. + + - If you require your user to reauthenticate before updating their + password, you need to enable the **Secure password change** option in your + [project's email provider settings](/dashboard/project/_/auth/providers). + + - A user is only require to reauthenticate before updating their password + if **Secure password change** is enabled and the user **hasn't recently + signed in**. A user is deemed recently signed in if the session was + created in the last 24 hours. + + - This method will send a nonce to the user's email. If the user doesn't + have a confirmed email address, the method will send the nonce to the + user's confirmed phone number instead. + + - After receiving the OTP, include it as the `nonce` in your + `updateUser()` call to finalize the password change. examples: - id: send-reauthentication-nonce name: Send reauthentication nonce @@ -1761,13 +2015,24 @@ functions: ``` - id: resend-email-or-phone-otps title: resend() - $ref: '@supabase/auth-js.GoTrueClient.resend' - notes: | - - Resends a signup confirmation, email change or phone change email to the user. - - Passwordless sign-ins can be resent by calling the `signInWithOtp()` method again. - - Password recovery emails can be resent by calling the `resetPasswordForEmail()` method again. - - This method will only resend an email or phone OTP to the user if there was an initial signup, email change or phone change request being made(note: For existing users signing in with OTP, you should use `signInWithOtp()` again to resend the OTP). - - You can specify a redirect url when you resend an email link using the `emailRedirectTo` option. + $ref: "@supabase/auth-js.GoTrueClient.resend" + notes: > + - Resends a signup confirmation, email change or phone change email to the + user. + + - Passwordless sign-ins can be resent by calling the `signInWithOtp()` + method again. + + - Password recovery emails can be resent by calling the + `resetPasswordForEmail()` method again. + + - This method will only resend an email or phone OTP to the user if there + was an initial signup, email change or phone change request being + made(note: For existing users signing in with OTP, you should use + `signInWithOtp()` again to resend the OTP). + + - You can specify a redirect url when you resend an email link using the + `emailRedirectTo` option. examples: - id: resend-email-signup-confirmation name: Resend an email signup confirmation @@ -1815,14 +2080,17 @@ functions: ``` - id: set-session title: setSession() - $ref: '@supabase/auth-js.GoTrueClient.setSession' - notes: | - - This method sets the session using an `access_token` and `refresh_token`. + $ref: "@supabase/auth-js.GoTrueClient.setSession" + notes: > + - This method sets the session using an `access_token` and + `refresh_token`. + - If successful, a `SIGNED_IN` event is emitted. examples: - id: set-the-session name: Set the session - description: Sets the session data from an access_token and refresh_token, then returns an auth response or error. + description: Sets the session data from an access_token and refresh_token, then + returns an auth response or error. isSpotlight: true code: | ```js @@ -1934,9 +2202,10 @@ functions: ``` - id: refresh-session title: refreshSession() - $ref: '@supabase/auth-js.GoTrueClient.refreshSession' - notes: | - - This method will refresh and return a new session whether the current one is expired or not. + $ref: "@supabase/auth-js.GoTrueClient.refreshSession" + notes: > + - This method will refresh and return a new session whether the current + one is expired or not. examples: - id: refresh-session-using-the-current-session name: Refresh session using the current session @@ -2050,14 +2319,18 @@ functions: - id: refresh-session-using-a-passed-in-session name: Refresh session using a refresh token isSpotlight: false - code: | + code: > ```js - const { data, error } = await supabase.auth.refreshSession({ refresh_token }) + + const { data, error } = await supabase.auth.refreshSession({ + refresh_token }) + const { session, user } = data + ``` - id: exchange-code-for-session title: exchangeCodeForSession() - $ref: '@supabase/auth-js.GoTrueClient.exchangeCodeForSession' + $ref: "@supabase/auth-js.GoTrueClient.exchangeCodeForSession" notes: | - Used when `flowType` is set to `pkce` in client options. examples: @@ -2226,17 +2499,29 @@ functions: ``` - id: auth-mfa-api title: Overview - notes: | - This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the `supabase.auth.mfa` namespace. + notes: > + This section contains methods commonly used for Multi-Factor + Authentication (MFA) and are invoked behind the `supabase.auth.mfa` + namespace. - Currently, there is support for time-based one-time password (TOTP) and phone verification code as the 2nd factor. Recovery codes are not supported but users can enroll multiple factors, with an upper limit of 10. - Having a 2nd factor for recovery frees the user of the burden of having to store their recovery codes somewhere. It also reduces the attack surface since multiple recovery codes are usually generated compared to just having 1 backup factor. + Currently, there is support for time-based one-time password (TOTP) and + phone verification code as the 2nd factor. Recovery codes are not + supported but users can enroll multiple factors, with an upper limit of + 10. - Learn more about implementing MFA in your application [in the MFA guide](https://supabase.com/docs/guides/auth/auth-mfa#overview). + + Having a 2nd factor for recovery frees the user of the burden of having to + store their recovery codes somewhere. It also reduces the attack surface + since multiple recovery codes are usually generated compared to just + having 1 backup factor. + + + Learn more about implementing MFA in your application [in the MFA + guide](https://supabase.com/docs/guides/auth/auth-mfa#overview). - id: mfa-enroll title: mfa.enroll() - $ref: '@supabase/auth-js.GoTrueMFAApi.enroll' + $ref: "@supabase/auth-js.GoTrueMFAApi.enroll" notes: | - Use `totp` or `phone` as the `factorType` and use the returned `id` to create a challenge. - To create a challenge, see [`mfa.challenge()`](/docs/reference/javascript/auth-mfa-challenge). @@ -2251,18 +2536,28 @@ functions: - id: enroll-totp-factor name: Enroll a time-based, one-time password (TOTP) factor isSpotlight: true - code: | + code: > ```js + const { data, error } = await supabase.auth.mfa.enroll({ factorType: 'totp', friendlyName: 'your_friendly_name' }) + // Use the id to create a challenge. - // The challenge can be verified by entering the code generated from the authenticator app. - // The code will be generated upon scanning the qr_code or entering the secret into the authenticator app. - const { id, type, totp: { qr_code, secret, uri }, friendly_name } = data + + // The challenge can be verified by entering the code generated from + the authenticator app. + + // The code will be generated upon scanning the qr_code or entering + the secret into the authenticator app. + + const { id, type, totp: { qr_code, secret, uri }, friendly_name } = + data + const challenge = await supabase.auth.mfa.challenge({ factorId: id }); + ``` response: | ```json @@ -2283,18 +2578,24 @@ functions: - id: enroll-phone-factor name: Enroll a Phone Factor isSpotlight: false - code: | + code: > ```js + const { data, error } = await supabase.auth.mfa.enroll({ factorType: 'phone', friendlyName: 'your_friendly_name', phone: '+12345678', }) - // Use the id to create a challenge and send an SMS with a code to the user. + + // Use the id to create a challenge and send an SMS with a code to the + user. + const { id, type, friendly_name, phone } = data + const challenge = await supabase.auth.mfa.challenge({ factorId: id }); + ``` response: | ```json @@ -2310,11 +2611,16 @@ functions: ``` - id: mfa-challenge title: mfa.challenge() - $ref: '@supabase/auth-js.GoTrueMFAApi.challenge' - notes: | - - An [enrolled factor](/docs/reference/javascript/auth-mfa-enroll) is required before creating a challenge. - - To verify a challenge, see [`mfa.verify()`](/docs/reference/javascript/auth-mfa-verify). - - A phone factor sends a code to the user upon challenge. The channel defaults to `sms` unless otherwise specified. + $ref: "@supabase/auth-js.GoTrueMFAApi.challenge" + notes: > + - An [enrolled factor](/docs/reference/javascript/auth-mfa-enroll) is + required before creating a challenge. + + - To verify a challenge, see + [`mfa.verify()`](/docs/reference/javascript/auth-mfa-verify). + + - A phone factor sends a code to the user upon challenge. The channel + defaults to `sms` unless otherwise specified. examples: - id: create-mfa-challenge name: Create a challenge for a factor @@ -2378,9 +2684,10 @@ functions: ``` - id: mfa-verify title: mfa.verify() - $ref: '@supabase/auth-js.GoTrueMFAApi.verify' - notes: | - - To verify a challenge, please [create a challenge](/docs/reference/javascript/auth-mfa-challenge) first. + $ref: "@supabase/auth-js.GoTrueMFAApi.verify" + notes: > + - To verify a challenge, please [create a + challenge](/docs/reference/javascript/auth-mfa-challenge) first. examples: - id: verify-challenge name: Verify a challenge for a factor @@ -2454,11 +2761,17 @@ functions: ``` - id: mfa-challenge-and-verify title: mfa.challengeAndVerify() - $ref: '@supabase/auth-js.GoTrueMFAApi.challengeAndVerify' - notes: | + $ref: "@supabase/auth-js.GoTrueMFAApi.challengeAndVerify" + notes: > - Intended for use with only TOTP factors. - - An [enrolled factor](/docs/reference/javascript/auth-mfa-enroll) is required before invoking `challengeAndVerify()`. - - Executes [`mfa.challenge()`](/docs/reference/javascript/auth-mfa-challenge) and [`mfa.verify()`](/docs/reference/javascript/auth-mfa-verify) in a single step. + + - An [enrolled factor](/docs/reference/javascript/auth-mfa-enroll) is + required before invoking `challengeAndVerify()`. + + - Executes + [`mfa.challenge()`](/docs/reference/javascript/auth-mfa-challenge) and + [`mfa.verify()`](/docs/reference/javascript/auth-mfa-verify) in a single + step. examples: - id: challenge-and-verify name: Create and verify a challenge for a factor @@ -2531,7 +2844,7 @@ functions: ``` - id: mfa-unenroll title: mfa.unenroll() - $ref: '@supabase/auth-js.GoTrueMFAApi.unenroll' + $ref: "@supabase/auth-js.GoTrueMFAApi.unenroll" examples: - id: unenroll-a-factor name: Unenroll a factor @@ -2553,19 +2866,30 @@ functions: ``` - id: mfa-get-authenticator-assurance-level title: mfa.getAuthenticatorAssuranceLevel() - $ref: '@supabase/auth-js.GoTrueMFAApi.getAuthenticatorAssuranceLevel' - notes: | - - Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism. - - In Supabase, having an AAL of `aal1` refers to having the 1st factor of authentication such as an email and password or OAuth sign-in while `aal2` refers to the 2nd factor of authentication such as a time-based, one-time-password (TOTP) or Phone factor. - - If the user has a verified factor, the `nextLevel` field will return `aal2`, else, it will return `aal1`. + $ref: "@supabase/auth-js.GoTrueMFAApi.getAuthenticatorAssuranceLevel" + notes: > + - Authenticator Assurance Level (AAL) is the measure of the strength of an + authentication mechanism. + + - In Supabase, having an AAL of `aal1` refers to having the 1st factor of + authentication such as an email and password or OAuth sign-in while `aal2` + refers to the 2nd factor of authentication such as a time-based, + one-time-password (TOTP) or Phone factor. + + - If the user has a verified factor, the `nextLevel` field will return + `aal2`, else, it will return `aal1`. examples: - id: get-aal name: Get the AAL details of a session isSpotlight: true - code: | + code: > ```js - const { data, error } = await supabase.auth.mfa.getAuthenticatorAssuranceLevel() + + const { data, error } = await + supabase.auth.mfa.getAuthenticatorAssuranceLevel() + const { currentLevel, nextLevel, currentAuthenticationMethods } = data + ``` response: | ```json @@ -2585,9 +2909,12 @@ functions: ``` - id: admin-api title: Overview - notes: | - - Any method under the `supabase.auth.admin` namespace requires a `service_role` key. - - These methods are considered admin methods and should be called on a trusted server. Never expose your `service_role` key in the browser. + notes: > + - Any method under the `supabase.auth.admin` namespace requires a + `service_role` key. + + - These methods are considered admin methods and should be called on a + trusted server. Never expose your `service_role` key in the browser. examples: - id: create-auth-admin-client name: Create server-side auth client @@ -2608,10 +2935,12 @@ functions: ``` - id: get-user-by-id title: getUserById() - $ref: '@supabase/auth-js.GoTrueAdminApi.getUserById' - notes: | + $ref: "@supabase/auth-js.GoTrueAdminApi.getUserById" + notes: > - Fetches the user object from the database based on the user's id. - - The `getUserById()` method requires the user's id which maps to the `auth.users.id` column. + + - The `getUserById()` method requires the user's id which maps to the + `auth.users.id` column. examples: - id: fetch-the-user-object-using-the-access-token-jwt name: Fetch the user object using the access_token jwt @@ -2664,30 +2993,36 @@ functions: ``` - id: list-users title: listUsers() - $ref: '@supabase/auth-js.GoTrueAdminApi.listUsers' + $ref: "@supabase/auth-js.GoTrueAdminApi.listUsers" notes: | - Defaults to return 50 users per page. examples: - id: get-a-full-list-of-users name: Get a page of users isSpotlight: true - code: | + code: > ```js - const { data: { users }, error } = await supabase.auth.admin.listUsers() + + const { data: { users }, error } = await + supabase.auth.admin.listUsers() + ``` - id: get-paginated-list-of-users name: Paginated list of users isSpotlight: false - code: | + code: > ```js - const { data: { users }, error } = await supabase.auth.admin.listUsers({ + + const { data: { users }, error } = await + supabase.auth.admin.listUsers({ page: 1, perPage: 1000 }) + ``` - id: create-user title: createUser() - $ref: '@supabase/auth-js.GoTrueAdminApi.createUser' + $ref: "@supabase/auth-js.GoTrueAdminApi.createUser" notes: | - To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false. - `createUser()` will not send a confirmation email to the user. You can use [`inviteUserByEmail()`](/docs/reference/javascript/auth-admin-inviteuserbyemail) if you want to send them an email invite instead. @@ -2766,9 +3101,10 @@ functions: ``` - id: delete-user title: deleteUser() - $ref: '@supabase/auth-js.GoTrueAdminApi.deleteUser' - notes: | - - The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column. + $ref: "@supabase/auth-js.GoTrueAdminApi.deleteUser" + notes: > + - The `deleteUser()` method requires the user's ID, which maps to the + `auth.users.id` column. examples: - id: removes-a-user name: Removes a user @@ -2790,18 +3126,27 @@ functions: ``` - id: invite-user-by-email title: inviteUserByEmail() - $ref: '@supabase/auth-js.GoTrueAdminApi.inviteUserByEmail' - notes: | + $ref: "@supabase/auth-js.GoTrueAdminApi.inviteUserByEmail" + notes: > - Sends an invite link to the user's email address. - - The `inviteUserByEmail()` method is typically used by administrators to invite users to join the application. - - Note that PKCE is not supported when using `inviteUserByEmail`. This is because the browser initiating the invite is often different from the browser accepting the invite which makes it difficult to provide the security guarantees required of the PKCE flow. + + - The `inviteUserByEmail()` method is typically used by administrators to + invite users to join the application. + + - Note that PKCE is not supported when using `inviteUserByEmail`. This is + because the browser initiating the invite is often different from the + browser accepting the invite which makes it difficult to provide the + security guarantees required of the PKCE flow. examples: - id: invite-a-user name: Invite a user isSpotlight: true - code: | + code: > ```js - const { data, error } = await supabase.auth.admin.inviteUserByEmail('email@example.com') + + const { data, error } = await + supabase.auth.admin.inviteUserByEmail('email@example.com') + ``` response: | ```json @@ -2850,31 +3195,56 @@ functions: ``` - id: reset-password-for-email title: resetPasswordForEmail() - $ref: '@supabase/auth-js.GoTrueClient.resetPasswordForEmail' - notes: | - - The password reset flow consist of 2 broad steps: (i) Allow the user to login via the password reset link; (ii) Update the user's password. - - The `resetPasswordForEmail()` only sends a password reset link to the user's email. - To update the user's password, see [`updateUser()`](/docs/reference/javascript/auth-updateuser). - - A `PASSWORD_RECOVERY` event will be emitted when the password recovery link is clicked. - You can use [`onAuthStateChange()`](/docs/reference/javascript/auth-onauthstatechange) to listen and invoke a callback function on these events. - - When the user clicks the reset link in the email they are redirected back to your application. - You can configure the URL that the user is redirected to with the `redirectTo` parameter. - See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) to add additional redirect URLs to your project. - - After the user has been redirected successfully, prompt them for a new password and call `updateUser()`: + $ref: "@supabase/auth-js.GoTrueClient.resetPasswordForEmail" + notes: > + - The password reset flow consist of 2 broad steps: (i) Allow the user to + login via the password reset link; (ii) Update the user's password. + + - The `resetPasswordForEmail()` only sends a password reset link to the + user's email. + + To update the user's password, see + [`updateUser()`](/docs/reference/javascript/auth-updateuser). + + - A `PASSWORD_RECOVERY` event will be emitted when the password recovery + link is clicked. + + You can use + [`onAuthStateChange()`](/docs/reference/javascript/auth-onauthstatechange) + to listen and invoke a callback function on these events. + + - When the user clicks the reset link in the email they are redirected + back to your application. + + You can configure the URL that the user is redirected to with the + `redirectTo` parameter. + + See [redirect URLs and + wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) + to add additional redirect URLs to your project. + + - After the user has been redirected successfully, prompt them for a new + password and call `updateUser()`: + ```js + const { data, error } = await supabase.auth.updateUser({ password: new_password }) + ``` examples: - id: reset-password name: Reset password isSpotlight: true - code: | + code: > ```js - const { data, error } = await supabase.auth.resetPasswordForEmail(email, { + + const { data, error } = await + supabase.auth.resetPasswordForEmail(email, { redirectTo: 'https://example.com/update-password', }) + ``` response: | ```json @@ -2886,8 +3256,9 @@ functions: - id: reset-password-react name: Reset password (React) isSpotlight: true - code: | + code: > ```js + /** * Step 1: Send the user an email to get a password reset token. * This email contains a link which sends the user back to your application. @@ -2914,17 +3285,25 @@ functions: ``` - id: generate-link title: generateLink() - $ref: '@supabase/auth-js.GoTrueAdminApi.generateLink' - notes: | - - The following types can be passed into `generateLink()`: `signup`, `magiclink`, `invite`, `recovery`, `email_change_current`, `email_change_new`, `phone_change`. - - `generateLink()` only generates the email link for `email_change_email` if the **Secure email change** is enabled in your project's [email auth provider settings](/dashboard/project/_/auth/providers). - - `generateLink()` handles the creation of the user for `signup`, `invite` and `magiclink`. + $ref: "@supabase/auth-js.GoTrueAdminApi.generateLink" + notes: > + - The following types can be passed into `generateLink()`: `signup`, + `magiclink`, `invite`, `recovery`, `email_change_current`, + `email_change_new`, `phone_change`. + + - `generateLink()` only generates the email link for `email_change_email` + if the **Secure email change** is enabled in your project's [email auth + provider settings](/dashboard/project/_/auth/providers). + + - `generateLink()` handles the creation of the user for `signup`, `invite` + and `magiclink`. overwriteParams: - name: params type: GenerateLinkParams subContent: - name: type - type: signup | invite | magiclink | recovery | email_change_current | email_change_new + type: signup | invite | magiclink | recovery | email_change_current | + email_change_new - name: email type: string - name: password @@ -2934,19 +3313,23 @@ functions: - name: newEmail type: string isOptional: true - description: Only required if type is `email_change_current` or `email_change_new`. + description: Only required if type is `email_change_current` or + `email_change_new`. - name: options type: object isOptional: true subContent: - name: data type: object - description: | - Custom JSON object containing user metadata, to be stored in the `raw_user_meta_data` column. Only accepted if type is `signup`, `invite`, or `magiclink`. + description: > + Custom JSON object containing user metadata, to be stored in + the `raw_user_meta_data` column. Only accepted if type is + `signup`, `invite`, or `magiclink`. - name: redirectTo type: string - description: | - A redirect URL which will be appended to the generated email link. + description: > + A redirect URL which will be appended to the generated email + link. examples: - id: generate-a-signup-link name: Generate a signup link @@ -3043,35 +3426,44 @@ functions: - id: generate-links-to-change-current-email-address name: Generate links to change current email address isSpotlight: false - code: | + code: > ```js - // generate an email change link to be sent to the current email address + + // generate an email change link to be sent to the current email + address + const { data, error } = await supabase.auth.admin.generateLink({ type: 'email_change_current', email: 'current.email@example.com', newEmail: 'new.email@example.com' }) + // generate an email change link to be sent to the new email address + const { data, error } = await supabase.auth.admin.generateLink({ type: 'email_change_new', email: 'current.email@example.com', newEmail: 'new.email@example.com' }) + ``` - id: update-user-by-id title: updateUserById() - $ref: '@supabase/auth-js.GoTrueAdminApi.updateUserById' + $ref: "@supabase/auth-js.GoTrueAdminApi.updateUserById" examples: - id: updates-a-users-email name: Updates a user's email isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '11111111-1111-1111-1111-111111111111', { email: 'new@email.com' } ) + ``` response: | ```json @@ -3128,66 +3520,84 @@ functions: - id: updates-a-users-password name: Updates a user's password isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { password: 'new_password' } ) + ``` - id: updates-a-users-metadata name: Updates a user's metadata isSpotlight: true - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { user_metadata: { hello: 'world' } } ) + ``` - id: updates-a-users-app-metadata name: Updates a user's app_metadata isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { app_metadata: { plan: 'trial' } } ) + ``` - id: confirms-a-users-email-address name: Confirms a user's email address isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { email_confirm: true } ) + ``` - id: confirms-a-users-phone-number name: Confirms a user's phone number isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { phone_confirm: true } ) + ``` - id: ban-a-user name: Ban a user for 100 years isSpotlight: false - code: | + code: > ```js - const { data: user, error } = await supabase.auth.admin.updateUserById( + + const { data: user, error } = await + supabase.auth.admin.updateUserById( '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4', { ban_duration: '100y' } ) + ``` - id: mfa-list-factors-admin title: mfa.listFactors() - $ref: '@supabase/auth-js.GoTrueAdminMFAApi.listFactors' + $ref: "@supabase/auth-js.GoTrueAdminMFAApi.listFactors" examples: - id: list-factors name: List all factors for a user @@ -3216,7 +3626,7 @@ functions: ``` - id: mfa-delete-factor title: mfa.deleteFactor() - $ref: '@supabase/auth-js.GoTrueAdminMFAApi.deleteFactor' + $ref: "@supabase/auth-js.GoTrueAdminMFAApi.deleteFactor" examples: - id: delete-factor name: Delete a factor for a user @@ -3238,13 +3648,24 @@ functions: } ``` - id: select - title: 'Fetch data: select()' - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.select' - notes: | - - By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's [API settings](/dashboard/project/_/settings/api). It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use `range()` queries to paginate through your data. - - `select()` can be combined with [Filters](/docs/reference/javascript/using-filters) - - `select()` can be combined with [Modifiers](/docs/reference/javascript/using-modifiers) - - `apikey` is a reserved keyword if you're using the [Supabase Platform](/docs/guides/platform) and [should be avoided as a column name](https://github.com/supabase/supabase/issues/5465). + title: "Fetch data: select()" + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.select" + notes: > + - By default, Supabase projects return a maximum of 1,000 rows. This + setting can be changed in your project's [API + settings](/dashboard/project/_/settings/api). It's recommended that you + keep it low to limit the payload size of accidental or malicious requests. + You can use `range()` queries to paginate through your data. + + - `select()` can be combined with + [Filters](/docs/reference/javascript/using-filters) + + - `select()` can be combined with + [Modifiers](/docs/reference/javascript/using-modifiers) + + - `apikey` is a reserved keyword if you're using the [Supabase + Platform](/docs/guides/platform) and [should be avoided as a column + name](https://github.com/supabase/supabase/issues/5465). examples: - id: getting-your-data name: Getting your data @@ -3329,8 +3750,9 @@ functions: ``` - id: query-referenced-tables name: Query referenced tables - description: | - If your database has foreign key relationships, you can query related tables too. + description: > + If your database has foreign key relationships, you can query related + tables too. code: | ```js const { data, error } = await supabase @@ -3392,8 +3814,9 @@ functions: ``` - id: query-referenced-tables-with-spaces-in-their-names name: Query referenced tables with spaces in their names - description: | - If your table name contains spaces, you must use double quotes in the `select` statement to reference the table. + description: > + If your table name contains spaces, you must use double quotes in the + `select` statement to reference the table. code: | ```js const { data, error } = await supabase @@ -3541,8 +3964,9 @@ functions: hideCodeBlock: true - id: query-the-same-referenced-table-multiple-times name: Query the same referenced table multiple times - code: | + code: > ```ts + const { data, error } = await supabase .from('messages') .select(` @@ -3551,8 +3975,11 @@ functions: to:receiver_id(name) `) - // To infer types, use the name of the table (in this case `users`) and + // To infer types, use the name of the table (in this case `users`) + and + // the name of the foreign key constraint. + const { data, error } = await supabase .from('messages') .select(` @@ -3603,9 +4030,12 @@ functions: "statusText": "OK" } ``` - description: | - If you need to query the same referenced table twice, use the name of the + description: > + If you need to query the same referenced table twice, use the name of + the + joined column to identify which join to use. You can also give each + column an alias. hideCodeBlock: true - id: query-nested-foreign-tables-through-a-join-table @@ -3763,9 +4193,12 @@ functions: "statusText": "OK" } ``` - description: | - If the filter on a referenced table's column is not satisfied, the referenced + description: > + If the filter on a referenced table's column is not satisfied, the + referenced + table returns `[]` or `null` but the parent table is not filtered out. + If you want to filter out the parent table rows, use the `!inner` hint hideCodeBlock: true - id: querying-referenced-table-with-count @@ -3777,28 +4210,37 @@ functions: .select(`*, instruments(count)`) ``` data: - sql: | + sql: > ```sql + create table orchestral_sections ( "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null, "name" text ); + create table characters ( "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null, "name" text, "section_id" "uuid" references public.orchestral_sections on delete cascade ); + with section as ( insert into orchestral_sections (name) values ('strings') returning id ) + insert into instruments (name, section_id) values + ('violin', (select id from section)), + ('viola', (select id from section)), + ('cello', (select id from section)), + ('double bass', (select id from section)); + ``` response: | ```json @@ -3908,28 +4350,37 @@ functions: .limit(1) ``` data: - sql: | + sql: > ```sql + create table orchestral_sections ( "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null, "name" text ); + create table instruments ( "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null, "name" text, "section_id" "uuid" references public.orchestral_sections on delete cascade ); + with section as ( insert into orchestral_sections (name) values ('woodwinds') returning id ) + insert into instruments (name, section_id) values + ('flute', (select id from section)), + ('clarinet', (select id from section)), + ('bassoon', (select id from section)), + ('piccolo', (select id from section)); + ``` response: | ```json @@ -3944,8 +4395,10 @@ functions: "statusText": "OK" } ``` - description: | - If you don't want to return the referenced table contents, you can leave the parenthesis empty. + description: > + If you don't want to return the referenced table contents, you can + leave the parenthesis empty. + Like `.select('name, orchestral_sections!inner()')`. hideCodeBlock: true - id: switching-schemas-per-query @@ -3982,13 +4435,16 @@ functions: "statusText": "OK" } ``` - description: | - In addition to setting the schema during initialization, you can also switch schemas on a per-query basis. - Make sure you've set up your [database privileges and API settings](/docs/guides/api/using-custom-schemas). + description: > + In addition to setting the schema during initialization, you can also + switch schemas on a per-query basis. + + Make sure you've set up your [database privileges and API + settings](/docs/guides/api/using-custom-schemas). hideCodeBlock: true - id: insert - title: 'Create data: insert()' - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.insert' + title: "Create data: insert()" + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.insert" examples: - id: create-a-record name: Create a record @@ -4059,8 +4515,9 @@ functions: create table countries (id int8 primary key, name text); ``` - response: | + response: > ```json + { "error": { "code": "23505", @@ -4071,16 +4528,19 @@ functions: "status": 409, "statusText": "Conflict" } + ``` description: | A bulk create operation is handled in a single transaction. If any of the inserts fail, none of the rows are inserted. hideCodeBlock: true - id: update - title: 'Modify data: update()' - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.update' - notes: | - - `update()` should always be combined with [Filters](/docs/reference/javascript/using-filters) to target the item(s) you wish to update. + title: "Modify data: update()" + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.update" + notes: > + - `update()` should always be combined with + [Filters](/docs/reference/javascript/using-filters) to target the item(s) + you wish to update. examples: - id: updating-your-data name: Updating your data @@ -4193,14 +4653,17 @@ functions: "statusText": "OK" } ``` - description: | + description: > Postgres offers some + [operators](/docs/guides/database/json#query-the-jsonb-data) for - working with JSON data. Currently, it is only possible to update the entire JSON document. + + working with JSON data. Currently, it is only possible to update the + entire JSON document. hideCodeBlock: true - id: upsert - title: 'Upsert data: upsert()' - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.upsert' + title: "Upsert data: upsert()" + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.upsert" notes: | - Primary keys must be included in `values` to use upsert. examples: @@ -4282,8 +4745,9 @@ functions: hideCodeBlock: true - id: upserting-into-tables-with-constraints name: Upserting into tables with constraints - code: | + code: > ```ts + const { data, error } = await supabase .from('users') .upsert({ id: 42, handle: 'saoirse', display_name: 'Saoirse' }, { onConflict: 'handle' }) @@ -4304,8 +4768,9 @@ functions: values (1, 'saoirse', null); ``` - response: | + response: > ```json + { "error": { "code": "23505", @@ -4316,26 +4781,40 @@ functions: "status": 409, "statusText": "Conflict" } + ``` - description: | + description: > In the following query, `upsert()` implicitly uses the `id` + (primary key) column to determine conflicts. If there is no existing + row with the same `id`, `upsert()` inserts a new row, which - will fail in this case as there is already a row with `handle` `"saoirse"`. + + will fail in this case as there is already a row with `handle` + `"saoirse"`. + Using the `onConflict` option, you can instruct `upsert()` to use + another column with a unique constraint to determine conflicts. hideCodeBlock: true - id: delete - title: 'Delete data: delete()' - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.delete' - notes: | - - `delete()` should always be combined with [filters](/docs/reference/javascript/using-filters) to target the item(s) you wish to delete. + title: "Delete data: delete()" + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.delete" + notes: > + - `delete()` should always be combined with + [filters](/docs/reference/javascript/using-filters) to target the item(s) + you wish to delete. + - If you use `delete()` with filters and you have [RLS](/docs/learn/auth-deep-dive/auth-row-level-security) enabled, only rows visible through `SELECT` policies are deleted. Note that by default no rows are visible, so you need at least one `SELECT`/`ALL` policy that makes the rows visible. - - When using `delete().in()`, specify an array of values to target multiple rows with a single query. This is particularly useful for batch deleting entries that share common criteria, such as deleting users by their IDs. Ensure that the array you provide accurately represents all records you intend to delete to avoid unintended data removal. + - When using `delete().in()`, specify an array of values to target + multiple rows with a single query. This is particularly useful for batch + deleting entries that share common criteria, such as deleting users by + their IDs. Ensure that the array you provide accurately represents all + records you intend to delete to avoid unintended data removal. examples: - id: delete-records name: Delete a single record @@ -4430,19 +4909,28 @@ functions: ``` hideCodeBlock: true - id: rpc - title: 'Postgres functions: rpc()' - description: | - You can call Postgres functions as _Remote Procedure Calls_, logic in your database that you can execute from anywhere. - Functions are useful when the logic rarely changes—like for password resets and updates. + title: "Postgres functions: rpc()" + description: > + You can call Postgres functions as _Remote Procedure Calls_, logic in your + database that you can execute from anywhere. + + Functions are useful when the logic rarely changes—like for password + resets and updates. + ```sql + create or replace function hello_world() returns text as $$ select 'Hello world'; $$ language sql; + ``` - To call Postgres functions on [Read Replicas](/docs/guides/platform/read-replicas), use the `get: true` option. - $ref: '@supabase/postgrest-js.PostgrestClient.rpc' + + To call Postgres functions on [Read + Replicas](/docs/guides/platform/read-replicas), use the `get: true` + option. + $ref: "@supabase/postgrest-js.PostgrestClient.rpc" examples: - id: call-a-postgres-function-without-arguments name: Call a Postgres function without arguments @@ -4491,9 +4979,12 @@ functions: hideCodeBlock: true - id: bulk-processing name: Bulk processing - code: | + code: > ```ts - const { data, error } = await supabase.rpc('add_one_each', { arr: [1, 2, 3] }) + + const { data, error } = await supabase.rpc('add_one_each', { arr: [1, + 2, 3] }) + ``` data: sql: | @@ -4527,8 +5018,9 @@ functions: .single() ``` data: - sql: | + sql: > ```sql + create table countries (id int8 primary key, name text); @@ -4538,9 +5030,11 @@ functions: (1, 'Rohan'), (2, 'The Shire'); - create function list_stored_countries() returns setof countries as $$ + create function list_stored_countries() returns setof countries as + $$ select * from countries; $$ language sql; + ``` response: | ```json @@ -4553,14 +5047,19 @@ functions: "statusText": "OK" } ``` - description: | - Postgres functions that return tables can also be combined with [Filters](/docs/reference/javascript/using-filters) and [Modifiers](/docs/reference/javascript/using-modifiers). + description: > + Postgres functions that return tables can also be combined with + [Filters](/docs/reference/javascript/using-filters) and + [Modifiers](/docs/reference/javascript/using-modifiers). hideCodeBlock: true - id: call-a-read-only-postgres-function name: Call a read-only Postgres function - code: | + code: > ```ts - const { data, error } = await supabase.rpc('hello_world', undefined, { get: true }) + + const { data, error } = await supabase.rpc('hello_world', undefined, { + get: true }) + ``` data: sql: | @@ -4580,18 +5079,25 @@ functions: hideCodeBlock: true - id: using-filters title: Using Filters - description: | + description: > Filters allow you to only return rows that match certain conditions. - Filters can be used on `select()`, `update()`, `upsert()`, and `delete()` queries. - If a Postgres function returns a table response, you can also apply filters. + Filters can be used on `select()`, `update()`, `upsert()`, and `delete()` + queries. + + + If a Postgres function returns a table response, you can also apply + filters. examples: - id: applying-filters name: Applying Filters - description: | - Filters must be applied after any of `select()`, `update()`, `upsert()`, + description: > + Filters must be applied after any of `select()`, `update()`, + `upsert()`, + `delete()`, and `rpc()` and before + [modifiers](/docs/reference/javascript/using-modifiers). code: | ```ts @@ -4607,11 +5113,15 @@ functions: ``` - id: chaining-filters name: Chaining - description: | - Filters can be chained together to produce advanced queries. For example, + description: > + Filters can be chained together to produce advanced queries. For + example, + to query cities with population between 1,000 and 10,000: + ```ts + const { data, error } = await supabase .from('cities') .select('name, country_id') @@ -4628,23 +5138,33 @@ functions: ``` - id: conditional-chaining name: Conditional Chaining - description: | - Filters can be built up one step at a time and then executed. For example: + description: > + Filters can be built up one step at a time and then executed. For + example: + ```ts + const filterByName = null + const filterPopLow = 1000 + const filterPopHigh = 10000 + let query = supabase .from('cities') .select('name, country_id') if (filterByName) { query = query.eq('name', filterByName) } + if (filterPopLow) { query = query.gte('population', filterPopLow) } + if (filterPopHigh) { query = query.lt('population', filterPopHigh) } + const { data, error } = await query + ``` code: | ```ts @@ -4762,7 +5282,7 @@ functions: notation. - id: eq title: eq() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.eq' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.eq" examples: - id: with-select name: With `select()` @@ -4803,7 +5323,7 @@ functions: isSpotlight: true - id: neq title: neq() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.neq' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.neq" examples: - id: with-select name: With `select()` @@ -4848,7 +5368,7 @@ functions: isSpotlight: true - id: gt title: gt() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.gt' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.gt" examples: - id: with-select name: With `select()` @@ -4892,7 +5412,7 @@ functions: to add double quotes e.g. `.gt('"order"', 2)` - id: gte title: gte() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.gte' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.gte" examples: - id: with-select name: With `select()` @@ -4937,7 +5457,7 @@ functions: isSpotlight: true - id: lt title: lt() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.lt' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.lt" examples: - id: with-select name: With `select()` @@ -4978,7 +5498,7 @@ functions: isSpotlight: true - id: lte title: lte() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.lte' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.lte" examples: - id: with-select name: With `select()` @@ -5023,7 +5543,7 @@ functions: isSpotlight: true - id: like title: like() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.like' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.like" examples: - id: with-select name: With `select()` @@ -5064,7 +5584,7 @@ functions: isSpotlight: true - id: ilike title: ilike() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.ilike' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.ilike" examples: - id: with-select name: With `select()` @@ -5105,7 +5625,7 @@ functions: isSpotlight: true - id: is title: is() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.is' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.is" examples: - id: checking-nullness name: Checking for nullness, true or false @@ -5149,7 +5669,7 @@ functions: isSpotlight: true - id: in title: in() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.in' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.in" examples: - id: with-select name: With `select()` @@ -5194,7 +5714,7 @@ functions: isSpotlight: true - id: contains title: contains() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.contains' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.contains" examples: - id: on-array-columns name: On array columns @@ -5206,8 +5726,9 @@ functions: .contains('tags', ['is:open', 'priority:low']) ``` data: - sql: | + sql: > ```sql + create table issues ( id int8 primary key, @@ -5290,8 +5811,9 @@ functions: .contains('address', { postcode: 90210 }) ``` data: - sql: | + sql: > ```sql + create table users ( id int8 primary key, @@ -5320,7 +5842,7 @@ functions: hideCodeBlock: true - id: contained-by title: containedBy() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.containedBy' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.containedBy" examples: - id: on-array-columns name: On array columns @@ -5416,8 +5938,9 @@ functions: .containedBy('address', {}) ``` data: - sql: | + sql: > ```sql + create table users ( id int8 primary key, @@ -5446,7 +5969,7 @@ functions: hideCodeBlock: true - id: range-gt title: rangeGt() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeGt' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.rangeGt" examples: - id: with-select name: With `select()` @@ -5496,7 +6019,7 @@ functions: isSpotlight: true - id: range-gte title: rangeGte() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeGte' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.rangeGte" examples: - id: with-select name: With `select()` @@ -5546,7 +6069,7 @@ functions: isSpotlight: true - id: range-lt title: rangeLt() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeLt' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.rangeLt" examples: - id: with-select name: With `select()` @@ -5596,7 +6119,7 @@ functions: isSpotlight: true - id: range-lte title: rangeLte() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeLte' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.rangeLte" examples: - id: with-select name: With `select()` @@ -5646,7 +6169,7 @@ functions: isSpotlight: true - id: range-adjacent title: rangeAdjacent() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeAdjacent' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.rangeAdjacent" examples: - id: with-select name: With `select()` @@ -5696,7 +6219,7 @@ functions: isSpotlight: true - id: overlaps title: overlaps() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.overlaps' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.overlaps" examples: - id: on-array-columns name: On array columns @@ -5708,8 +6231,9 @@ functions: .overlaps('tags', ['is:closed', 'severity:high']) ``` data: - sql: | + sql: > ```sql + create table issues ( id int8 primary key, @@ -5784,9 +6308,10 @@ functions: hideCodeBlock: true - id: text-search title: textSearch() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.textSearch' - notes: | - - For more information, see [Postgres full text search](/docs/guides/database/full-text-search). + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.textSearch" + notes: > + - For more information, see [Postgres full text + search](/docs/guides/database/full-text-search). examples: - id: text-search name: Text search @@ -5855,14 +6380,23 @@ functions: ``` - id: web-search name: Websearch - description: | + description: > Uses PostgreSQL's `websearch_to_tsquery` function. - This function will never raise syntax errors, which makes it possible to use raw user-supplied input for search, and can be used + + This function will never raise syntax errors, which makes it possible + to use raw user-supplied input for search, and can be used + with advanced operators. - - `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery. - - `"quoted text"`: text inside quote marks will be converted to terms separated by `<->` operators, as if processed by phraseto_tsquery. + + - `unquoted text`: text not inside quote marks will be converted to + terms separated by & operators, as if processed by plainto_tsquery. + + - `"quoted text"`: text inside quote marks will be converted to terms + separated by `<->` operators, as if processed by phraseto_tsquery. + - `OR`: the word “or” will be converted to the | operator. + - `-`: a dash will be converted to the ! operator. code: | ```ts @@ -5876,7 +6410,7 @@ functions: ``` - id: match title: match() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.match' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.match" examples: - id: with-select name: With `select()` @@ -5916,13 +6450,18 @@ functions: isSpotlight: true - id: not title: not() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.not' - notes: | + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.not" + notes: > not() expects you to use the raw PostgREST syntax for the filter values. + ```ts + .not('id', 'in', '(5,6,7)') // Use `()` for `in` filter - .not('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` for array values + + .not('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` + for array values + ``` examples: - id: with-select @@ -5963,13 +6502,20 @@ functions: isSpotlight: true - id: or title: or() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.or' - notes: | - or() expects you to use the raw PostgREST syntax for the filter names and values. + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.or" + notes: > + or() expects you to use the raw PostgREST syntax for the filter names and + values. + ```ts - .or('id.in.(5,6,7), arraycol.cs.{"a","b"}') // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`. - .or('id.in.(5,6,7), arraycol.cd.{"a","b"}') // Use `cd` for `containedBy()` + + .or('id.in.(5,6,7), arraycol.cs.{"a","b"}') // Use `()` for `in` filter, + `{}` for array values and `cs` for `contains()`. + + .or('id.in.(5,6,7), arraycol.cd.{"a","b"}') // Use `cd` for + `containedBy()` + ``` examples: - id: with-select @@ -6048,8 +6594,9 @@ functions: hideCodeBlock: true - id: use-or-on-referenced-tables name: Use `or` on referenced tables - code: | + code: > ```ts + const { data, error } = await supabase .from('orchestral_sections') .select(` @@ -6103,13 +6650,19 @@ functions: hideCodeBlock: true - id: filter title: filter() - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.filter' - notes: | - filter() expects you to use the raw PostgREST syntax for the filter values. + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.filter" + notes: > + filter() expects you to use the raw PostgREST syntax for the filter + values. + ```ts + .filter('id', 'in', '(5,6,7)') // Use `()` for `in` filter - .filter('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` for array values + + .filter('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` + for array values + ``` examples: - id: with-select @@ -6217,7 +6770,7 @@ functions: returns a table response). - id: db-modifiers-select title: select() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.select' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.select" examples: - id: with-upsert name: With `upsert()` @@ -6256,7 +6809,7 @@ functions: isSpotlight: true - id: order title: order() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.order' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.order" examples: - id: with-select name: With `select()` @@ -6305,7 +6858,7 @@ functions: isSpotlight: true - id: on-a-referenced-table name: On a referenced table - code: | + code: > ```ts const { data, error } = await supabase .from('orchestral_sections') @@ -6428,7 +6981,7 @@ functions: hideCodeBlock: true - id: limit title: limit() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.limit' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.limit" examples: - id: with-select name: With `select()` @@ -6522,7 +7075,7 @@ functions: hideCodeBlock: true - id: range title: range() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.range' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.range" examples: - id: with-select name: With `select()` @@ -6564,7 +7117,7 @@ functions: hideCodeBlock: true isSpotlight: true - id: abort-signal - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.abortSignal' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.abortSignal" title: abortSignal() notes: | You can use this to set a timeout for the request. @@ -6623,7 +7176,7 @@ functions: hideCodeBlock: true - id: single title: single() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.single' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.single" examples: - id: with-select name: With `select()` @@ -6662,7 +7215,7 @@ functions: isSpotlight: true - id: maybe-single title: maybeSingle() - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.maybeSingle' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.maybeSingle" examples: - id: with-select name: With `select()` @@ -6697,7 +7250,7 @@ functions: hideCodeBlock: true isSpotlight: true - id: csv - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.csv' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.csv" title: csv() examples: - id: return-data-as-csv @@ -6730,12 +7283,13 @@ functions: "statusText": "OK" } ``` - description: | - By default, the data is returned in JSON format, but can also be returned as Comma Separated Values. + description: > + By default, the data is returned in JSON format, but can also be + returned as Comma Separated Values. hideCodeBlock: true isSpotlight: true - id: returns - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.returns' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.returns" notes: | - Deprecated: use overrideTypes method instead title: returns() @@ -6772,7 +7326,7 @@ functions: hideCodeBlock: true isSpotlight: true - id: overrideTypes - $ref: '@supabase/postgrest-js.PostgrestBuilder.overrideTypes' + $ref: "@supabase/postgrest-js.PostgrestBuilder.overrideTypes" title: overrideTypes() examples: - id: complete-override-type-of-successful-response @@ -6815,9 +7369,12 @@ functions: .select() .overrideTypes>() ``` - response: | + response: > ```ts - let x: typeof data // Array + + let x: typeof data // Array + ``` hideCodeBlock: true isSpotlight: true @@ -6831,23 +7388,37 @@ functions: .maybeSingle() .overrideTypes<{ status: "A" | "B" }>() ``` - response: | + response: > ```ts - let x: typeof data // CountryRowProperties & { status: "A" | "B" } | null + + let x: typeof data // CountryRowProperties & { status: "A" | "B" } | + null + ``` hideCodeBlock: true isSpotlight: true - id: explain - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.explain' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.explain" title: Using Explain - description: | - For debugging slow queries, you can get the [Postgres `EXPLAIN` execution plan](https://www.postgresql.org/docs/current/sql-explain.html) of a query - using the `explain()` method. This works on any query, even for `rpc()` or writes. + description: > + For debugging slow queries, you can get the [Postgres `EXPLAIN` execution + plan](https://www.postgresql.org/docs/current/sql-explain.html) of a query - Explain is not enabled by default as it can reveal sensitive information about your database. - It's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a `pre-request` function. + using the `explain()` method. This works on any query, even for `rpc()` or + writes. - Follow the [Performance Debugging Guide](/docs/guides/database/debugging-performance) to enable the functionality on your project. + + Explain is not enabled by default as it can reveal sensitive information + about your database. + + It's best to only enable this for testing environments but if you wish to + enable it for production you can provide additional protection by using a + `pre-request` function. + + + Follow the [Performance Debugging + Guide](/docs/guides/database/debugging-performance) to enable the + functionality on your project. examples: - id: get-execution-plan name: Get the execution plan @@ -6871,14 +7442,16 @@ functions: (2, 'Leia'), (3, 'Han'); ``` - response: | + response: > ``` + Aggregate (cost=33.34..33.36 rows=1 width=112) -> Limit (cost=0.00..18.33 rows=1000 width=40) -> Seq Scan on characters (cost=0.00..22.00 rows=1200 width=40) ``` - description: | - By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter. + description: > + By default, the data is returned in TEXT format, but can also be + returned as JSON by using the `format` parameter. hideCodeBlock: true isSpotlight: true - id: get-execution-plan-with-analyze-and-verbose @@ -6903,32 +7476,49 @@ functions: (2, 'Leia'), (3, 'Han'); ``` - response: | + response: > ``` - Aggregate (cost=33.34..33.36 rows=1 width=112) (actual time=0.041..0.041 rows=1 loops=1) + + Aggregate (cost=33.34..33.36 rows=1 width=112) (actual + time=0.041..0.041 rows=1 loops=1) Output: NULL::bigint, count(ROW(characters.id, characters.name)), COALESCE(json_agg(ROW(characters.id, characters.name)), '[]'::json), NULLIF(current_setting('response.headers'::text, true), ''::text), NULLIF(current_setting('response.status'::text, true), ''::text) -> Limit (cost=0.00..18.33 rows=1000 width=40) (actual time=0.005..0.006 rows=3 loops=1) Output: characters.id, characters.name -> Seq Scan on public.characters (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1) Output: characters.id, characters.name Query Identifier: -4730654291623321173 + Planning Time: 0.407 ms + Execution Time: 0.119 ms + ``` - description: | - By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter. + description: > + By default, the data is returned in TEXT format, but can also be + returned as JSON by using the `format` parameter. hideCodeBlock: true isSpotlight: false - id: invoke title: invoke() description: | Invoke a Supabase Edge Function. - $ref: '@supabase/functions-js.FunctionsClient.invoke' - notes: | + $ref: "@supabase/functions-js.FunctionsClient.invoke" + notes: > - Requires an Authorization header. - - Invoke params generally match the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec. - - When you pass in a body to your function, we automatically attach the Content-Type header for `Blob`, `ArrayBuffer`, `File`, `FormData` and `String`. If it doesn't match any of these types we assume the payload is `json`, serialize it and attach the `Content-Type` header as `application/json`. You can override this behavior by passing in a `Content-Type` header of your own. - - Responses are automatically parsed as `json`, `blob` and `form-data` depending on the `Content-Type` header sent by your function. Responses are parsed as `text` by default. + + - Invoke params generally match the [Fetch + API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec. + + - When you pass in a body to your function, we automatically attach the + Content-Type header for `Blob`, `ArrayBuffer`, `File`, `FormData` and + `String`. If it doesn't match any of these types we assume the payload is + `json`, serialize it and attach the `Content-Type` header as + `application/json`. You can override this behavior by passing in a + `Content-Type` header of your own. + + - Responses are automatically parsed as `json`, `blob` and `form-data` + depending on the `Content-Type` header sent by your function. Responses + are parsed as `text` by default. examples: - id: basic-invocation name: Basic invocation @@ -6941,12 +7531,18 @@ functions: ``` - id: error-handling name: Error handling - description: | - A `FunctionsHttpError` error is returned if your function throws an error, `FunctionsRelayError` if the Supabase Relay has an error processing your function and `FunctionsFetchError` if there is a network error in calling your function. + description: > + A `FunctionsHttpError` error is returned if your function throws an + error, `FunctionsRelayError` if the Supabase Relay has an error + processing your function and `FunctionsFetchError` if there is a + network error in calling your function. isSpotlight: true - code: | + code: > ```js - import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError } from "@supabase/supabase-js"; + + import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError + } from "@supabase/supabase-js"; + const { data, error } = await supabase.functions.invoke('hello', { headers: { @@ -6955,6 +7551,7 @@ functions: body: { foo: 'bar' } }) + if (error instanceof FunctionsHttpError) { const errorMessage = await error.context.json() console.log('Function returned an error', errorMessage) @@ -6963,11 +7560,14 @@ functions: } else if (error instanceof FunctionsFetchError) { console.log('Fetch error:', error.message) } + ``` - id: passing-custom-headers name: Passing custom headers - description: | - You can pass custom headers to your function. Note: supabase-js automatically passes the `Authorization` header with the signed in user's JWT. + description: > + You can pass custom headers to your function. Note: supabase-js + automatically passes the `Authorization` header with the signed in + user's JWT. isSpotlight: true code: | ```js @@ -6980,8 +7580,9 @@ functions: ``` - id: calling-with-delete-verb name: Calling with DELETE HTTP verb - description: | - You can also set the HTTP verb to `DELETE` when calling your Edge Function. + description: > + You can also set the HTTP verb to `DELETE` when calling your Edge + Function. isSpotlight: true code: | ```js @@ -7024,8 +7625,9 @@ functions: ``` - id: calling-with-get-verb name: Calling with GET HTTP verb - description: | - You can also set the HTTP verb to `GET` when calling your Edge Function. + description: > + You can also set the HTTP verb to `GET` when calling your Edge + Function. isSpotlight: true code: | ```js @@ -7038,12 +7640,21 @@ functions: ``` - id: subscribe title: on().subscribe() - $ref: '@supabase/realtime-js.RealtimeChannel.on' - notes: | + $ref: "@supabase/realtime-js.RealtimeChannel.on" + notes: > - By default, Broadcast and Presence are enabled for all projects. - - By default, listening to database changes is disabled for new projects due to database performance and security concerns. You can turn it on by managing Realtime's [replication](/docs/guides/api#realtime-api-overview). - - You can receive the "previous" data for updates and deletes by setting the table's `REPLICA IDENTITY` to `FULL` (e.g., `ALTER TABLE your_table REPLICA IDENTITY FULL;`). - - Row level security is not applied to delete statements. When RLS is enabled and replica identity is set to full, only the primary key is sent to clients. + + - By default, listening to database changes is disabled for new projects + due to database performance and security concerns. You can turn it on by + managing Realtime's [replication](/docs/guides/api#realtime-api-overview). + + - You can receive the "previous" data for updates and deletes by setting + the table's `REPLICA IDENTITY` to `FULL` (e.g., `ALTER TABLE your_table + REPLICA IDENTITY FULL;`). + + - Row level security is not applied to delete statements. When RLS is + enabled and replica identity is set to full, only the primary key is sent + to clients. examples: - id: listen-to-broadcast name: Listen to broadcast messages @@ -7127,8 +7738,9 @@ functions: ``` - id: listen-to-a-specific-table name: Listen to a specific table - code: | + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => { @@ -7138,8 +7750,9 @@ functions: ``` - id: listen-to-inserts name: Listen to inserts - code: | + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => { @@ -7149,15 +7762,21 @@ functions: ``` - id: listen-to-updates name: Listen to updates - description: | - By default, Supabase will send only the updated record. If you want to receive the previous values as well you can + description: > + By default, Supabase will send only the updated record. If you want to + receive the previous values as well you can + enable full replication for the table you are listening to: + ```sql + alter table "your_table" replica identity full; + ``` - code: | + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => { @@ -7167,15 +7786,21 @@ functions: ``` - id: listen-to-deletes name: Listen to deletes - description: | - By default, Supabase does not send deleted records. If you want to receive the deleted record you can + description: > + By default, Supabase does not send deleted records. If you want to + receive the deleted record you can + enable full replication for the table you are listening too: + ```sql + alter table "your_table" replica identity full; + ``` - code: | + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => { @@ -7185,9 +7810,11 @@ functions: ``` - id: listen-to-multiple-events name: Listen to multiple events - description: You can chain listeners if you want to listen to multiple events for each table. - code: | + description: You can chain listeners if you want to listen to multiple events + for each table. + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted) @@ -7196,11 +7823,16 @@ functions: ``` - id: listening-to-row-level-changes name: Listen to row level changes - description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. - notes: | - - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them. - code: | + description: You can listen to individual rows using the format + `{table}:{col}=eq.{val}` - where `{col}` is the column name, and + `{val}` is the value which you want to match. + notes: > + - ``eq`` filter works with all database types as under the hood, it's + casting both the filter value and the database value to the correct + type and then comparing them. + code: > ```js + supabase .channel('room1') .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated) @@ -7213,7 +7845,7 @@ functions: notes: | - When using REST you don't need to subscribe to the channel - REST calls are only available from 2.37.0 onwards - $ref: '@supabase/realtime-js.RealtimeChannel.send' + $ref: "@supabase/realtime-js.RealtimeChannel.send" examples: - id: send-a-message name: Send a message via websocket @@ -7247,7 +7879,7 @@ functions: ``` - id: get-channels title: getChannels() - $ref: '@supabase/supabase-js.SupabaseClient.getChannels' + $ref: "@supabase/supabase-js.SupabaseClient.getChannels" examples: - id: get-all-channels name: Get all channels @@ -7258,9 +7890,13 @@ functions: ``` - id: remove-channel title: removeChannel() - $ref: '@supabase/supabase-js.SupabaseClient.removeChannel' - notes: | - - Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed. + $ref: "@supabase/supabase-js.SupabaseClient.removeChannel" + notes: > + - Removing a channel is a great way to maintain the performance of your + project's Realtime service as well as your database if you're listening to + Postgres changes. Supabase will automatically handle cleanup 30 seconds + after a client is disconnected, but unused channels may cause degradation + as more clients are simultaneously subscribed. examples: - id: removes-a-channel name: Removes a channel @@ -7271,9 +7907,13 @@ functions: ``` - id: remove-all-channels title: removeAllChannels() - $ref: '@supabase/supabase-js.SupabaseClient.removeAllChannels' - notes: | - - Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed. + $ref: "@supabase/supabase-js.SupabaseClient.removeAllChannels" + notes: > + - Removing channels is a great way to maintain the performance of your + project's Realtime service as well as your database if you're listening to + Postgres changes. Supabase will automatically handle cleanup 30 seconds + after a client is disconnected, but unused channels may cause degradation + as more clients are simultaneously subscribed. examples: - id: remove-all-channels name: Remove all channels @@ -7284,12 +7924,14 @@ functions: ``` - id: list-buckets title: listBuckets() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.listBuckets' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.listBuckets" + notes: > - RLS policy permissions required: - `buckets` table permissions: `select` - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: list-buckets name: List buckets @@ -7322,12 +7964,14 @@ functions: ``` - id: get-bucket title: getBucket() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.getBucket' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.getBucket" + notes: > - RLS policy permissions required: - `buckets` table permissions: `select` - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: get-bucket name: Get bucket @@ -7358,12 +8002,14 @@ functions: ``` - id: create-bucket title: createBucket() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.createBucket' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.createBucket" + notes: > - RLS policy permissions required: - `buckets` table permissions: `insert` - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: create-bucket name: Create bucket @@ -7389,12 +8035,14 @@ functions: ``` - id: empty-bucket title: emptyBucket() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.emptyBucket' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.emptyBucket" + notes: > - RLS policy permissions required: - `buckets` table permissions: `select` - `objects` table permissions: `select` and `delete` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: empty-bucket name: Empty bucket @@ -7416,12 +8064,14 @@ functions: ``` - id: update-bucket title: updateBucket() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.updateBucket' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.updateBucket" + notes: > - RLS policy permissions required: - `buckets` table permissions: `select` and `update` - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: update-bucket name: Update bucket @@ -7447,12 +8097,14 @@ functions: ``` - id: delete-bucket title: deleteBucket() - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.deleteBucket' - notes: | + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.deleteBucket" + notes: > - RLS policy permissions required: - `buckets` table permissions: `select` and `delete` - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: delete-bucket name: Delete bucket @@ -7474,13 +8126,18 @@ functions: ``` - id: from-upload title: from.upload() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.upload' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.upload" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: only `insert` when you are uploading new files and `select`, `insert` and `update` when you are upserting files - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works - - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Upload file using `ArrayBuffer` from base64 file data instead, see example below. + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works + + - For React Native, using either `Blob`, `File` or `FormData` does not + work as intended. Upload file using `ArrayBuffer` from base64 file data + instead, see example below. examples: - id: upload-file name: Upload file @@ -7520,13 +8177,18 @@ functions: ``` - id: from-update title: from.update() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.update' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.update" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `update` and `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works - - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Update file using `ArrayBuffer` from base64 file data instead, see example below. + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works + + - For React Native, using either `Blob`, `File` or `FormData` does not + work as intended. Update file using `ArrayBuffer` from base64 file data + instead, see example below. examples: - id: update-file name: Update file @@ -7567,12 +8229,14 @@ functions: ``` - id: from-move title: from.move() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.move' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.move" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `update` and `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: move-file name: Move file @@ -7595,12 +8259,14 @@ functions: ``` - id: from-copy title: from.copy() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.copy' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.copy" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `insert` and `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: copy-file name: Copy file @@ -7623,12 +8289,14 @@ functions: ``` - id: from-create-signed-url title: from.createSignedUrl() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrl' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.createSignedUrl" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: create-signed-url name: Create Signed URL @@ -7640,14 +8308,16 @@ functions: .from('avatars') .createSignedUrl('folder/avatar1.png', 60) ``` - response: | + response: > ```json + { "data": { "signedUrl": "https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar1.png?token=" }, "error": null } + ``` - id: create-signed-url-with-transformations name: Create a signed URL for an asset with transformations @@ -7678,12 +8348,14 @@ functions: ``` - id: from-create-signed-urls title: from.createSignedUrls() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrls' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.createSignedUrls" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: create-signed-urls name: Create Signed URLs @@ -7695,8 +8367,9 @@ functions: .from('avatars') .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60) ``` - response: | + response: > ```json + { "data": [ { @@ -7714,15 +8387,19 @@ functions: ], "error": null } + ``` - id: from-create-signed-upload-url title: from.createSignedUploadUrl() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUploadUrl' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.createSignedUploadU\ + rl" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `insert` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: create-signed-upload-url name: Create Signed Upload URL @@ -7734,8 +8411,9 @@ functions: .from('avatars') .createSignedUploadUrl('folder/cat.jpg') ``` - response: | + response: > ```json + { "data": { "signedUrl": "https://example.supabase.co/storage/v1/object/upload/sign/avatars/folder/cat.jpg?token=", @@ -7744,21 +8422,25 @@ functions: }, "error": null } + ``` - id: from-upload-to-signed-url title: from.uploadToSignedUrl() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.uploadToSignedUrl' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.uploadToSignedUrl" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: upload-to-signed-url name: Upload to a signed URL isSpotlight: true - code: | + code: > ```js + const { data, error } = await supabase .storage .from('avatars') @@ -7776,13 +8458,20 @@ functions: ``` - id: from-get-public-url title: from.getPublicUrl() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.getPublicUrl' - notes: | - - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [supabase.com/dashboard](https://supabase.com/dashboard), clicking the overflow menu on a bucket and choosing "Make public" + $ref: "@supabase/storage-js.packages/StorageFileApi.default.getPublicUrl" + notes: > + - The bucket needs to be set to public, either via + [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by + going to Storage on + [supabase.com/dashboard](https://supabase.com/dashboard), clicking the + overflow menu on a bucket and choosing "Make public" + - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: none - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: returns-the-url-for-an-asset-in-a-public-bucket name: Returns the URL for an asset in a public bucket @@ -7794,13 +8483,15 @@ functions: .from('public-bucket') .getPublicUrl('folder/avatar1.png') ``` - response: | + response: > ```json + { "data": { "publicUrl": "https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png" } } + ``` - id: transform-asset-in-public-bucket name: Returns the URL for an asset in a public bucket with transformations @@ -7831,12 +8522,14 @@ functions: ``` - id: from-download title: from.download() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.download' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.download" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: download-file name: Download file @@ -7873,12 +8566,14 @@ functions: ``` - id: from-remove title: from.remove() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.remove' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.remove" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `delete` and `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: delete-file name: Delete file @@ -7899,12 +8594,14 @@ functions: ``` - id: from-list title: from.list() - $ref: '@supabase/storage-js.packages/StorageFileApi.default.list' - notes: | + $ref: "@supabase/storage-js.packages/StorageFileApi.default.list" + notes: > - RLS policy permissions required: - `buckets` table permissions: none - `objects` table permissions: `select` - - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works + - Refer to the [Storage + guide](/docs/guides/storage/security/access-control) on how access control + works examples: - id: list-files-in-a-bucket name: List files in a bucket @@ -7960,64 +8657,57 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/supabase-js.GoTrueAdminApi.constructor' + $ref: "@supabase/supabase-js.GoTrueAdminApi.constructor" description: Create an Auth Admin API instance - id: createuser title: createUser - $ref: '@supabase/supabase-js.GoTrueAdminApi.createUser' - description: |- + $ref: "@supabase/supabase-js.GoTrueAdminApi.createUser" + description: >- Creates a new user. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: deleteuser title: deleteUser - $ref: '@supabase/supabase-js.GoTrueAdminApi.deleteUser' + $ref: "@supabase/supabase-js.GoTrueAdminApi.deleteUser" description: Delete a user. Requires a key. - id: generatelink title: generateLink - $ref: '@supabase/supabase-js.GoTrueAdminApi.generateLink' - description: Generates email links and OTPs to be sent via a custom email provider. + $ref: "@supabase/supabase-js.GoTrueAdminApi.generateLink" - id: getuserbyid title: getUserById - $ref: '@supabase/supabase-js.GoTrueAdminApi.getUserById' - description: Get user by id. + $ref: "@supabase/supabase-js.GoTrueAdminApi.getUserById" - id: inviteuserbyemail title: inviteUserByEmail - $ref: '@supabase/supabase-js.GoTrueAdminApi.inviteUserByEmail' - description: Sends an invite link to an email address. + $ref: "@supabase/supabase-js.GoTrueAdminApi.inviteUserByEmail" - id: listusers title: listUsers - $ref: '@supabase/supabase-js.GoTrueAdminApi.listUsers' - description: |- + $ref: "@supabase/supabase-js.GoTrueAdminApi.listUsers" + description: >- Get a list of users. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: signout title: signOut - $ref: '@supabase/supabase-js.GoTrueAdminApi.signOut' - description: Removes a logged-in session. + $ref: "@supabase/supabase-js.GoTrueAdminApi.signOut" - id: updateuserbyid title: updateUserById - $ref: '@supabase/supabase-js.GoTrueAdminApi.updateUserById' - description: Updates the user data. + $ref: "@supabase/supabase-js.GoTrueAdminApi.updateUserById" - id: constructor title: constructor - $ref: '@supabase/supabase-js.RealtimeChannel.constructor' + $ref: "@supabase/supabase-js.RealtimeChannel.constructor" description: Create a Realtime channel instance - id: httpsend title: httpSend - $ref: '@supabase/supabase-js.RealtimeChannel.httpSend' - description: |- - Sends a broadcast message explicitly via REST API. - - This method always uses the REST API endpoint regardless of WebSocket connection state. - Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback. + $ref: "@supabase/supabase-js.RealtimeChannel.httpSend" - id: on title: on - $ref: '@supabase/supabase-js.RealtimeChannel.on' - description: Creates an event handler that listens to changes. + $ref: "@supabase/supabase-js.RealtimeChannel.on" - id: presencestate title: presenceState - $ref: '@supabase/supabase-js.RealtimeChannel.presenceState' + $ref: "@supabase/supabase-js.RealtimeChannel.presenceState" description: Access current presence state examples: - id: example-1 @@ -8030,12 +8720,10 @@ functions: ``` - id: send title: send - $ref: '@supabase/supabase-js.RealtimeChannel.send' - description: Sends a message into the channel. + $ref: "@supabase/supabase-js.RealtimeChannel.send" - id: subscribe title: subscribe - $ref: '@supabase/supabase-js.RealtimeChannel.subscribe' - description: Subscribe registers your client with the server + $ref: "@supabase/supabase-js.RealtimeChannel.subscribe" examples: - id: example-1 name: Subscribe to channel @@ -8050,37 +8738,43 @@ functions: ``` - id: teardown title: teardown - $ref: '@supabase/supabase-js.RealtimeChannel.teardown' - description: |- - Teardown the channel. - - Destroys and stops related timers. + $ref: "@supabase/supabase-js.RealtimeChannel.teardown" - id: track title: track - $ref: '@supabase/supabase-js.RealtimeChannel.track' + $ref: "@supabase/supabase-js.RealtimeChannel.track" description: Track user presence in channel examples: - id: example-1 name: Track user presence - code: |- + code: >- ```typescript + const channel = supabase.channel('room1') - await channel.track({ user_id: 'user-123', online_at: new Date().toISOString() }) + + await channel.track({ user_id: 'user-123', online_at: new + Date().toISOString() }) + ``` - id: unsubscribe title: unsubscribe - $ref: '@supabase/supabase-js.RealtimeChannel.unsubscribe' - description: |- + $ref: "@supabase/supabase-js.RealtimeChannel.unsubscribe" + description: >- Leaves the channel. - Unsubscribes from server events, and instructs channel to terminate on server. + + Unsubscribes from server events, and instructs channel to terminate on + server. + Triggers onClose() hooks. - To receive leave acknowledgements, use the a hook to bind to the server ack, ie: + + To receive leave acknowledgements, use the a hook to bind to the server + ack, ie: + channel.unsubscribe().receive("ok", () => alert("left!") ) - id: untrack title: untrack - $ref: '@supabase/supabase-js.RealtimeChannel.untrack' + $ref: "@supabase/supabase-js.RealtimeChannel.untrack" description: Stop tracking user presence examples: - id: example-1 @@ -8092,7 +8786,7 @@ functions: ``` - id: updatejoinpayload title: updateJoinPayload - $ref: '@supabase/supabase-js.RealtimeChannel.updateJoinPayload' + $ref: "@supabase/supabase-js.RealtimeChannel.updateJoinPayload" description: Update channel join payload examples: - id: example-1 @@ -8104,11 +8798,10 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/supabase-js.RealtimeClient.constructor' - description: Initializes the Socket. + $ref: "@supabase/supabase-js.RealtimeClient.constructor" - id: channel title: channel - $ref: '@supabase/supabase-js.RealtimeClient.channel' + $ref: "@supabase/supabase-js.RealtimeClient.channel" description: Create or retrieve a channel examples: - id: example-1 @@ -8120,50 +8813,44 @@ functions: ``` - id: connect title: connect - $ref: '@supabase/supabase-js.RealtimeClient.connect' - description: Connects the socket, unless already connected. + $ref: "@supabase/supabase-js.RealtimeClient.connect" - id: connectionstate title: connectionState - $ref: '@supabase/supabase-js.RealtimeClient.connectionState' - description: Returns the current state of the socket. + $ref: "@supabase/supabase-js.RealtimeClient.connectionState" - id: disconnect title: disconnect - $ref: '@supabase/supabase-js.RealtimeClient.disconnect' - description: Disconnects the socket. + $ref: "@supabase/supabase-js.RealtimeClient.disconnect" - id: endpointurl title: endpointURL - $ref: '@supabase/supabase-js.RealtimeClient.endpointURL' - description: Returns the URL of the websocket. + $ref: "@supabase/supabase-js.RealtimeClient.endpointURL" - id: flushsendbuffer title: flushSendBuffer - $ref: '@supabase/supabase-js.RealtimeClient.flushSendBuffer' - description: Flushes send buffer + $ref: "@supabase/supabase-js.RealtimeClient.flushSendBuffer" - id: getchannels title: getChannels - $ref: '@supabase/supabase-js.RealtimeClient.getChannels' - description: Returns all created channels + $ref: "@supabase/supabase-js.RealtimeClient.getChannels" - id: isconnected title: isConnected - $ref: '@supabase/supabase-js.RealtimeClient.isConnected' + $ref: "@supabase/supabase-js.RealtimeClient.isConnected" description: Returns is the connection is open. - id: isconnecting title: isConnecting - $ref: '@supabase/supabase-js.RealtimeClient.isConnecting' + $ref: "@supabase/supabase-js.RealtimeClient.isConnecting" description: Returns if the connection is currently connecting. - id: isdisconnecting title: isDisconnecting - $ref: '@supabase/supabase-js.RealtimeClient.isDisconnecting' + $ref: "@supabase/supabase-js.RealtimeClient.isDisconnecting" description: Returns if the connection is currently disconnecting. - id: log title: log - $ref: '@supabase/supabase-js.RealtimeClient.log' + $ref: "@supabase/supabase-js.RealtimeClient.log" description: |- Logs the message. For customized logging, can be overridden. - id: onheartbeat title: onHeartbeat - $ref: '@supabase/supabase-js.RealtimeClient.onHeartbeat' + $ref: "@supabase/supabase-js.RealtimeClient.onHeartbeat" description: Handle heartbeat events examples: - id: example-1 @@ -8177,202 +8864,176 @@ functions: ``` - id: push title: push - $ref: '@supabase/supabase-js.RealtimeClient.push' - description: |- - Push out a message if the socket is connected. - - If the socket is not connected, the message gets enqueued within a local buffer, and sent out when a connection is next established. + $ref: "@supabase/supabase-js.RealtimeClient.push" - id: removeallchannels title: removeAllChannels - $ref: '@supabase/supabase-js.RealtimeClient.removeAllChannels' - description: Unsubscribes and removes all channels + $ref: "@supabase/supabase-js.RealtimeClient.removeAllChannels" - id: removechannel title: removeChannel - $ref: '@supabase/supabase-js.RealtimeClient.removeChannel' - description: Unsubscribes and removes a single channel + $ref: "@supabase/supabase-js.RealtimeClient.removeChannel" - id: sendheartbeat title: sendHeartbeat - $ref: '@supabase/supabase-js.RealtimeClient.sendHeartbeat' - description: Sends a heartbeat message if the socket is connected. + $ref: "@supabase/supabase-js.RealtimeClient.sendHeartbeat" - id: setauth title: setAuth - $ref: '@supabase/supabase-js.RealtimeClient.setAuth' - description: |- - Sets the JWT access token used for channel subscription authorization and Realtime RLS. + $ref: "@supabase/supabase-js.RealtimeClient.setAuth" + description: >- + Sets the JWT access token used for channel subscription authorization and + Realtime RLS. - If param is null it will use the callback function or the token set on the client. - On callback used, it will set the value of the token internal to the client. + If param is null it will use the callback function or the token set on + the client. + + + On callback used, it will set the value of the token internal to the + client. - id: channel title: channel - $ref: '@supabase/supabase-js.SupabaseClient.channel' - description: Creates a Realtime channel with Broadcast, Presence, and Postgres Changes. + $ref: "@supabase/supabase-js.SupabaseClient.channel" - id: from title: from - $ref: '@supabase/supabase-js.SupabaseClient.from' - description: Perform a query on a table or a view. + $ref: "@supabase/supabase-js.SupabaseClient.from" - id: rpc title: rpc - $ref: '@supabase/supabase-js.SupabaseClient.rpc' - description: Perform a function call. + $ref: "@supabase/supabase-js.SupabaseClient.rpc" - id: schema title: schema - $ref: '@supabase/supabase-js.SupabaseClient.schema' - description: |- - Select a schema to query or perform an function (rpc) call. - - The schema needs to be on the list of exposed schemas inside Supabase. + $ref: "@supabase/supabase-js.SupabaseClient.schema" - id: constructor title: constructor - $ref: '@supabase/auth-js.GoTrueAdminApi.constructor' + $ref: "@supabase/auth-js.GoTrueAdminApi.constructor" description: Create an Auth Admin API instance - id: signout title: signOut - $ref: '@supabase/auth-js.GoTrueAdminApi.signOut' - description: Removes a logged-in session. + $ref: "@supabase/auth-js.GoTrueAdminApi.signOut" - id: constructor title: constructor - $ref: '@supabase/realtime-js.RealtimeChannel.constructor' + $ref: "@supabase/realtime-js.RealtimeChannel.constructor" description: Create a Realtime channel instance - id: httpsend title: httpSend - $ref: '@supabase/realtime-js.RealtimeChannel.httpSend' - description: |- - Sends a broadcast message explicitly via REST API. - - This method always uses the REST API endpoint regardless of WebSocket connection state. - Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback. + $ref: "@supabase/realtime-js.RealtimeChannel.httpSend" - id: presencestate title: presenceState - $ref: '@supabase/realtime-js.RealtimeChannel.presenceState' + $ref: "@supabase/realtime-js.RealtimeChannel.presenceState" description: Access current presence state - id: subscribe title: subscribe - $ref: '@supabase/realtime-js.RealtimeChannel.subscribe' - description: Subscribe registers your client with the server + $ref: "@supabase/realtime-js.RealtimeChannel.subscribe" - id: teardown title: teardown - $ref: '@supabase/realtime-js.RealtimeChannel.teardown' - description: |- - Teardown the channel. - - Destroys and stops related timers. + $ref: "@supabase/realtime-js.RealtimeChannel.teardown" - id: track title: track - $ref: '@supabase/realtime-js.RealtimeChannel.track' + $ref: "@supabase/realtime-js.RealtimeChannel.track" description: Track user presence in channel - id: unsubscribe title: unsubscribe - $ref: '@supabase/realtime-js.RealtimeChannel.unsubscribe' - description: |- + $ref: "@supabase/realtime-js.RealtimeChannel.unsubscribe" + description: >- Leaves the channel. - Unsubscribes from server events, and instructs channel to terminate on server. + + Unsubscribes from server events, and instructs channel to terminate on + server. + Triggers onClose() hooks. - To receive leave acknowledgements, use the a hook to bind to the server ack, ie: + + To receive leave acknowledgements, use the a hook to bind to the server + ack, ie: + channel.unsubscribe().receive("ok", () => alert("left!") ) - id: untrack title: untrack - $ref: '@supabase/realtime-js.RealtimeChannel.untrack' + $ref: "@supabase/realtime-js.RealtimeChannel.untrack" description: Stop tracking user presence - id: updatejoinpayload title: updateJoinPayload - $ref: '@supabase/realtime-js.RealtimeChannel.updateJoinPayload' + $ref: "@supabase/realtime-js.RealtimeChannel.updateJoinPayload" description: Update channel join payload - id: constructor title: constructor - $ref: '@supabase/realtime-js.RealtimeClient.constructor' - description: Initializes the Socket. + $ref: "@supabase/realtime-js.RealtimeClient.constructor" - id: channel title: channel - $ref: '@supabase/realtime-js.RealtimeClient.channel' + $ref: "@supabase/realtime-js.RealtimeClient.channel" description: Create or retrieve a channel - id: connect title: connect - $ref: '@supabase/realtime-js.RealtimeClient.connect' - description: Connects the socket, unless already connected. + $ref: "@supabase/realtime-js.RealtimeClient.connect" - id: connectionstate title: connectionState - $ref: '@supabase/realtime-js.RealtimeClient.connectionState' - description: Returns the current state of the socket. + $ref: "@supabase/realtime-js.RealtimeClient.connectionState" - id: disconnect title: disconnect - $ref: '@supabase/realtime-js.RealtimeClient.disconnect' - description: Disconnects the socket. + $ref: "@supabase/realtime-js.RealtimeClient.disconnect" - id: endpointurl title: endpointURL - $ref: '@supabase/realtime-js.RealtimeClient.endpointURL' - description: Returns the URL of the websocket. + $ref: "@supabase/realtime-js.RealtimeClient.endpointURL" - id: flushsendbuffer title: flushSendBuffer - $ref: '@supabase/realtime-js.RealtimeClient.flushSendBuffer' - description: Flushes send buffer + $ref: "@supabase/realtime-js.RealtimeClient.flushSendBuffer" - id: getchannels title: getChannels - $ref: '@supabase/realtime-js.RealtimeClient.getChannels' - description: Returns all created channels + $ref: "@supabase/realtime-js.RealtimeClient.getChannels" - id: isconnected title: isConnected - $ref: '@supabase/realtime-js.RealtimeClient.isConnected' + $ref: "@supabase/realtime-js.RealtimeClient.isConnected" description: Returns is the connection is open. - id: isconnecting title: isConnecting - $ref: '@supabase/realtime-js.RealtimeClient.isConnecting' + $ref: "@supabase/realtime-js.RealtimeClient.isConnecting" description: Returns if the connection is currently connecting. - id: isdisconnecting title: isDisconnecting - $ref: '@supabase/realtime-js.RealtimeClient.isDisconnecting' + $ref: "@supabase/realtime-js.RealtimeClient.isDisconnecting" description: Returns if the connection is currently disconnecting. - id: log title: log - $ref: '@supabase/realtime-js.RealtimeClient.log' + $ref: "@supabase/realtime-js.RealtimeClient.log" description: |- Logs the message. For customized logging, can be overridden. - id: onheartbeat title: onHeartbeat - $ref: '@supabase/realtime-js.RealtimeClient.onHeartbeat' + $ref: "@supabase/realtime-js.RealtimeClient.onHeartbeat" description: Handle heartbeat events - id: push title: push - $ref: '@supabase/realtime-js.RealtimeClient.push' - description: |- - Push out a message if the socket is connected. - - If the socket is not connected, the message gets enqueued within a local buffer, and sent out when a connection is next established. + $ref: "@supabase/realtime-js.RealtimeClient.push" - id: removeallchannels title: removeAllChannels - $ref: '@supabase/realtime-js.RealtimeClient.removeAllChannels' - description: Unsubscribes and removes all channels + $ref: "@supabase/realtime-js.RealtimeClient.removeAllChannels" - id: removechannel title: removeChannel - $ref: '@supabase/realtime-js.RealtimeClient.removeChannel' - description: Unsubscribes and removes a single channel + $ref: "@supabase/realtime-js.RealtimeClient.removeChannel" - id: sendheartbeat title: sendHeartbeat - $ref: '@supabase/realtime-js.RealtimeClient.sendHeartbeat' - description: Sends a heartbeat message if the socket is connected. + $ref: "@supabase/realtime-js.RealtimeClient.sendHeartbeat" - id: setauth title: setAuth - $ref: '@supabase/realtime-js.RealtimeClient.setAuth' - description: |- - Sets the JWT access token used for channel subscription authorization and Realtime RLS. + $ref: "@supabase/realtime-js.RealtimeClient.setAuth" + description: >- + Sets the JWT access token used for channel subscription authorization and + Realtime RLS. - If param is null it will use the callback function or the token set on the client. - On callback used, it will set the value of the token internal to the client. + If param is null it will use the callback function or the token set on + the client. + + + On callback used, it will set the value of the token internal to the + client. - id: constructor title: constructor - $ref: '@supabase/storage-js.index.StorageVectorsClient.constructor' - description: Create a Storage client instance + $ref: "@supabase/storage-js.index.StorageVectorsClient.constructor" + description: Create a Storage Vector client instance - id: from title: from - $ref: '@supabase/storage-js.index.StorageVectorsClient.from' - description: |- - Access operations for a specific vector bucket - Returns a scoped client for index and vector operations within the bucket + $ref: "@supabase/storage-js.index.StorageVectorsClient.from" examples: - id: example-1 name: Example 1 @@ -8393,14 +9054,10 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/storage-js.index.VectorBucketApi.constructor' - description: Creates a new VectorBucketApi instance + $ref: "@supabase/storage-js.index.VectorBucketApi.constructor" - id: createbucket title: createBucket - $ref: '@supabase/storage-js.index.VectorBucketApi.createBucket' - description: |- - Creates a new vector bucket - Vector buckets are containers for vector indexes and their data + $ref: "@supabase/storage-js.index.VectorBucketApi.createBucket" examples: - id: example-1 name: Example 1 @@ -8413,10 +9070,7 @@ functions: ``` - id: deletebucket title: deleteBucket - $ref: '@supabase/storage-js.index.VectorBucketApi.deleteBucket' - description: |- - Deletes a vector bucket - Bucket must be empty before deletion (all indexes must be removed first) + $ref: "@supabase/storage-js.index.VectorBucketApi.deleteBucket" examples: - id: example-1 name: Example 1 @@ -8430,33 +9084,33 @@ functions: ``` - id: getbucket title: getBucket - $ref: '@supabase/storage-js.index.VectorBucketApi.getBucket' - description: |- - Retrieves metadata for a specific vector bucket - Returns bucket configuration including encryption settings and creation time + $ref: "@supabase/storage-js.index.VectorBucketApi.getBucket" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript + const { data, error } = await client.getBucket('embeddings-prod') + if (data) { console.log('Bucket created at:', new Date(data.vectorBucket.creationTime! * 1000)) } + ``` - id: listbuckets title: listBuckets - $ref: '@supabase/storage-js.index.VectorBucketApi.listBuckets' - description: |- - Lists vector buckets with optional filtering and pagination - Supports prefix-based filtering and paginated results + $ref: "@supabase/storage-js.index.VectorBucketApi.listBuckets" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript + // List all buckets with prefix 'prod-' + const { data, error } = await client.listBuckets({ prefix: 'prod-' }) + if (data) { console.log('Found buckets:', data.buckets.length) // Fetch next page if available @@ -8464,32 +9118,32 @@ functions: const next = await client.listBuckets({ nextToken: data.nextToken }) } } + ``` - id: throwonerror title: throwOnError - $ref: '@supabase/storage-js.index.VectorBucketApi.throwOnError' - description: |- - Enable throwing errors instead of returning them in the response - When enabled, failed operations will throw instead of returning { data: null, error } + $ref: "@supabase/storage-js.index.VectorBucketApi.throwOnError" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript + const client = new VectorBucketApi(url, headers) + client.throwOnError() - const { data } = await client.createBucket('my-bucket') // throws on error + + const { data } = await client.createBucket('my-bucket') // throws on + error + ``` - id: constructor title: constructor - $ref: '@supabase/storage-js.index.VectorBucketScope.constructor' + $ref: "@supabase/storage-js.index.VectorBucketScope.constructor" description: Create a VectorBucketScope instance - id: createindex title: createIndex - $ref: '@supabase/storage-js.index.VectorBucketScope.createIndex' - description: |- - Creates a new vector index in this bucket - Convenience method that automatically includes the bucket name + $ref: "@supabase/storage-js.index.VectorBucketScope.createIndex" examples: - id: example-1 name: Example 1 @@ -8508,10 +9162,7 @@ functions: ``` - id: deleteindex title: deleteIndex - $ref: '@supabase/storage-js.index.VectorBucketScope.deleteIndex' - description: |- - Deletes an index from this bucket - Convenience method that automatically includes the bucket name + $ref: "@supabase/storage-js.index.VectorBucketScope.deleteIndex" examples: - id: example-1 name: Example 1 @@ -8522,10 +9173,7 @@ functions: ``` - id: getindex title: getIndex - $ref: '@supabase/storage-js.index.VectorBucketScope.getIndex' - description: |- - Retrieves metadata for a specific index in this bucket - Convenience method that automatically includes the bucket name + $ref: "@supabase/storage-js.index.VectorBucketScope.getIndex" examples: - id: example-1 name: Example 1 @@ -8537,36 +9185,37 @@ functions: ``` - id: index title: index - $ref: '@supabase/storage-js.index.VectorBucketScope.index' - description: |- - Access operations for a specific index within this bucket - Returns a scoped client for vector data operations + $ref: "@supabase/storage-js.index.VectorBucketScope.index" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + // Insert vectors + await index.putVectors({ vectors: [ { key: 'doc-1', data: { float32: [...] }, metadata: { title: 'Intro' } } ] }) + // Query similar vectors + const { data } = await index.queryVectors({ queryVector: { float32: [...] }, topK: 5 }) + ``` - id: listindexes title: listIndexes - $ref: '@supabase/storage-js.index.VectorBucketScope.listIndexes' - description: |- - Lists indexes in this bucket - Convenience method that automatically includes the bucket name + $ref: "@supabase/storage-js.index.VectorBucketScope.listIndexes" examples: - id: example-1 name: Example 1 @@ -8577,14 +9226,11 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/storage-js.index.VectorDataApi.constructor' + $ref: "@supabase/storage-js.index.VectorDataApi.constructor" description: Create a VectorDataApi instance - id: deletevectors title: deleteVectors - $ref: '@supabase/storage-js.index.VectorDataApi.deleteVectors' - description: |- - Deletes vectors by their keys in batch - Accepts 1-500 keys per request + $ref: "@supabase/storage-js.index.VectorDataApi.deleteVectors" examples: - id: example-1 name: Example 1 @@ -8601,11 +9247,7 @@ functions: ``` - id: getvectors title: getVectors - $ref: '@supabase/storage-js.index.VectorDataApi.getVectors' - description: |- - Retrieves vectors by their keys in batch - Optionally includes vector data and/or metadata in response - Additional permissions required when returning data or metadata + $ref: "@supabase/storage-js.index.VectorDataApi.getVectors" examples: - id: example-1 name: Example 1 @@ -8624,11 +9266,7 @@ functions: ``` - id: listvectors title: listVectors - $ref: '@supabase/storage-js.index.VectorDataApi.listVectors' - description: |- - Lists/scans vectors in an index with pagination - Supports parallel scanning via segment configuration for high-throughput scenarios - Additional permissions required when returning data or metadata + $ref: "@supabase/storage-js.index.VectorDataApi.listVectors" examples: - id: example-1 name: Example 1 @@ -8664,10 +9302,7 @@ functions: ``` - id: putvectors title: putVectors - $ref: '@supabase/storage-js.index.VectorDataApi.putVectors' - description: |- - Inserts or updates vectors in batch (upsert operation) - Accepts 1-500 vectors per request. Larger batches should be split + $ref: "@supabase/storage-js.index.VectorDataApi.putVectors" examples: - id: example-1 name: Example 1 @@ -8692,11 +9327,7 @@ functions: ``` - id: queryvectors title: queryVectors - $ref: '@supabase/storage-js.index.VectorDataApi.queryVectors' - description: |- - Queries for similar vectors using approximate nearest neighbor (ANN) search - Returns top-K most similar vectors based on the configured distance metric - Supports optional metadata filtering (requires GetVectors permission) + $ref: "@supabase/storage-js.index.VectorDataApi.queryVectors" examples: - id: example-1 name: Example 1 @@ -8724,10 +9355,7 @@ functions: ``` - id: throwonerror title: throwOnError - $ref: '@supabase/storage-js.index.VectorDataApi.throwOnError' - description: |- - Enable throwing errors instead of returning them in the response - When enabled, failed operations will throw instead of returning { data: null, error } + $ref: "@supabase/storage-js.index.VectorDataApi.throwOnError" examples: - id: example-1 name: Example 1 @@ -8739,14 +9367,11 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/storage-js.index.VectorIndexApi.constructor' + $ref: "@supabase/storage-js.index.VectorIndexApi.constructor" description: Create a VectorIndexApi instance - id: createindex title: createIndex - $ref: '@supabase/storage-js.index.VectorIndexApi.createIndex' - description: |- - Creates a new vector index within a bucket - Defines the schema for vectors including dimensionality, distance metric, and metadata config + $ref: "@supabase/storage-js.index.VectorIndexApi.createIndex" examples: - id: example-1 name: Example 1 @@ -8765,44 +9390,44 @@ functions: ``` - id: deleteindex title: deleteIndex - $ref: '@supabase/storage-js.index.VectorIndexApi.deleteIndex' - description: |- - Deletes a vector index and all its data - This operation removes the index schema and all vectors stored in the index + $ref: "@supabase/storage-js.index.VectorIndexApi.deleteIndex" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript + // Delete an index and all its vectors - const { error } = await client.deleteIndex('embeddings-prod', 'old-index') + + const { error } = await client.deleteIndex('embeddings-prod', + 'old-index') + if (!error) { console.log('Index deleted successfully') } + ``` - id: getindex title: getIndex - $ref: '@supabase/storage-js.index.VectorIndexApi.getIndex' - description: |- - Retrieves metadata for a specific vector index - Returns index configuration including dimension, distance metric, and metadata settings + $ref: "@supabase/storage-js.index.VectorIndexApi.getIndex" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const { data, error } = await client.getIndex('embeddings-prod', 'documents-openai-small') + + const { data, error } = await client.getIndex('embeddings-prod', + 'documents-openai-small') + if (data) { console.log('Index dimension:', data.index.dimension) console.log('Distance metric:', data.index.distanceMetric) } + ``` - id: listindexes title: listIndexes - $ref: '@supabase/storage-js.index.VectorIndexApi.listIndexes' - description: |- - Lists vector indexes within a bucket with optional filtering and pagination - Supports prefix-based filtering and paginated results + $ref: "@supabase/storage-js.index.VectorIndexApi.listIndexes" examples: - id: example-1 name: Example 1 @@ -8826,10 +9451,7 @@ functions: ``` - id: throwonerror title: throwOnError - $ref: '@supabase/storage-js.index.VectorIndexApi.throwOnError' - description: |- - Enable throwing errors instead of returning them in the response - When enabled, failed operations will throw instead of returning { data: null, error } + $ref: "@supabase/storage-js.index.VectorIndexApi.throwOnError" examples: - id: example-1 name: Example 1 @@ -8841,70 +9463,73 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/storage-js.index.VectorIndexScope.constructor' + $ref: "@supabase/storage-js.index.VectorIndexScope.constructor" description: Create a VectorIndexScope instance - id: deletevectors title: deleteVectors - $ref: '@supabase/storage-js.index.VectorIndexScope.deleteVectors' - description: |- - Deletes vectors by keys from this index - Convenience method that automatically includes bucket and index names + $ref: "@supabase/storage-js.index.VectorIndexScope.deleteVectors" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + await index.deleteVectors({ keys: ['doc-1', 'doc-2', 'doc-3'] }) + ``` - id: getvectors title: getVectors - $ref: '@supabase/storage-js.index.VectorIndexScope.getVectors' - description: |- - Retrieves vectors by keys from this index - Convenience method that automatically includes bucket and index names + $ref: "@supabase/storage-js.index.VectorIndexScope.getVectors" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + const { data } = await index.getVectors({ keys: ['doc-1', 'doc-2'], returnMetadata: true }) + ``` - id: listvectors title: listVectors - $ref: '@supabase/storage-js.index.VectorIndexScope.listVectors' - description: |- - Lists vectors in this index with pagination - Convenience method that automatically includes bucket and index names + $ref: "@supabase/storage-js.index.VectorIndexScope.listVectors" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + const { data } = await index.listVectors({ maxResults: 500, returnMetadata: true }) + ``` - id: putvectors title: putVectors - $ref: '@supabase/storage-js.index.VectorIndexScope.putVectors' - description: |- - Inserts or updates vectors in this index - Convenience method that automatically includes bucket and index names + $ref: "@supabase/storage-js.index.VectorIndexScope.putVectors" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + await index.putVectors({ vectors: [ { @@ -8914,19 +9539,20 @@ functions: } ] }) + ``` - id: queryvectors title: queryVectors - $ref: '@supabase/storage-js.index.VectorIndexScope.queryVectors' - description: |- - Queries for similar vectors in this index - Convenience method that automatically includes bucket and index names + $ref: "@supabase/storage-js.index.VectorIndexScope.queryVectors" examples: - id: example-1 name: Example 1 - code: |- + code: >- ```typescript - const index = client.bucket('embeddings-prod').index('documents-openai') + + const index = + client.bucket('embeddings-prod').index('documents-openai') + const { data } = await index.queryVectors({ queryVector: { float32: [0.1, 0.2, ...] }, topK: 5, @@ -8934,105 +9560,102 @@ functions: returnDistance: true, returnMetadata: true }) + ``` - id: constructor title: constructor - $ref: '@supabase/functions-js.FunctionsClient.constructor' + $ref: "@supabase/functions-js.FunctionsClient.constructor" description: Create a Functions client instance - id: setauth title: setAuth - $ref: '@supabase/functions-js.FunctionsClient.setAuth' - description: Updates the authorization header + $ref: "@supabase/functions-js.FunctionsClient.setAuth" - id: constructor title: constructor - $ref: '@supabase/auth-js.GoTrueClient.constructor' - description: Create a new client for use in the browser. + $ref: "@supabase/auth-js.GoTrueClient.constructor" - id: initialize title: initialize - $ref: '@supabase/auth-js.GoTrueClient.initialize' - description: |- - Initializes the client session either from the url or from storage. - This method is automatically called when instantiating the client, but should also be called - manually when checking for an error from an auth redirect (oauth, magiclink, password recovery, etc). + $ref: "@supabase/auth-js.GoTrueClient.initialize" - id: isthrowonerrorenabled title: isThrowOnErrorEnabled - $ref: '@supabase/auth-js.GoTrueClient.isThrowOnErrorEnabled' - description: Returns whether error throwing mode is enabled for this client. + $ref: "@supabase/auth-js.GoTrueClient.isThrowOnErrorEnabled" - id: approveauthorization title: approveAuthorization - $ref: '@supabase/auth-js.AuthOAuthServerApi.approveAuthorization' - description: |- - Approves an OAuth authorization request. - Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. + $ref: "@supabase/auth-js.AuthOAuthServerApi.approveAuthorization" - id: denyauthorization title: denyAuthorization - $ref: '@supabase/auth-js.AuthOAuthServerApi.denyAuthorization' - description: |- - Denies an OAuth authorization request. - Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. + $ref: "@supabase/auth-js.AuthOAuthServerApi.denyAuthorization" - id: getauthorizationdetails title: getAuthorizationDetails - $ref: '@supabase/auth-js.AuthOAuthServerApi.getAuthorizationDetails' - description: |- - Retrieves details about an OAuth authorization request. - Used to display consent information to the user. - Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - - This method returns authorization details including client info, scopes, and user information. - If the response includes a redirect_uri, it means consent was already given - the caller - should handle the redirect manually if needed. + $ref: "@supabase/auth-js.AuthOAuthServerApi.getAuthorizationDetails" - id: createclient title: createClient - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.createClient' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.createClient" + description: >- Creates a new OAuth client. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: deleteclient title: deleteClient - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.deleteClient' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.deleteClient" + description: >- Deletes an OAuth client. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: getclient title: getClient - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.getClient' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.getClient" + description: >- Gets details of a specific OAuth client. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: listclients title: listClients - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.listClients' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.listClients" + description: >- Lists all OAuth clients with optional pagination. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: regenerateclientsecret title: regenerateClientSecret - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.regenerateClientSecret' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.regenerateClientSecret" + description: >- Regenerates the secret for an OAuth client. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: updateclient title: updateClient - $ref: '@supabase/auth-js.GoTrueAdminOAuthApi.updateClient' - description: |- + $ref: "@supabase/auth-js.GoTrueAdminOAuthApi.updateClient" + description: >- Updates an existing OAuth client. + Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. - This function should only be called on a server. Never expose your key in the browser. + + This function should only be called on a server. Never expose your key in + the browser. - id: listfactors title: listFactors - $ref: '@supabase/auth-js.GoTrueMFAApi.listFactors' - description: Returns the list of MFA factors enabled for this user. + $ref: "@supabase/auth-js.GoTrueMFAApi.listFactors" examples: - id: example-1 name: List all MFA factors @@ -9047,12 +9670,11 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/postgrest-js.PostgrestBuilder.constructor' + $ref: "@supabase/postgrest-js.PostgrestBuilder.constructor" description: Create a query builder instance - id: returns title: returns - $ref: '@supabase/postgrest-js.PostgrestBuilder.returns' - description: Override the type of the returned . + $ref: "@supabase/postgrest-js.PostgrestBuilder.returns" notes: | - Deprecated: use overrideTypes method instead examples: @@ -9067,40 +9689,29 @@ functions: ``` - id: setheader title: setHeader - $ref: '@supabase/postgrest-js.PostgrestBuilder.setHeader' - description: Set an HTTP header for the request. + $ref: "@supabase/postgrest-js.PostgrestBuilder.setHeader" - id: then title: then - $ref: '@supabase/postgrest-js.PostgrestBuilder.then' - description: Attaches callbacks for the resolution and/or rejection of the Promise. + $ref: "@supabase/postgrest-js.PostgrestBuilder.then" - id: throwonerror title: throwOnError - $ref: '@supabase/postgrest-js.PostgrestBuilder.throwOnError' - description: |- - If there's an error with the query, throwOnError will reject the promise by - throwing the error instead of returning it as part of a successful response. + $ref: "@supabase/postgrest-js.PostgrestBuilder.throwOnError" - id: constructor title: constructor - $ref: '@supabase/postgrest-js.PostgrestClient.constructor' - description: Creates a PostgREST client. + $ref: "@supabase/postgrest-js.PostgrestClient.constructor" - id: from title: from - $ref: '@supabase/postgrest-js.PostgrestClient.from' - description: Perform a query on a table or a view. + $ref: "@supabase/postgrest-js.PostgrestClient.from" - id: schema title: schema - $ref: '@supabase/postgrest-js.PostgrestClient.schema' - description: |- - Select a schema to query or perform an function (rpc) call. - - The schema needs to be on the list of exposed schemas inside Supabase. + $ref: "@supabase/postgrest-js.PostgrestClient.schema" - id: constructor title: constructor - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.constructor' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.constructor" description: Create a query builder instance - id: ilikeallof title: ilikeAllOf - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.ilikeAllOf' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.ilikeAllOf" description: Match only rows where matches all of case-insensitively. examples: - id: example-1 @@ -9114,7 +9725,7 @@ functions: ``` - id: ilikeanyof title: ilikeAnyOf - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.ilikeAnyOf' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.ilikeAnyOf" description: Match only rows where matches any of case-insensitively. examples: - id: example-1 @@ -9128,7 +9739,7 @@ functions: ``` - id: likeallof title: likeAllOf - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.likeAllOf' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.likeAllOf" description: Match only rows where matches all of case-sensitively. examples: - id: example-1 @@ -9142,7 +9753,7 @@ functions: ``` - id: likeanyof title: likeAnyOf - $ref: '@supabase/postgrest-js.PostgrestFilterBuilder.likeAnyOf' + $ref: "@supabase/postgrest-js.PostgrestFilterBuilder.likeAnyOf" description: Match only rows where matches any of case-sensitively. examples: - id: example-1 @@ -9156,15 +9767,15 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/postgrest-js.PostgrestQueryBuilder.constructor' + $ref: "@supabase/postgrest-js.PostgrestQueryBuilder.constructor" description: Create a query builder instance - id: constructor title: constructor - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.constructor' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.constructor" description: Create a query builder instance - id: geojson title: geojson - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.geojson' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.geojson" description: Return as an object in [GeoJSON](https://geojson.org) format. examples: - id: example-1 @@ -9178,10 +9789,7 @@ functions: ``` - id: maxaffected title: maxAffected - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.maxAffected' - description: |- - Set the maximum number of rows that can be affected by the query. - Only available in PostgREST v13+ and only works with PATCH and DELETE methods. + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.maxAffected" examples: - id: example-1 name: Limit affected rows in update @@ -9195,7 +9803,7 @@ functions: ``` - id: rollback title: rollback - $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.rollback' + $ref: "@supabase/postgrest-js.PostgrestTransformBuilder.rollback" description: |- Rollback the query. @@ -9213,68 +9821,64 @@ functions: ``` - id: constructor title: constructor - $ref: '@supabase/realtime-js.RealtimePresence.constructor' - description: Initializes the Presence. + $ref: "@supabase/realtime-js.RealtimePresence.constructor" - id: constructor title: constructor - $ref: '@supabase/realtime-js.WebSocketFactory.constructor' + $ref: "@supabase/realtime-js.WebSocketFactory.constructor" description: Create a WebSocketFactory instance - id: createwebsocket title: createWebSocket - $ref: '@supabase/realtime-js.WebSocketFactory.createWebSocket' + $ref: "@supabase/realtime-js.WebSocketFactory.createWebSocket" description: Create WebSocket connection - id: getwebsocketconstructor title: getWebSocketConstructor - $ref: '@supabase/realtime-js.WebSocketFactory.getWebSocketConstructor' + $ref: "@supabase/realtime-js.WebSocketFactory.getWebSocketConstructor" description: Get WebSocket constructor function - id: iswebsocketsupported title: isWebSocketSupported - $ref: '@supabase/realtime-js.WebSocketFactory.isWebSocketSupported' + $ref: "@supabase/realtime-js.WebSocketFactory.isWebSocketSupported" description: Check if WebSocket is supported - id: addeventlistener title: addEventListener - $ref: '@supabase/realtime-js.WebSocketLike.addEventListener' + $ref: "@supabase/realtime-js.WebSocketLike.addEventListener" description: Add WebSocket event listener - id: close title: close - $ref: '@supabase/realtime-js.WebSocketLike.close' + $ref: "@supabase/realtime-js.WebSocketLike.close" description: Close WebSocket connection - id: removeeventlistener title: removeEventListener - $ref: '@supabase/realtime-js.WebSocketLike.removeEventListener' + $ref: "@supabase/realtime-js.WebSocketLike.removeEventListener" description: Remove WebSocket event listener - id: send title: send - $ref: '@supabase/realtime-js.WebSocketLike.send' + $ref: "@supabase/realtime-js.WebSocketLike.send" description: Send message through WebSocket - id: constructor title: constructor - $ref: '@supabase/realtime-js.WebSocketLikeConstructor.constructor' + $ref: "@supabase/realtime-js.WebSocketLikeConstructor.constructor" description: Create a WebSocketLikeConstructor instance - id: constructor title: constructor - $ref: '@supabase/storage-js.index.StorageClient.constructor' + $ref: "@supabase/storage-js.index.StorageClient.constructor" description: Create a Storage client instance - id: from title: from - $ref: '@supabase/storage-js.index.StorageClient.from' - description: Perform file operation in a bucket. + $ref: "@supabase/storage-js.index.StorageClient.from" - id: constructor title: constructor - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.constructor' + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.constructor" description: Create a StorageBucketApi instance - id: throwonerror title: throwOnError - $ref: '@supabase/storage-js.packages/StorageBucketApi.default.throwOnError' - description: Enable throwing errors instead of returning them. + $ref: "@supabase/storage-js.packages/StorageBucketApi.default.throwOnError" - id: constructor title: constructor - $ref: '@supabase/storage-js.packages/StorageFileApi.default.constructor' + $ref: "@supabase/storage-js.packages/StorageFileApi.default.constructor" description: Create a StorageFileApi instance - id: exists title: exists - $ref: '@supabase/storage-js.packages/StorageFileApi.default.exists' - description: Checks the existence of a file. + $ref: "@supabase/storage-js.packages/StorageFileApi.default.exists" examples: - id: example-1 name: Check if file exists @@ -9291,8 +9895,7 @@ functions: ``` - id: info title: info - $ref: '@supabase/storage-js.packages/StorageFileApi.default.info' - description: Retrieves the details of an existing file. + $ref: "@supabase/storage-js.packages/StorageFileApi.default.info" examples: - id: example-1 name: Get file metadata @@ -9310,9 +9913,7 @@ functions: ``` - id: listv2 title: listV2 - $ref: '@supabase/storage-js.packages/StorageFileApi.default.listV2' - description: this method signature might change in the future + $ref: "@supabase/storage-js.packages/StorageFileApi.default.listV2" - id: throwonerror title: throwOnError - $ref: '@supabase/storage-js.packages/StorageFileApi.default.throwOnError' - description: Enable throwing errors instead of returning them. + $ref: "@supabase/storage-js.packages/StorageFileApi.default.throwOnError"