Merge pull request #8585 from supabase/update-storage-docs-3

apps/reference/_supabase_js/generated/storage-createbucket.mdx

@@ -75,7 +75,7 @@ No description provided.
   </h4>
   <div class="method-list-item-description">
 
-The visibility of the bucket. By default, buckets are not public.
+The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private.
 
   </div>
   
@@ -89,9 +89,10 @@ The visibility of the bucket. By default, buckets are not public.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `insert`
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: `insert`
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-deletebucket.mdx

@@ -43,9 +43,10 @@ The unique identifier of the bucket you would like to delete.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `select` and `delete`
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: `select` and `delete`
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-emptybucket.mdx

@@ -42,9 +42,10 @@ The unique identifier of the bucket you would like to empty.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `select`
-  - `objects` permissions: `select` and `delete`
+- RLS policy permissions required:
+  - `buckets` table permissions: `select`
+  - `objects` table permissions: `select` and `delete`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-copy.mdx

@@ -8,7 +8,7 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Copies an existing file.
+Copies an existing file to a new path in the same bucket.
 
 ```js
 const { data, error } = await supabase.storage
@@ -64,9 +64,10 @@ The new file path, including the new file name. For example `folder/image-copy.p
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `update` and `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `insert` and `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-createsignedurl.mdx

@@ -8,7 +8,7 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Create signed URL to download file without requiring permissions. This URL can be valid for a set number of seconds.
+Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.
 
 ```js
 const { data, error } = await supabase.storage
@@ -34,7 +34,7 @@ const { data, error } = await supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-The file path to be downloaded, including the current file name. For example `folder/image.png`.
+The file path, including the current file name. For example `folder/image.png`.
 
   </div>
   
@@ -64,9 +64,10 @@ The number of seconds until the signed URL expires. For example, `60` for a URL
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-createsignedurls.mdx

@@ -8,7 +8,7 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Create signed URLs to download files without requiring permissions. These URLs can be valid for a set number of seconds.
+Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time.
 
 ```js
 const { data, error } = await supabase.storage
@@ -64,9 +64,10 @@ The number of seconds until the signed URLs expire. For example, `60` for URLs w
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-download.mdx

@@ -34,7 +34,7 @@ const { data, error } = await supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-The file path to be downloaded, including the path and file name. For example `folder/image.png`.
+The full path and file name of the file to be downloaded. For example `folder/image.png`.
 
   </div>
   
@@ -44,9 +44,10 @@ The file path to be downloaded, including the path and file name. For example `f
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-getpublicurl.mdx

@@ -8,10 +8,11 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Retrieve URLs for assets in public buckets and encapsulates it in a return object
+Retrieves the URL for an asset in a public bucket.
+This function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset.
 
 ```js
-const { data, error } = supabase.storage
+const { data } = supabase.storage
   .from('public-bucket')
   .getPublicUrl('folder/avatar1.png')
 ```
@@ -34,7 +35,7 @@ const { data, error } = supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-The file path to be downloaded, including the path and file name. For example `folder/image.png`.
+The path and name of the file to generate the public URL for. For example `folder/image.png`.
 
   </div>
   
@@ -45,16 +46,17 @@ The file path to be downloaded, including the path and file name. For example `f
 ## Notes
 
 - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public"
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 
 ### Returns the URL for an asset in a public bucket
 
 ```js
-const { data, error } = supabase.storage
+const { data } = supabase.storage
   .from('public-bucket')
   .getPublicUrl('folder/avatar1.png')
 ```

apps/reference/_supabase_js/generated/storage-from-list.mdx

@@ -196,9 +196,10 @@ Pass in an AbortController's signal to cancel the request.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-move.mdx

@@ -8,7 +8,7 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Moves an existing file.
+Moves an existing file to a new path in the same bucket.
 
 ```js
 const { data, error } = await supabase.storage
@@ -64,9 +64,10 @@ The new file path, including the new file name. For example `folder/image-new.pn
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `update` and `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `update` and `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-remove.mdx

@@ -34,7 +34,7 @@ const { data, error } = await supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-An array of files to be deleted, including the path and file name. For example [`folder/image.png`].
+An array of files to delete, including the path and file name. For example [`'folder/image.png'`].
 
   </div>
   
@@ -44,9 +44,10 @@ An array of files to be deleted, including the path and file name. For example [
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `delete` and `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `delete` and `select`
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-from-update.mdx

@@ -38,7 +38,7 @@ const { data, error } = await supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
+The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update.
 
   </div>
   
@@ -304,7 +304,7 @@ No description provided.
   </h4>
   <div class="method-list-item-description">
 
-the `Cache-Control: max-age=<seconds>` seconds value.
+The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds.
 
   </div>
   
@@ -344,7 +344,7 @@ the `Content-Type` header value. Should be specified if using a `fileBody` that
   </h4>
   <div class="method-list-item-description">
 
-whether to perform an upsert
+When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false.
 
   </div>
   
@@ -358,9 +358,10 @@ whether to perform an upsert
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `update` and `select`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `update` and `select`
+- Refer to the [Storage guide](/docs/guides/storage#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

apps/reference/_supabase_js/generated/storage-from-upload.mdx

@@ -38,7 +38,7 @@ const { data, error } = await supabase.storage
   </h4>
   <div class="method-list-item-description">
 
-The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
+The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
 
   </div>
   
@@ -304,7 +304,7 @@ No description provided.
   </h4>
   <div class="method-list-item-description">
 
-the `Cache-Control: max-age=<seconds>` seconds value.
+The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds.
 
   </div>
   
@@ -344,7 +344,7 @@ the `Content-Type` header value. Should be specified if using a `fileBody` that
   </h4>
   <div class="method-list-item-description">
 
-whether to perform an upsert
+When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false.
 
   </div>
   
@@ -358,9 +358,10 @@ whether to perform an upsert
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: none
-  - `objects` permissions: `insert`
+- RLS policy permissions required:
+  - `buckets` table permissions: none
+  - `objects` table permissions: `insert`
+- Refer to the [Storage guide](/docs/guides/storage#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

apps/reference/_supabase_js/generated/storage-getbucket.mdx

@@ -42,9 +42,10 @@ The unique identifier of the bucket you would like to retrieve.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `select`
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: `select`
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-listbuckets.mdx

@@ -16,9 +16,10 @@ const { data, error } = await supabase.storage.listBuckets()
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `select`
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: `select`
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js/generated/storage-updatebucket.mdx

@@ -8,7 +8,7 @@ custom_edit_url: https://github.com/supabase/supabase/edit/master/spec/supabase_
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Updates a new Storage bucket
+Updates a Storage bucket
 
 ```js
 const { data, error } = await supabase.storage.updateBucket('avatars', {
@@ -75,7 +75,7 @@ No description provided.
   </h4>
   <div class="method-list-item-description">
 
-The visibility of the bucket.
+The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.
 
   </div>
   
@@ -89,9 +89,10 @@ The visibility of the bucket.
 
 ## Notes
 
-- Policy permissions required:
-  - `buckets` permissions: `update`
-  - `objects` permissions: none
+- RLS policy permissions required:
+  - `buckets` table permissions: `update`
+  - `objects` table permissions: none
+- Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
 
 ## Examples
 

apps/reference/_supabase_js_versioned_docs/version-v1/storage-from-copy.mdx

@@ -66,7 +66,7 @@ The new file path, including the new file name. For example `folder/image-copy.p
 
 - Policy permissions required:
   - `buckets` permissions: none
-  - `objects` permissions: `update` and `select`
+  - `objects` permissions: `insert` and `select`
 
 ## Examples
 

apps/reference/docs/guides/storage.mdx

@@ -268,9 +268,44 @@ create policy "Public Access"
 </TabItem>
 </Tabs>
 
+## Accessing objects
+
+For private buckets, you can access objects via the [download](/docs/reference/javascript/storage-from-download) method. This corresponds to `/object/auth/` API endpoint.
+Alternatively, you can create a publicly shareable URL with an expiry date using the [createSignedUrl](/docs/reference/javascript/storage-from-createsignedurl) method
+which calls the `/object/sign/` API.
+
+For public buckets, you can access the assets directly without a token or an Authorisation header. The [getPublicUrl](/docs/reference/javascript/storage-from-getpublicurl)
+helper method returns the full public URL for an asset. This calls the `/object/public/` API endpoint internally.
+
+<details>
+<summary>Advanced: reverse proxy</summary>
+The URLs returned are proxied through the API Proxy. They are prefixed by <code>/storage/v1</code>.
+
+For example, on the hosted Platform they will be
+
+<code>https://[project_ref].supabase.co/storage/v1/object/public/[id]</code>
+
+You can access the storage API directly with the same endpoint. See the <a href="https://supabase.github.io/storage-api">API docs</a> for a full list of operations available.
+
+</details>
+
+---
+
+## Access Control
+
+Supabase Storage is integrated with your [Postgres Database](/docs/guides/database).
+This means that you can use the same [Row Level Security Policies](/docs/guides/auth#policies)
+for managing access to your files. Supabase Storage stores metadata in the `objects` and `buckets` table in the storage schema. To allow read access to files, the RLS policy must allow users to `SELECT` the `objects` table and for uploading a new object, the RLS policy must grant users access to `INSERT` into the `objects` table and so on. The mapping between the different API calls and the database permissions required is documented in the [Reference docs](/docs/reference/javascript/next/storage-createbucket).
+
+:::note
+
+Access control for Storage is mapped to CRUD operations on the `buckets` and `objects` table via RLS policies.
+
+:::
+
 ## Helpers
 
-Supabase Storage is configured with database SQL helper functions which you can use in your database queries and
+Supabase Storage provides SQL helper functions which you can use in your database queries and
 policies.
 
 ---
@@ -320,39 +355,9 @@ For example, if your file is stored in `public/subfolder/avatar.png` it would re
 
 ---
 
-## Accessing objects
-
-For private buckets, you can access objects via the [download](/docs/reference/javascript/storage-from-download) method. This corresponds to `/object/auth/` API endpoint.
-Alternatively, you can create a publicly shareable URL with an expiry date using the [createSignedUrl](/docs/reference/javascript/storage-from-createsignedurl) method
-which calls the `/object/sign/` API.
-
-For public buckets, you can access the assets directly without a token or an Authorisation header. The [getPublicUrl](/docs/reference/javascript/storage-from-getpublicurl)
-helper method returns the full public URL for an asset. This calls the `/object/public/` API endpoint internally.
-
-<details> 
-<summary>Advanced: reverse proxy</summary>
-The URLs returned are proxied through the API Proxy. They are prefixed by <code>/storage/v1</code>.
-
-For example, on the hosted Platform they will be
-
-<code>https://[project_ref].supabase.co/storage/v1/object/public/[id]</code>
-
-You can access the storage API directly with the same endpoint. See the <a href="https://supabase.github.io/storage-api">API docs</a> for a full list of operations available.
-
-</details>
-
----
-
-## Security
-
-Supabase Storage is integrated with your [Postgres Database](/docs/guides/database).
-This means that you can use the same [Policy](/docs/guides/auth#policies) engine
-for managing access to your files.
-
 ## Policy Examples
 
-Here are some examples to show you the power of PostgreSQL's Row Level Security. Each policy is attached to a table, and the policy is executed
-every time a table is accessed.
+Here are some examples of storage policies.
 
 ### Allow public access to a bucket
 

spec/WIP_supabase_js_v2_sdk.yaml

@@ -41,7 +41,7 @@ functions:
           ```js
           import { createClient } from '@supabase/supabase-js'
 
-          // Create a single supabase client for interacting with your database 
+          // Create a single supabase client for interacting with your database
           const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')
           ```
       - id: example-init-with-params
@@ -62,7 +62,7 @@ functions:
       - id: example-init-scheams
         summary: API schemas
         description: |
-          By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard. 
+          By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard.
           Go to `Settings > API > Schema` 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.
@@ -71,22 +71,22 @@ functions:
           import { createClient } from '@supabase/supabase-js'
 
           // Provide a custom schema. Defaults to "public".
-          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', { 
-            schema: 'other_schema' 
+          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
+            schema: 'other_schema'
           })
           ```
       - id: example-init-fetch
         summary: Custom `fetch` implementation
         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. 
+          `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).
         code: |
           ```js
           import { createClient } from '@supabase/supabase-js'
 
-          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', { 
-            fetch: fetch.bind(globalThis) 
+          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
+            fetch: fetch.bind(globalThis)
           })
           ```
 
@@ -128,8 +128,8 @@ functions:
               password: 'example-password',
             },
             {
-              data: { 
-                first_name: 'John', 
+              data: {
+                first_name: 'John',
                 age: 27,
               }
             }
@@ -203,10 +203,10 @@ functions:
       - id: example-signin-redirect
         summary: Sign in with redirect.
         description: |
-          Note that the `redirectTo` param is only relevant for OAuth logins, where the login flow is managed by 
+          Note that the `redirectTo` param is only relevant for OAuth logins, where the login flow is managed by
           the Auth server. If you are using email/phone logins you should set up your own redirects (within the email/sms template).
-           
-          Sometimes you want to control where the user is redirected to after they are logged in. Supabase supports this for 
+
+          Sometimes you want to control where the user is redirected to after they are logged in. Supabase supports this for
           any URL path on your website (the URL must either be on the same domain as your Site URL [see Auth>Settings in dashboard], or must match one of the Additional Redirect URLs [also in Auth>Settings]).
         code: |
           ```js
@@ -294,7 +294,7 @@ functions:
       To toggle this behavior off and only send a single confirmation link to the new email, toggle "Double confirm email changes" under "Authentication" -> "Settings" off.
 
 
-      User metadata: It's generally better to store user data in a table inside your public schema (i.e. `public.users`). 
+      User metadata: It's generally better to store user data in a table inside your public schema (i.e. `public.users`).
       Use the `update()` method if you have data which rarely changes or is specific only to the logged in user.
     examples:
       - id: example-auth-update-email
@@ -314,8 +314,8 @@ functions:
         summary: Update a user's metadata.
         code: |
           ```js
-          const { user, error } = await supabase.auth.update({ 
-            data: { hello: 'world' } 
+          const { user, error } = await supabase.auth.update({
+            data: { hello: 'world' }
           })
           ```
 
@@ -330,9 +330,9 @@ functions:
           ```js
           function apiFunction(req, res) {
             // Assuming the access token was sent as a header "X-Supabase-Auth"
-            const { access_token } = req.get('X-Supabase-Auth') 
+            const { access_token } = req.get('X-Supabase-Auth')
 
-            // You can now use it within a Supabase Client 
+            // You can now use it within a Supabase Client
             const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key")
             const { user, error } = supabase.auth.setAuth(access_token)
 
@@ -367,9 +367,9 @@ functions:
           * Use the Auth token in your server-side function.
           */
           async function apiFunction(req, res) {
-            const { access_token } = req.get('X-Supabase-Auth') 
+            const { access_token } = req.get('X-Supabase-Auth')
 
-            // You can now use it within a Supabase Client 
+            // You can now use it within a Supabase Client
             const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key")
             const { user, error } = supabase.auth.setAuth(access_token)
 
@@ -1410,7 +1410,7 @@ functions:
     description: |
       - Policy permissions required:
         - `buckets` permissions: none
-        - `objects` permissions: `update` and `select`
+        - `objects` permissions: `insert` and `select`
     examples:
       - id: example-storage-file-copy
         summary: Copy file

spec/enrichments/tsdoc_v2/combined.json

@@ -92461,7 +92461,7 @@
                                   "kindString": "Property",
                                   "flags": {},
                                   "comment": {
-                                    "shortText": "The visibility of the bucket. By default, buckets are not public."
+                                    "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
                                   },
                                   "sources": [
                                     {
@@ -93501,7 +93501,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Updates a new Storage bucket"
+                        "shortText": "Updates a Storage bucket"
                       },
                       "parameters": [
                         {
@@ -93540,7 +93540,7 @@
                                   "kindString": "Property",
                                   "flags": {},
                                   "comment": {
-                                    "shortText": "The visibility of the bucket.\n"
+                                    "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
                                   },
                                   "sources": [
                                     {
@@ -94409,7 +94409,7 @@
                     "isOptional": true
                   },
                   "comment": {
-                    "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                    "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
                   },
                   "sources": [
                     {
@@ -94455,7 +94455,7 @@
                     "isOptional": true
                   },
                   "comment": {
-                    "shortText": "whether to perform an upsert"
+                    "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
                   },
                   "sources": [
                     {
@@ -95035,7 +95035,7 @@
                                   "kindString": "Property",
                                   "flags": {},
                                   "comment": {
-                                    "shortText": "The visibility of the bucket. By default, buckets are not public."
+                                    "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
                                   },
                                   "sources": [
                                     {
@@ -95978,7 +95978,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Updates a new Storage bucket"
+                        "shortText": "Updates a Storage bucket"
                       },
                       "parameters": [
                         {
@@ -96017,7 +96017,7 @@
                                   "kindString": "Property",
                                   "flags": {},
                                   "comment": {
-                                    "shortText": "The visibility of the bucket.\n"
+                                    "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
                                   },
                                   "sources": [
                                     {
@@ -96470,7 +96470,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Copies an existing file."
+                        "shortText": "Copies an existing file to a new path in the same bucket."
                       },
                       "parameters": [
                         {
@@ -96691,7 +96691,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Create signed URL to download file without requiring permissions. This URL can be valid for a set number of seconds."
+                        "shortText": "Creates a signed URL. Use a signed URL to share a file for a fixed amount of time."
                       },
                       "parameters": [
                         {
@@ -96701,7 +96701,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "The file path to be downloaded, including the current file name. For example `folder/image.png`."
+                            "shortText": "The file path, including the current file name. For example `folder/image.png`."
                           },
                           "type": {
                             "type": "intrinsic",
@@ -96912,7 +96912,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Create signed URLs to download files without requiring permissions. These URLs can be valid for a set number of seconds."
+                        "shortText": "Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time."
                       },
                       "parameters": [
                         {
@@ -97205,7 +97205,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+                            "shortText": "The full path and file name of the file to be downloaded. For example `folder/image.png`.\n"
                           },
                           "type": {
                             "type": "intrinsic",
@@ -97357,7 +97357,7 @@
                   "sources": [
                     {
                       "fileName": "src/packages/StorageFileApi.ts",
-                      "line": 376,
+                      "line": 377,
                       "character": 2
                     }
                   ],
@@ -97369,7 +97369,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Retrieve URLs for assets in public buckets and encapsulates it in a return object"
+                        "shortText": "Retrieves the URL for an asset in a public bucket.\nThis function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset."
                       },
                       "parameters": [
                         {
@@ -97379,7 +97379,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+                            "shortText": "The path and name of the file to generate the public URL for. For example `folder/image.png`.\n"
                           },
                           "type": {
                             "type": "intrinsic",
@@ -97405,7 +97405,7 @@
                               "sources": [
                                 {
                                   "fileName": "src/packages/StorageFileApi.ts",
-                                  "line": 376,
+                                  "line": 377,
                                   "character": 32
                                 }
                               ],
@@ -97427,7 +97427,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 376,
+                                          "line": 377,
                                           "character": 40
                                         }
                                       ],
@@ -97473,7 +97473,7 @@
                   "sources": [
                     {
                       "fileName": "src/packages/StorageFileApi.ts",
-                      "line": 482,
+                      "line": 483,
                       "character": 8
                     }
                   ],
@@ -97728,7 +97728,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 488,
+                                          "line": 489,
                                           "character": 8
                                         }
                                       ],
@@ -97750,7 +97750,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 489,
+                                          "line": 490,
                                           "character": 8
                                         }
                                       ],
@@ -97790,7 +97790,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 492,
+                                          "line": 493,
                                           "character": 8
                                         }
                                       ],
@@ -97808,7 +97808,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 493,
+                                          "line": 494,
                                           "character": 8
                                         }
                                       ],
@@ -97862,7 +97862,7 @@
                       "kindString": "Call signature",
                       "flags": {},
                       "comment": {
-                        "shortText": "Moves an existing file."
+                        "shortText": "Moves an existing file to a new path in the same bucket."
                       },
                       "parameters": [
                         {
@@ -98071,7 +98071,7 @@
                   "sources": [
                     {
                       "fileName": "src/packages/StorageFileApi.ts",
-                      "line": 386,
+                      "line": 387,
                       "character": 8
                     }
                   ],
@@ -98093,7 +98093,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "An array of files to be deleted, including the path and file name. For example [`folder/image.png`].\n"
+                            "shortText": "An array of files to delete, including the path and file name. For example [`'folder/image.png'`].\n"
                           },
                           "type": {
                             "type": "array",
@@ -98128,7 +98128,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 390,
+                                          "line": 391,
                                           "character": 8
                                         }
                                       ],
@@ -98150,7 +98150,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 391,
+                                          "line": 392,
                                           "character": 8
                                         }
                                       ],
@@ -98190,7 +98190,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 394,
+                                          "line": 395,
                                           "character": 8
                                         }
                                       ],
@@ -98208,7 +98208,7 @@
                                       "sources": [
                                         {
                                           "fileName": "src/packages/StorageFileApi.ts",
-                                          "line": 395,
+                                          "line": 396,
                                           "character": 8
                                         }
                                       ],
@@ -98272,7 +98272,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+                            "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update."
                           },
                           "type": {
                             "type": "intrinsic",
@@ -98388,7 +98388,7 @@
                                     "isOptional": true
                                   },
                                   "comment": {
-                                    "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                                    "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
                                   },
                                   "sources": [
                                     {
@@ -98434,7 +98434,7 @@
                                     "isOptional": true
                                   },
                                   "comment": {
-                                    "shortText": "whether to perform an upsert"
+                                    "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
                                   },
                                   "sources": [
                                     {
@@ -98670,7 +98670,7 @@
                           "kindString": "Parameter",
                           "flags": {},
                           "comment": {
-                            "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+                            "shortText": "The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
                           },
                           "type": {
                             "type": "intrinsic",
@@ -98786,7 +98786,7 @@
                                     "isOptional": true
                                   },
                                   "comment": {
-                                    "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                                    "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
                                   },
                                   "sources": [
                                     {
@@ -98832,7 +98832,7 @@
                                     "isOptional": true
                                   },
                                   "comment": {
-                                    "shortText": "whether to perform an upsert"
+                                    "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
                                   },
                                   "sources": [
                                     {

spec/enrichments/tsdoc_v2/storage.json

@@ -473,7 +473,7 @@
 															"kindString": "Property",
 															"flags": {},
 															"comment": {
-																"shortText": "The visibility of the bucket. By default, buckets are not public."
+																"shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
 															},
 															"sources": [
 																{
@@ -1513,7 +1513,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Updates a new Storage bucket"
+										"shortText": "Updates a Storage bucket"
 									},
 									"parameters": [
 										{
@@ -1552,7 +1552,7 @@
 															"kindString": "Property",
 															"flags": {},
 															"comment": {
-																"shortText": "The visibility of the bucket.\n"
+																"shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
 															},
 															"sources": [
 																{
@@ -2421,7 +2421,7 @@
 								"isOptional": true
 							},
 							"comment": {
-								"shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+								"shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
 							},
 							"sources": [
 								{
@@ -2467,7 +2467,7 @@
 								"isOptional": true
 							},
 							"comment": {
-								"shortText": "whether to perform an upsert"
+								"shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
 							},
 							"sources": [
 								{
@@ -3047,7 +3047,7 @@
 															"kindString": "Property",
 															"flags": {},
 															"comment": {
-																"shortText": "The visibility of the bucket. By default, buckets are not public."
+																"shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
 															},
 															"sources": [
 																{
@@ -3990,7 +3990,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Updates a new Storage bucket"
+										"shortText": "Updates a Storage bucket"
 									},
 									"parameters": [
 										{
@@ -4029,7 +4029,7 @@
 															"kindString": "Property",
 															"flags": {},
 															"comment": {
-																"shortText": "The visibility of the bucket.\n"
+																"shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
 															},
 															"sources": [
 																{
@@ -4482,7 +4482,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Copies an existing file."
+										"shortText": "Copies an existing file to a new path in the same bucket."
 									},
 									"parameters": [
 										{
@@ -4703,7 +4703,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Create signed URL to download file without requiring permissions. This URL can be valid for a set number of seconds."
+										"shortText": "Creates a signed URL. Use a signed URL to share a file for a fixed amount of time."
 									},
 									"parameters": [
 										{
@@ -4713,7 +4713,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "The file path to be downloaded, including the current file name. For example `folder/image.png`."
+												"shortText": "The file path, including the current file name. For example `folder/image.png`."
 											},
 											"type": {
 												"type": "intrinsic",
@@ -4924,7 +4924,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Create signed URLs to download files without requiring permissions. These URLs can be valid for a set number of seconds."
+										"shortText": "Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time."
 									},
 									"parameters": [
 										{
@@ -5217,7 +5217,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+												"shortText": "The full path and file name of the file to be downloaded. For example `folder/image.png`.\n"
 											},
 											"type": {
 												"type": "intrinsic",
@@ -5369,7 +5369,7 @@
 							"sources": [
 								{
 									"fileName": "src/packages/StorageFileApi.ts",
-									"line": 376,
+									"line": 377,
 									"character": 2
 								}
 							],
@@ -5381,7 +5381,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Retrieve URLs for assets in public buckets and encapsulates it in a return object"
+										"shortText": "Retrieves the URL for an asset in a public bucket.\nThis function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset."
 									},
 									"parameters": [
 										{
@@ -5391,7 +5391,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+												"shortText": "The path and name of the file to generate the public URL for. For example `folder/image.png`.\n"
 											},
 											"type": {
 												"type": "intrinsic",
@@ -5417,7 +5417,7 @@
 													"sources": [
 														{
 															"fileName": "src/packages/StorageFileApi.ts",
-															"line": 376,
+															"line": 377,
 															"character": 32
 														}
 													],
@@ -5439,7 +5439,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 376,
+																			"line": 377,
 																			"character": 40
 																		}
 																	],
@@ -5485,7 +5485,7 @@
 							"sources": [
 								{
 									"fileName": "src/packages/StorageFileApi.ts",
-									"line": 482,
+									"line": 483,
 									"character": 8
 								}
 							],
@@ -5569,7 +5569,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 488,
+																			"line": 489,
 																			"character": 8
 																		}
 																	],
@@ -5591,7 +5591,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 489,
+																			"line": 490,
 																			"character": 8
 																		}
 																	],
@@ -5631,7 +5631,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 492,
+																			"line": 493,
 																			"character": 8
 																		}
 																	],
@@ -5649,7 +5649,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 493,
+																			"line": 494,
 																			"character": 8
 																		}
 																	],
@@ -5703,7 +5703,7 @@
 									"kindString": "Call signature",
 									"flags": {},
 									"comment": {
-										"shortText": "Moves an existing file."
+										"shortText": "Moves an existing file to a new path in the same bucket."
 									},
 									"parameters": [
 										{
@@ -5912,7 +5912,7 @@
 							"sources": [
 								{
 									"fileName": "src/packages/StorageFileApi.ts",
-									"line": 386,
+									"line": 387,
 									"character": 8
 								}
 							],
@@ -5934,7 +5934,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "An array of files to be deleted, including the path and file name. For example [`folder/image.png`].\n"
+												"shortText": "An array of files to delete, including the path and file name. For example [`'folder/image.png'`].\n"
 											},
 											"type": {
 												"type": "array",
@@ -5969,7 +5969,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 390,
+																			"line": 391,
 																			"character": 8
 																		}
 																	],
@@ -5991,7 +5991,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 391,
+																			"line": 392,
 																			"character": 8
 																		}
 																	],
@@ -6031,7 +6031,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 394,
+																			"line": 395,
 																			"character": 8
 																		}
 																	],
@@ -6049,7 +6049,7 @@
 																	"sources": [
 																		{
 																			"fileName": "src/packages/StorageFileApi.ts",
-																			"line": 395,
+																			"line": 396,
 																			"character": 8
 																		}
 																	],
@@ -6113,7 +6113,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+												"shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update."
 											},
 											"type": {
 												"type": "intrinsic",
@@ -6415,7 +6415,7 @@
 											"kindString": "Parameter",
 											"flags": {},
 											"comment": {
-												"shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+												"shortText": "The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
 											},
 											"type": {
 												"type": "intrinsic",

spec/enrichments/tsdoc_v2/storage_dereferenced.json

@@ -473,7 +473,7 @@
                               "kindString": "Property",
                               "flags": {},
                               "comment": {
-                                "shortText": "The visibility of the bucket. By default, buckets are not public."
+                                "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
                               },
                               "sources": [
                                 {
@@ -1513,7 +1513,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Updates a new Storage bucket"
+                    "shortText": "Updates a Storage bucket"
                   },
                   "parameters": [
                     {
@@ -1552,7 +1552,7 @@
                               "kindString": "Property",
                               "flags": {},
                               "comment": {
-                                "shortText": "The visibility of the bucket.\n"
+                                "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
                               },
                               "sources": [
                                 {
@@ -2421,7 +2421,7 @@
                 "isOptional": true
               },
               "comment": {
-                "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
               },
               "sources": [
                 {
@@ -2467,7 +2467,7 @@
                 "isOptional": true
               },
               "comment": {
-                "shortText": "whether to perform an upsert"
+                "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
               },
               "sources": [
                 {
@@ -3047,7 +3047,7 @@
                               "kindString": "Property",
                               "flags": {},
                               "comment": {
-                                "shortText": "The visibility of the bucket. By default, buckets are not public."
+                                "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
                               },
                               "sources": [
                                 {
@@ -3990,7 +3990,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Updates a new Storage bucket"
+                    "shortText": "Updates a Storage bucket"
                   },
                   "parameters": [
                     {
@@ -4029,7 +4029,7 @@
                               "kindString": "Property",
                               "flags": {},
                               "comment": {
-                                "shortText": "The visibility of the bucket.\n"
+                                "shortText": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.\n"
                               },
                               "sources": [
                                 {
@@ -4482,7 +4482,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Copies an existing file."
+                    "shortText": "Copies an existing file to a new path in the same bucket."
                   },
                   "parameters": [
                     {
@@ -4703,7 +4703,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Create signed URL to download file without requiring permissions. This URL can be valid for a set number of seconds."
+                    "shortText": "Creates a signed URL. Use a signed URL to share a file for a fixed amount of time."
                   },
                   "parameters": [
                     {
@@ -4713,7 +4713,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "The file path to be downloaded, including the current file name. For example `folder/image.png`."
+                        "shortText": "The file path, including the current file name. For example `folder/image.png`."
                       },
                       "type": {
                         "type": "intrinsic",
@@ -4924,7 +4924,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Create signed URLs to download files without requiring permissions. These URLs can be valid for a set number of seconds."
+                    "shortText": "Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time."
                   },
                   "parameters": [
                     {
@@ -5217,7 +5217,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+                        "shortText": "The full path and file name of the file to be downloaded. For example `folder/image.png`.\n"
                       },
                       "type": {
                         "type": "intrinsic",
@@ -5369,7 +5369,7 @@
               "sources": [
                 {
                   "fileName": "src/packages/StorageFileApi.ts",
-                  "line": 376,
+                  "line": 377,
                   "character": 2
                 }
               ],
@@ -5381,7 +5381,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Retrieve URLs for assets in public buckets and encapsulates it in a return object"
+                    "shortText": "Retrieves the URL for an asset in a public bucket.\nThis function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset."
                   },
                   "parameters": [
                     {
@@ -5391,7 +5391,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "The file path to be downloaded, including the path and file name. For example `folder/image.png`.\n"
+                        "shortText": "The path and name of the file to generate the public URL for. For example `folder/image.png`.\n"
                       },
                       "type": {
                         "type": "intrinsic",
@@ -5417,7 +5417,7 @@
                           "sources": [
                             {
                               "fileName": "src/packages/StorageFileApi.ts",
-                              "line": 376,
+                              "line": 377,
                               "character": 32
                             }
                           ],
@@ -5439,7 +5439,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 376,
+                                      "line": 377,
                                       "character": 40
                                     }
                                   ],
@@ -5485,7 +5485,7 @@
               "sources": [
                 {
                   "fileName": "src/packages/StorageFileApi.ts",
-                  "line": 482,
+                  "line": 483,
                   "character": 8
                 }
               ],
@@ -5740,7 +5740,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 488,
+                                      "line": 489,
                                       "character": 8
                                     }
                                   ],
@@ -5762,7 +5762,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 489,
+                                      "line": 490,
                                       "character": 8
                                     }
                                   ],
@@ -5802,7 +5802,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 492,
+                                      "line": 493,
                                       "character": 8
                                     }
                                   ],
@@ -5820,7 +5820,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 493,
+                                      "line": 494,
                                       "character": 8
                                     }
                                   ],
@@ -5874,7 +5874,7 @@
                   "kindString": "Call signature",
                   "flags": {},
                   "comment": {
-                    "shortText": "Moves an existing file."
+                    "shortText": "Moves an existing file to a new path in the same bucket."
                   },
                   "parameters": [
                     {
@@ -6083,7 +6083,7 @@
               "sources": [
                 {
                   "fileName": "src/packages/StorageFileApi.ts",
-                  "line": 386,
+                  "line": 387,
                   "character": 8
                 }
               ],
@@ -6105,7 +6105,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "An array of files to be deleted, including the path and file name. For example [`folder/image.png`].\n"
+                        "shortText": "An array of files to delete, including the path and file name. For example [`'folder/image.png'`].\n"
                       },
                       "type": {
                         "type": "array",
@@ -6140,7 +6140,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 390,
+                                      "line": 391,
                                       "character": 8
                                     }
                                   ],
@@ -6162,7 +6162,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 391,
+                                      "line": 392,
                                       "character": 8
                                     }
                                   ],
@@ -6202,7 +6202,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 394,
+                                      "line": 395,
                                       "character": 8
                                     }
                                   ],
@@ -6220,7 +6220,7 @@
                                   "sources": [
                                     {
                                       "fileName": "src/packages/StorageFileApi.ts",
-                                      "line": 395,
+                                      "line": 396,
                                       "character": 8
                                     }
                                   ],
@@ -6284,7 +6284,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+                        "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update."
                       },
                       "type": {
                         "type": "intrinsic",
@@ -6400,7 +6400,7 @@
                                 "isOptional": true
                               },
                               "comment": {
-                                "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                                "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
                               },
                               "sources": [
                                 {
@@ -6446,7 +6446,7 @@
                                 "isOptional": true
                               },
                               "comment": {
-                                "shortText": "whether to perform an upsert"
+                                "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
                               },
                               "sources": [
                                 {
@@ -6682,7 +6682,7 @@
                       "kindString": "Parameter",
                       "flags": {},
                       "comment": {
-                        "shortText": "The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
+                        "shortText": "The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload."
                       },
                       "type": {
                         "type": "intrinsic",
@@ -6798,7 +6798,7 @@
                                 "isOptional": true
                               },
                               "comment": {
-                                "shortText": "the `Cache-Control: max-age=<seconds>` seconds value."
+                                "shortText": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control: max-age=<seconds>` header. Defaults to 3600 seconds."
                               },
                               "sources": [
                                 {
@@ -6844,7 +6844,7 @@
                                 "isOptional": true
                               },
                               "comment": {
-                                "shortText": "whether to perform an upsert"
+                                "shortText": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
                               },
                               "sources": [
                                 {

spec/supabase_js_v1_legacy.yml

@@ -18,7 +18,7 @@ info:
 pages:
   Installing:
     description: |
-      All JavaScript libraries are built directly by the Supabase team. 
+      All JavaScript libraries are built directly by the Supabase team.
 
       Other languages are built by the community and supported by Supabase.
 
@@ -34,7 +34,7 @@ pages:
       yarn add @supabase/supabase-js
       ```
 
-      Find the source code on [GitHub](https://github.com/supabase/supabase-js).  
+      Find the source code on [GitHub](https://github.com/supabase/supabase-js).
 
       Or via CDN
       ```js
@@ -57,7 +57,7 @@ pages:
           ```js
           import { createClient } from '@supabase/supabase-js'
 
-          // Create a single supabase client for interacting with your database 
+          // Create a single supabase client for interacting with your database
           const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')
           ```
       - name: With additional parameters
@@ -80,12 +80,12 @@ pages:
           import { createClient } from '@supabase/supabase-js'
 
           // Provide a custom schema. Defaults to "public".
-          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', { 
-            schema: 'other_schema' 
+          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
+            schema: 'other_schema'
           })
           ```
 
-          By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard. 
+          By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard.
           Go to `Settings > API > Schema` 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.
@@ -94,13 +94,13 @@ pages:
           ```js
           import { createClient } from '@supabase/supabase-js'
 
-          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', { 
-            fetch: fetch.bind(globalThis) 
+          const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
+            fetch: fetch.bind(globalThis)
           })
           ```
 
-          `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. 
+          `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).
 
   Generating Types:
@@ -111,7 +111,7 @@ pages:
 
       `supabase-js` ships with type definitions for usage with TypeScript and for convenient IntelliSense auto-complete and documentation in your editor.
 
-      When using TypeScript, you can pass the type of database row as a type parameter to the `from` method to get better auto-completion support down the chain. 
+      When using TypeScript, you can pass the type of database row as a type parameter to the `from` method to get better auto-completion support down the chain.
       If you don't provide a type for the row you need to explicitly pass `from<any>('tableName')`.
 
       ```ts
@@ -170,8 +170,8 @@ pages:
               password: 'example-password',
             },
             {
-              data: { 
-                first_name: 'John', 
+              data: {
+                first_name: 'John',
                 age: 27,
               }
             }
@@ -244,10 +244,10 @@ pages:
           ```
       - name: Sign in with redirect.
         description: |
-          Note that the `redirectTo` param is only relevant for OAuth logins, where the login flow is managed by 
+          Note that the `redirectTo` param is only relevant for OAuth logins, where the login flow is managed by
           the Auth server. If you are using email/phone logins you should set up your own redirects (within the email/sms template).
-           
-          Sometimes you want to control where the user is redirected to after they are logged in. Supabase supports this for 
+
+          Sometimes you want to control where the user is redirected to after they are logged in. Supabase supports this for
           any URL path on your website (the URL must either be on the same domain as your Site URL [see Auth>Settings in dashboard], or must match one of the Additional Redirect URLs [also in Auth>Settings]).
         js: |
           ```js
@@ -333,7 +333,7 @@ pages:
       To toggle this behavior off and only send a single confirmation link to the new email, toggle "Double confirm email changes" under "Authentication" -> "Settings" off.
 
 
-      User metadata: It's generally better to store user data in a table inside your public schema (i.e. `public.users`). 
+      User metadata: It's generally better to store user data in a table inside your public schema (i.e. `public.users`).
       Use the `update()` method if you have data which rarely changes or is specific only to the logged in user.
     examples:
       - name: Update email for authenticated user.
@@ -353,8 +353,8 @@ pages:
         isSpotlight: true
         js: |
           ```js
-          const { user, error } = await supabase.auth.update({ 
-            data: { hello: 'world' } 
+          const { user, error } = await supabase.auth.update({
+            data: { hello: 'world' }
           })
           ```
 
@@ -369,9 +369,9 @@ pages:
           ```js
           function apiFunction(req, res) {
             // Assuming the access token was sent as a header "X-Supabase-Auth"
-            const { access_token } = req.get('X-Supabase-Auth') 
+            const { access_token } = req.get('X-Supabase-Auth')
 
-            // You can now use it within a Supabase Client 
+            // You can now use it within a Supabase Client
             const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key")
             const { user, error } = supabase.auth.setAuth(access_token)
 
@@ -406,9 +406,9 @@ pages:
           * Use the Auth token in your server-side function.
           */
           async function apiFunction(req, res) {
-            const { access_token } = req.get('X-Supabase-Auth') 
+            const { access_token } = req.get('X-Supabase-Auth')
 
-            // You can now use it within a Supabase Client 
+            // You can now use it within a Supabase Client
             const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key")
             const { user, error } = supabase.auth.setAuth(access_token)
 
@@ -727,8 +727,8 @@ pages:
         js: |
           ```js
           const { data: user, error } = await supabase.functions.invoke('hello', {
-            headers: { 
-              "my-custom-header": 'my-custom-header-value' 
+            headers: {
+              "my-custom-header": 'my-custom-header-value'
             },
             body: JSON.stringify({ foo: 'bar' })
           })
@@ -779,11 +779,11 @@ pages:
           For more details, [follow the link](https://postgrest.org/en/latest/api.html#embedding-through-join-tables).
       - name: Query the same foreign table multiple times
         description: |
-          Sometimes you will need to query the same foreign table twice. 
-          In this case, you can use the name of the joined column to identify 
-          which join you intend to use. For convenience, you can also give an 
-          alias for each column. For example, if we had a shop of products, 
-          and we wanted to get the supplier and the purchaser at the same time 
+          Sometimes you will need to query the same foreign table twice.
+          In this case, you can use the name of the joined column to identify
+          which join you intend to use. For convenience, you can also give an
+          alias for each column. For example, if we had a shop of products,
+          and we wanted to get the supplier and the purchaser at the same time
           (both in the users) table:
         js: |
           ```js
@@ -797,7 +797,7 @@ pages:
           ```
       - name: Filtering with inner joins
         description: |
-          If you want to filter a table based on a child table's values you can use the `!inner()` function. For example, if you wanted 
+          If you want to filter a table based on a child table's values you can use the `!inner()` function. For example, if you wanted
           to select all rows in a `message` table which belong to a user with the `username` "Jane":
         js: |
           ```js
@@ -818,10 +818,10 @@ pages:
           ```
       - name: Querying JSON data
         description: |
-          If you have data inside of a JSONB column, you can apply select 
-          and query filters to the data values. Postgres offers a 
-          [number of operators](https://www.postgresql.org/docs/current/functions-json.html) 
-          for querying JSON data. Also see 
+          If you have data inside of a JSONB column, you can apply select
+          and query filters to the data values. Postgres offers a
+          [number of operators](https://www.postgresql.org/docs/current/functions-json.html)
+          for querying JSON data. Also see
           [PostgREST docs](http://postgrest.org/en/v7.0.0/api.html#json-columns) for more details.
         js: |
           ```js
@@ -875,7 +875,7 @@ pages:
     $ref: '@supabase/postgrest-js."lib/PostgrestQueryBuilder".PostgrestQueryBuilder.insert'
     notes: |
       - By default, every time you run `insert()`, the client library will make a `select` to return the full record.
-      This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation. 
+      This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation.
       If you are using Row Level Security and you are encountering problems, try setting the `returning` param to `minimal`.
     examples:
       - name: Create a record
@@ -890,7 +890,7 @@ pages:
           ```
       - name: Bulk create
         description: |
-          When running a bulk create, the operation is handled in a single transaction. If any of the inserts fail, all other operations are 
+          When running a bulk create, the operation is handled in a single transaction. If any of the inserts fail, all other operations are
           rolled back.
         js: |
           ```js
@@ -903,10 +903,10 @@ pages:
           ```
       - name: Upsert
         description: |
-          For upsert, if set to true, primary key columns would need to be included 
-          in the data parameter in order for an update to properly happen. Also, primary keys 
-          used must be natural, not surrogate. There are however, 
-          [workarounds](https://github.com/PostgREST/postgrest/issues/1118) 
+          For upsert, if set to true, primary key columns would need to be included
+          in the data parameter in order for an update to properly happen. Also, primary keys
+          used must be natural, not surrogate. There are however,
+          [workarounds](https://github.com/PostgREST/postgrest/issues/1118)
           for surrogate primary keys.
         js: |
           ```js
@@ -938,16 +938,16 @@ pages:
           ```
       - name: Updating JSON data
         description: |
-          Postgres offers a 
-          [number of operators](https://www.postgresql.org/docs/current/functions-json.html) 
-          for working with JSON data. Right now it is only possible to update an entire JSON document, 
+          Postgres offers a
+          [number of operators](https://www.postgresql.org/docs/current/functions-json.html)
+          for working with JSON data. Right now it is only possible to update an entire JSON document,
           but we are [working on ideas](https://github.com/PostgREST/postgrest/issues/465) for updating individual keys.
         js: |
           ```js
           const { data, error } = await supabase
             .from('users')
             .update(`
-              address: { 
+              address: {
                 street: 'Melrose Place',
                 postcode: 90210
               }
@@ -959,7 +959,7 @@ pages:
     title: 'Upsert data: upsert()'
     $ref: '@supabase/postgrest-js."lib/PostgrestQueryBuilder".PostgrestQueryBuilder.upsert'
     notes: |
-      - Primary keys should be included in the data payload in order for an update to work correctly. 
+      - Primary keys should be included in the data payload in order for an update to work correctly.
       - Primary keys  must be natural, not surrogate. There are however, [workarounds](https://github.com/PostgREST/postgrest/issues/1118) for surrogate primary keys.
     examples:
       - name: Upsert your data
@@ -983,8 +983,8 @@ pages:
           ```
       - name: Upserting into tables with constraints
         description: |
-          Running the following will cause supabase to upsert data into the `users` table. 
-          If the username 'supabot' already exists, the `onConflict` argument tells supabase to overwrite that row 
+          Running the following will cause supabase to upsert data into the `users` table.
+          If the username 'supabot' already exists, the `onConflict` argument tells supabase to overwrite that row
           based on the column passed into `onConflict`.
         isSpotlight: true
         js: |
@@ -999,11 +999,11 @@ pages:
           ```js
           const { data, error, count } = await supabase
             .from('users')
-            .upsert({ 
-                id: 3, message: 'foo', 
-                username: 'supabot' 
-            }, { 
-              count: 'exact' 
+            .upsert({
+                id: 3, message: 'foo',
+                username: 'supabot'
+            }, {
+              count: 'exact'
             })
           ```
 
@@ -1067,7 +1067,7 @@ pages:
       - name: With filters
         description: |
           Postgres functions that return tables can also be combined with
-          [Modifiers](/docs/reference/javascript/using-modifiers) and 
+          [Modifiers](/docs/reference/javascript/using-modifiers) and
           [Filters](/docs/reference/javascript/using-filters).
         js: |
           ```js
@@ -1126,8 +1126,8 @@ pages:
           ```
       - name: Listening to updates
         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 too: 
+          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 too:
 
           ```sql
           alter table "your_table" replica identity full;
@@ -1143,8 +1143,8 @@ pages:
           ```
       - name: Listening to deletes
         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: 
+          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;
@@ -1222,7 +1222,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.listBuckets'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: `select` 
+        - `buckets` permissions: `select`
         - `objects` permissions: none
     examples:
       - name: List buckets
@@ -1239,7 +1239,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.getBucket'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: `select` 
+        - `buckets` permissions: `select`
         - `objects` permissions: none
     examples:
       - name: Get bucket
@@ -1256,7 +1256,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.createBucket'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: `insert` 
+        - `buckets` permissions: `insert`
         - `objects` permissions: none
     examples:
       - name: Create bucket
@@ -1273,7 +1273,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.emptyBucket'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: `select` 
+        - `buckets` permissions: `select`
         - `objects` permissions: `select` and `delete`
     examples:
       - name: Empty bucket
@@ -1323,7 +1323,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.upload'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `insert`
       - 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:
@@ -1358,7 +1358,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.update'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `update` and `select`
       - 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:
@@ -1393,7 +1393,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.move'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `update` and `select`
     examples:
       - name: Move file
@@ -1411,8 +1411,8 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.copy'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
-        - `objects` permissions: `update` and `select`
+        - `buckets` permissions: none
+        - `objects` permissions: `insert` and `select`
     examples:
       - name: Copy file
         isSpotlight: true
@@ -1429,7 +1429,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.createSignedUrl'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `select`
     examples:
       - name: Create Signed URL
@@ -1447,7 +1447,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.createSignedUrls'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `select`
     examples:
       - name: Create Signed URLs
@@ -1466,7 +1466,7 @@ pages:
     notes: |
       - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public"
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: none
     examples:
       - name: Returns the URL for an asset in a public bucket
@@ -1484,7 +1484,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.download'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `select`
     examples:
       - name: Download file
@@ -1502,7 +1502,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.remove'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `delete` and `select`
     examples:
       - name: Delete file
@@ -1520,7 +1520,7 @@ pages:
     $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.list'
     notes: |
       - Policy permissions required:
-        - `buckets` permissions: none 
+        - `buckets` permissions: none
         - `objects` permissions: `select`
     examples:
       - name: List files in a bucket
@@ -1552,7 +1552,7 @@ pages:
 
   Using Modifiers:
     description: |
-      Modifiers can be used on `select()` queries. 
+      Modifiers can be used on `select()` queries.
 
       If a Postgres function returns a table response, you can also apply modifiers to the `rpc()` function.
 
@@ -1651,7 +1651,7 @@ pages:
 
   Using Filters:
     description: |
-      Filters can be used on `select()`, `update()`, and `delete()` queries. 
+      Filters can be used on `select()`, `update()`, and `delete()` queries.
 
       If a Postgres function returns a table response, you can also apply filters.
 
@@ -1695,7 +1695,7 @@ pages:
       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) }
@@ -2529,8 +2529,8 @@ pages:
           const { data, error } = await supabase
             .from('quotes')
             .select('catchphrase')
-            .textSearch('catchphrase', `'fat' & 'cat'`, { 
-              config: 'english' 
+            .textSearch('catchphrase', `'fat' & 'cat'`, {
+              config: 'english'
             })
           ```
       - name: Basic normalization
@@ -2540,9 +2540,9 @@ pages:
           const { data, error } = await supabase
             .from('quotes')
             .select('catchphrase')
-            .textSearch('catchphrase', `'fat' & 'cat'`, { 
+            .textSearch('catchphrase', `'fat' & 'cat'`, {
               type: 'plain',
-              config: 'english' 
+              config: 'english'
             })
           ```
       - name: Full normalization
@@ -2552,15 +2552,15 @@ pages:
           const { data, error } = await supabase
             .from('quotes')
             .select('catchphrase')
-            .textSearch('catchphrase', `'fat' & 'cat'`, { 
+            .textSearch('catchphrase', `'fat' & 'cat'`, {
               type: 'phrase',
-              config: 'english' 
+              config: 'english'
             })
           ```
       - name: Websearch
         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 
+          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
           with advanced operators.
 
           - `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery.
@@ -2573,7 +2573,7 @@ pages:
           const { data, error } = await supabase
             .from('quotes')
             .select('catchphrase')
-            .textSearch('catchphrase', `'fat or cat'`, { 
+            .textSearch('catchphrase', `'fat or cat'`, {
               type: 'websearch',
               config: 'english'
             })

spec/supabase_js_v2_legacy.yml

@@ -1123,9 +1123,10 @@ pages:
     title: 'listBuckets()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.listBuckets'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `select`
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: `select`
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: List buckets
         isSpotlight: true
@@ -1140,9 +1141,10 @@ pages:
     title: 'getBucket()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.getBucket'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `select`
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: `select`
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Get bucket
         isSpotlight: true
@@ -1157,9 +1159,10 @@ pages:
     title: 'createBucket()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.createBucket'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `insert`
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: `insert`
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Create bucket
         isSpotlight: true
@@ -1174,9 +1177,10 @@ pages:
     title: 'emptyBucket()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.emptyBucket'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `select`
-        - `objects` permissions: `select` and `delete`
+      - RLS policy permissions required:
+        - `buckets` table permissions: `select`
+        - `objects` table permissions: `select` and `delete`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Empty bucket
         isSpotlight: true
@@ -1190,9 +1194,10 @@ pages:
     title: 'updateBucket()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.updateBucket'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `update`
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: `update`
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Update bucket
         isSpotlight: true
@@ -1207,9 +1212,10 @@ pages:
     title: 'deleteBucket()'
     $ref: '@supabase/storage-js.packages/StorageBucketApi.default.deleteBucket'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: `select` and `delete`
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: `select` and `delete`
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Delete bucket
         isSpotlight: true
@@ -1224,9 +1230,10 @@ pages:
     title: 'from.upload()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.upload'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `insert`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `insert`
+      - Refer to the [Storage guide](/docs/guides/storage#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:
       - name: Upload file
@@ -1259,9 +1266,10 @@ pages:
     title: 'from.update()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.update'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `update` and `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `update` and `select`
+      - Refer to the [Storage guide](/docs/guides/storage#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:
       - name: Update file
@@ -1294,9 +1302,10 @@ pages:
     title: 'from.move()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.move'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `update` and `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `update` and `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Move file
         isSpotlight: true
@@ -1312,9 +1321,10 @@ pages:
     title: 'from.copy()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.copy'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `update` and `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `insert` and `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Copy file
         isSpotlight: true
@@ -1330,9 +1340,10 @@ pages:
     title: 'from.createSignedUrl()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrl'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Create Signed URL
         isSpotlight: true
@@ -1348,9 +1359,10 @@ pages:
     title: 'from.createSignedUrls()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrls'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Create Signed URLs
         isSpotlight: true
@@ -1367,15 +1379,16 @@ pages:
     $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 [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public"
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: none
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: none
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Returns the URL for an asset in a public bucket
         isSpotlight: true
         js: |
           ```js
-          const { data, error } = supabase
+          const { data } = supabase
             .storage
             .from('public-bucket')
             .getPublicUrl('folder/avatar1.png')
@@ -1385,9 +1398,10 @@ pages:
     title: 'from.download()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.download'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Download file
         isSpotlight: true
@@ -1403,9 +1417,10 @@ pages:
     title: 'from.remove()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.remove'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `delete` and `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `delete` and `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: Delete file
         isSpotlight: true
@@ -1421,9 +1436,10 @@ pages:
     title: 'from.list()'
     $ref: '@supabase/storage-js.packages/StorageFileApi.default.list'
     notes: |
-      - Policy permissions required:
-        - `buckets` permissions: none
-        - `objects` permissions: `select`
+      - RLS policy permissions required:
+        - `buckets` table permissions: none
+        - `objects` table permissions: `select`
+      - Refer to the [Storage guide](/docs/guides/storage#access-control) on how access control works
     examples:
       - name: List files in a bucket
         isSpotlight: true