node_modules/@supabase/storage-js/src/packages/StorageBucketApi.ts

import { DEFAULT_HEADERS } from '../lib/constants'
import { StorageError } from '../lib/common/errors'
import { Fetch, get, post, put, remove } from '../lib/common/fetch'
import { encodeStoragePath } from '../lib/common/helpers'
import BaseApiClient from '../lib/common/BaseApiClient'
import {
  Bucket,
  BucketType,
  CreateSettableVersioningStatus,
  FetchParameters,
  ListBucketOptions,
  PurgeCacheOptions,
  UpdateSettableVersioningStatus,
} from '../lib/types'
import { StorageClientOptions } from '../StorageClient'

export default class StorageBucketApi extends BaseApiClient<StorageError> {
  constructor(
    url: string,
    headers: { [key: string]: string } = {},
    fetch?: Fetch,
    opts?: StorageClientOptions
  ) {
    const baseUrl = new URL(url)

    // if legacy uri is used, replace with new storage host (disables request buffering to allow > 50GB uploads)
    // "project-ref.supabase.co" becomes "project-ref.storage.supabase.co"
    if (opts?.useNewHostname) {
      const isSupabaseHost = /supabase\.(co|in|red)$/.test(baseUrl.hostname)
      if (isSupabaseHost && !baseUrl.hostname.includes('storage.supabase.')) {
        baseUrl.hostname = baseUrl.hostname.replace('supabase.', 'storage.supabase.')
      }
    }

    const finalUrl = baseUrl.href.replace(/\/$/, '')
    const finalHeaders = { ...DEFAULT_HEADERS, ...headers }

    super(finalUrl, finalHeaders, fetch, 'storage')
  }

  /**
   * Retrieves the details of all Storage buckets within an existing project.
   *
   * @category Storage
   * @subcategory File Buckets
   * @param options Query parameters for listing buckets
   * @param options.limit Maximum number of buckets to return
   * @param options.offset Number of buckets to skip
   * @param options.sortColumn Column to sort by ('id', 'name', 'created_at', 'updated_at')
   * @param options.sortOrder Sort order ('asc' or 'desc')
   * @param options.search Search term to filter bucket names
   * @returns Promise with response containing array of buckets or error
   *
   * @example List buckets
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .listBuckets()
   * ```
   *
   * @example List buckets with options
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .listBuckets({
   *     limit: 10,
   *     offset: 0,
   *     sortColumn: 'created_at',
   *     sortOrder: 'desc',
   *     search: 'prod'
   *   })
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `select`
   *   - `objects` table permissions: none
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async listBuckets(options?: ListBucketOptions): Promise<
    | {
        data: Bucket[]
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      const queryString = this.listBucketOptionsToQueryString(options)
      return await get(this.fetch, `${this.url}/bucket${queryString}`, {
        headers: this.headers,
      })
    })
  }

  /**
   * Retrieves the details of an existing Storage bucket.
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id The unique identifier of the bucket you would like to retrieve.
   * @returns Promise with response containing bucket details or error
   *
   * @example Get bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .getBucket('avatars')
   * ```
   *
   * Response:
   * ```json
   * {
   *   "data": {
   *     "id": "avatars",
   *     "name": "avatars",
   *     "owner": "",
   *     "public": false,
   *     "file_size_limit": 1024,
   *     "allowed_mime_types": [
   *       "image/png"
   *     ],
   *     "created_at": "2024-05-22T22:26:05.100Z",
   *     "updated_at": "2024-05-22T22:26:05.100Z"
   *   },
   *   "error": null
   * }
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `select`
   *   - `objects` table permissions: none
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async getBucket(id: string): Promise<
    | {
        data: Bucket
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      return await get(this.fetch, `${this.url}/bucket/${id}`, { headers: this.headers })
    })
  }

  /**
   * Creates a new Storage bucket
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id A unique identifier for the bucket you are creating.
   * @param options.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.
   * @param options.fileSizeLimit specifies the max file size in bytes that can be uploaded to this bucket.
   * The global file size limit takes precedence over this value.
   * The default value is null, which doesn't set a per bucket file size limit.
   * @param options.allowedMimeTypes specifies the allowed mime types that this bucket can accept during upload.
   * The default value is null, which allows files with all mime types to be uploaded.
   * Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
   * @param options.type (private-beta) specifies the bucket type. see `BucketType` for more details.
   *   - default bucket type is `STANDARD`
   * @param options.versioningStatus the bucket's initial object versioning status.
   * The default value is `DISABLED`
   * @returns Promise with response containing newly created bucket name or error
   *
   * @example Create bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .createBucket('avatars', {
   *     public: false,
   *     allowedMimeTypes: ['image/png'],
   *     fileSizeLimit: 1024
   *   })
   * ```
   *
   * Response:
   * ```json
   * {
   *   "data": {
   *     "name": "avatars"
   *   },
   *   "error": null
   * }
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `insert`
   *   - `objects` table permissions: none
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async createBucket(
    id: string,
    options: {
      public: boolean
      fileSizeLimit?: number | string | null
      allowedMimeTypes?: string[] | null
      type?: BucketType
      versioningStatus?: CreateSettableVersioningStatus
    } = {
      public: false,
    }
  ): Promise<
    | {
        data: Pick<Bucket, 'name'>
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      return await post(
        this.fetch,
        `${this.url}/bucket`,
        {
          id,
          name: id,
          type: options.type,
          public: options.public,
          file_size_limit: options.fileSizeLimit,
          allowed_mime_types: options.allowedMimeTypes,
          versioning_status: options.versioningStatus,
        },
        { headers: this.headers }
      )
    })
  }

  /**
   * Updates a Storage bucket
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id A unique identifier for the bucket you are updating.
   * @param options.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.
   * @param options.fileSizeLimit specifies the max file size in bytes that can be uploaded to this bucket.
   * The global file size limit takes precedence over this value.
   * The default value is null, which doesn't set a per bucket file size limit.
   * @param options.allowedMimeTypes specifies the allowed mime types that this bucket can accept during upload.
   * The default value is null, which allows files with all mime types to be uploaded.
   * Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
   * @param options.versioningStatus the bucket's new object versioning status. `DISABLED` is not
   * valid here, there's no transition back to it once versioning has been touched.
   * @returns Promise with response containing success message or error
   *
   * @example Update bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .updateBucket('avatars', {
   *     public: false,
   *     allowedMimeTypes: ['image/png'],
   *     fileSizeLimit: 1024
   *   })
   * ```
   *
   * Response:
   * ```json
   * {
   *   "data": {
   *     "message": "Successfully updated"
   *   },
   *   "error": null
   * }
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `select` and `update`
   *   - `objects` table permissions: none
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async updateBucket(
    id: string,
    options: {
      public: boolean
      fileSizeLimit?: number | string | null
      allowedMimeTypes?: string[] | null
      versioningStatus?: UpdateSettableVersioningStatus
    }
  ): Promise<
    | {
        data: { message: string }
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      return await put(
        this.fetch,
        `${this.url}/bucket/${id}`,
        {
          id,
          name: id,
          public: options.public,
          file_size_limit: options.fileSizeLimit,
          allowed_mime_types: options.allowedMimeTypes,
          versioning_status: options.versioningStatus,
        },
        { headers: this.headers }
      )
    })
  }

  /**
   * Removes all objects inside a single bucket.
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id The unique identifier of the bucket you would like to empty.
   * @returns Promise with success message or error
   *
   * @example Empty bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .emptyBucket('avatars')
   * ```
   *
   * Response:
   * ```json
   * {
   *   "data": {
   *     "message": "Successfully emptied"
   *   },
   *   "error": null
   * }
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `select`
   *   - `objects` table permissions: `select` and `delete`
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async emptyBucket(id: string): Promise<
    | {
        data: { message: string }
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      return await post(this.fetch, `${this.url}/bucket/${id}/empty`, {}, { headers: this.headers })
    })
  }

  /**
   * Deletes an existing bucket. A bucket can't be deleted with existing objects inside it.
   * You must first `empty()` the bucket.
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id The unique identifier of the bucket you would like to delete.
   * @returns Promise with success message or error
   *
   * @example Delete bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .deleteBucket('avatars')
   * ```
   *
   * Response:
   * ```json
   * {
   *   "data": {
   *     "message": "Successfully deleted"
   *   },
   *   "error": null
   * }
   * ```
   *
   * @remarks
   * - RLS policy permissions required:
   *   - `buckets` table permissions: `select` and `delete`
   *   - `objects` table permissions: none
   * - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
   */
  async deleteBucket(id: string): Promise<
    | {
        data: { message: string }
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      return await remove(this.fetch, `${this.url}/bucket/${id}`, {}, { headers: this.headers })
    })
  }

  /**
   * Purges the CDN cache for an entire bucket.
   *
   * Maps to `DELETE /cdn/{bucket}` on the Storage API. The server
   * issues a CDN invalidation for the bucket and returns `{ message: 'success' }`.
   *
   * **Requires the `service_role` key.** The underlying endpoint enforces
   * `service_role` JWT — calls made with the anon key or a user JWT will be
   * rejected by the server.
   *
   * **Hosted CDN feature.** On self-hosted Supabase, the Storage service must
   * have `CDN_PURGE_ENDPOINT_URL` configured and the `purgeCache` tenant
   * feature enabled, otherwise the server returns an error.
   *
   * @category Storage
   * @subcategory File Buckets
   * @param id The unique identifier of the bucket you would like to purge from cache.
   * @param options Optional purge cache options.
   * @param options.transformations If true, purges only transformations (resized/formatted variants), leaving original cached files intact.
   * @param parameters Optional fetch parameters such as an `AbortController` signal.
   * @returns Promise with `{ data: { message }, error: null }` on success or `{ data: null, error }` on failure.
   *
   * @example Purge cache for an entire bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .purgeBucketCache('avatars')
   * ```
   *
   * @example Purge only transformations for an entire bucket
   * ```js
   * const { data, error } = await supabase
   *   .storage
   *   .purgeBucketCache('avatars', { transformations: true })
   * ```
   */
  async purgeBucketCache(
    id: string,
    options?: PurgeCacheOptions,
    parameters?: FetchParameters
  ): Promise<
    | {
        data: { message: string }
        error: null
      }
    | {
        data: null
        error: StorageError
      }
  > {
    return this.handleOperation(async () => {
      const query = new URLSearchParams()
      if (options?.transformations) {
        query.set('transformations', 'true')
      }
      const queryString = query.toString()

      return await remove(
        this.fetch,
        `${this.url}/cdn/${encodeStoragePath(id)}${queryString ? `?${queryString}` : ''}`,
        {},
        { headers: this.headers },
        parameters
      )
    })
  }

  private listBucketOptionsToQueryString(options?: ListBucketOptions): string {
    const params: Record<string, string> = {}
    if (options) {
      if ('limit' in options) {
        params.limit = String(options.limit)
      }
      if ('offset' in options) {
        params.offset = String(options.offset)
      }
      if (options.search) {
        params.search = options.search
      }
      if (options.sortColumn) {
        params.sortColumn = options.sortColumn
      }
      if (options.sortOrder) {
        params.sortOrder = options.sortOrder
      }
    }
    return Object.keys(params).length > 0 ? '?' + new URLSearchParams(params).toString() : ''
  }
}