better-supabase 0.14.0 → 0.15.1

package/dist/bucket-CiNi8sIw.d.ts

@@ -0,0 +1,666 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, f as Result, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { Ft as RequestContext, T as AccessBucketPolicy, _t as BucketLifecycle, bt as VersioningStatus, j as BucketPolicyName, yt as ObjectVersion } from "./types-DFdg_4yN.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/core/template.d.ts
+/**
+ * Placeholder names in a `{name}` template; a rest placeholder `{...name}` is
+ * `name`.
+ */
+type TemplateParams<P extends string> = P extends `${string}{${infer K}}${infer R}` ? (K extends `...${infer N}` ? N : K) | TemplateParams<R> : never;
+type TemplateValues<P extends string> = { readonly [K in TemplateParams<P>]: string | number; };
+//#endregion
+//#region src/storage/apply.d.ts
+interface AppliedBucket {
+  /** The bucket did not exist and was created. */
+  readonly created: boolean;
+}
+//#endregion
+//#region src/storage/path.d.ts
+declare const bucketOf: unique symbol;
+/**
+ * An object path in bucket `B`, e.g. `org-1/cust-1/logo/3.webp`. Returned by
+ * `bucket.path()` and `upload()`, and the type of columns listed in the
+ * `storagePaths` config. Store paths, not URLs: signed URLs expire and public
+ * URLs pin the project host.
+ */
+type StoragePath<B extends string = string> = string & {
+  readonly [bucketOf]: B;
+};
+/**
+ * A plain string or a `StoragePath` of bucket `B`; paths of other buckets are
+ * rejected.
+ */
+type PathIn<B extends string> = string & {
+  readonly [bucketOf]?: B;
+};
+//#endregion
+//#region src/storage/storage-api.d.ts
+/**
+ * A failed Storage call's `error`, as supabase-js returns it
+ * (`StorageApiError`, `StorageUnknownError`).
+ */
+interface StorageFailure {
+  readonly name: string;
+  readonly message: string;
+  readonly status?: number | undefined;
+  readonly statusCode?: string | undefined;
+  /** The Storage error code, such as `NoSuchKey` or `AccessDenied`. */
+  readonly code?: string | undefined;
+}
+/** What a supabase-js Storage call resolves to: `data` or `error`, never both. */
+type StorageResponse<T> = {
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly data: null;
+  readonly error: StorageFailure;
+};
+interface StorageTransform {
+  readonly width?: number;
+  readonly height?: number;
+  readonly resize?: "cover" | "contain" | "fill";
+  readonly quality?: number;
+  readonly format?: "origin";
+}
+interface StorageUrlOptions {
+  readonly download?: string | boolean;
+  readonly transform?: StorageTransform;
+  readonly cacheNonce?: string;
+  readonly versionId?: string;
+}
+interface StorageDownloadOptions {
+  readonly transform?: StorageTransform;
+  readonly cacheNonce?: string;
+  readonly versionId?: string;
+}
+interface StorageFetchParameters {
+  readonly signal?: AbortSignal;
+  readonly cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached";
+}
+interface StorageFileOptions {
+  readonly cacheControl?: string;
+  readonly contentType?: string;
+  readonly upsert?: boolean;
+  readonly duplex?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+interface StorageDestinationOptions {
+  readonly destinationBucket?: string;
+  readonly sourceVersionId?: string;
+}
+/** `list(prefix, options)`: one folder level, folders first when sorted by name. */
+interface StorageSearchOptions {
+  /** Defaults to 100. */
+  readonly limit?: number;
+  readonly offset?: number;
+  /** Defaults to `{ column: "name", order: "asc" }`. */
+  readonly sortBy?: {
+    readonly column?: string;
+    readonly order?: string;
+  };
+  /** Entries whose name starts with this text, ignoring case. */
+  readonly search?: string;
+  readonly noncurrentVersions?: "exclude" | "include" | "only";
+  readonly deleteMarkers?: "exclude" | "include" | "only";
+  readonly exactMatch?: boolean;
+}
+interface StorageSearchV2Options {
+  /** Defaults to 1000, the most one page returns. */
+  readonly limit?: number;
+  readonly prefix?: string;
+  /** `nextCursor` of the previous page. */
+  readonly cursor?: string;
+  /** Group the objects below the next `/` into folders. */
+  readonly with_delimiter?: boolean;
+  readonly sortBy?: {
+    readonly column: "name" | "updated_at" | "created_at";
+    readonly order?: "asc" | "desc";
+  };
+  readonly noncurrentVersions?: "exclude" | "include" | "only";
+  readonly deleteMarkers?: "exclude" | "include" | "only";
+  readonly exactMatch?: boolean;
+}
+/** An entry of `list`: a file, or a folder when `id` is `null`. */
+interface StorageListEntry {
+  readonly name: string;
+  readonly id: string | null;
+  readonly updated_at: string | null;
+  readonly created_at: string | null;
+  readonly last_accessed_at?: string | null;
+  readonly metadata: Readonly<Record<string, unknown>> | null;
+}
+interface StorageListV2Object {
+  readonly name: string;
+  readonly key?: string;
+  readonly id: string;
+  readonly updated_at: string;
+  readonly created_at: string;
+  readonly last_accessed_at?: string;
+  readonly metadata: Readonly<Record<string, unknown>> | null;
+  readonly version?: string;
+  readonly archived_at?: string | null;
+  readonly is_delete_marker?: boolean;
+  readonly is_versioned?: boolean;
+}
+interface StorageListV2Folder {
+  /** The folder's full path, ending in `/`. */
+  readonly name: string;
+  readonly key?: string;
+}
+interface StorageListV2Result {
+  readonly hasNext: boolean;
+  readonly nextCursor?: string;
+  readonly folders: readonly StorageListV2Folder[];
+  readonly objects: readonly StorageListV2Object[];
+}
+/** `info(path)`, in camelCase as supabase-js returns it. */
+interface StorageObjectInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly bucketId: string;
+  readonly createdAt: string;
+  readonly size?: number;
+  readonly contentType?: string;
+  readonly cacheControl?: string;
+  readonly etag?: string;
+  readonly lastModified?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly updatedAt?: string;
+  readonly archivedAt?: string | null;
+  readonly isDeleteMarker?: boolean;
+  readonly isVersioned?: boolean;
+}
+interface StorageSignedUrlEntry {
+  readonly error: string | null;
+  readonly path: string | null;
+  readonly signedUrl: string | null;
+}
+type StorageRemoveEntry = string | {
+  readonly path: string;
+  readonly versionId: string;
+};
+/**
+ * One bucket's file API: the methods of supabase-js
+ * `supabase.storage.from(bucket)` that bucket clients and blocks call, typed
+ * structurally so another implementation (such as `supportStorage`) can stand
+ * in for it.
+ */
+interface StorageBucketApi {
+  upload(path: string, body: UploadBody, options?: StorageFileOptions): PromiseLike<StorageResponse<{
+    readonly path: string;
+  }>>;
+  update(path: string, body: UploadBody, options?: StorageFileOptions): PromiseLike<StorageResponse<{
+    readonly path: string;
+  }>>;
+  createSignedUploadUrl(path: string, options?: {
+    upsert: boolean;
+  }): PromiseLike<StorageResponse<{
+    readonly signedUrl: string;
+    readonly token: string;
+    readonly path: string;
+  }>>;
+  uploadToSignedUrl(path: string, token: string, body: UploadBody, options?: StorageFileOptions): PromiseLike<StorageResponse<{
+    readonly path: string;
+  }>>;
+  download(path: string, options?: StorageDownloadOptions, parameters?: StorageFetchParameters): PromiseLike<StorageResponse<Blob>>;
+  info(path: string, options?: {
+    versionId?: string;
+  }): PromiseLike<StorageResponse<StorageObjectInfo>>;
+  /** `data` is `false` with an `error` when Storage answers 400 or 404. */
+  exists(path: string): PromiseLike<{
+    readonly data: boolean;
+    readonly error: null;
+  } | {
+    readonly data: boolean;
+    readonly error: StorageFailure;
+  }>;
+  createSignedUrl(path: string, expiresIn: number, options?: StorageUrlOptions): PromiseLike<StorageResponse<{
+    readonly signedUrl: string;
+  }>>;
+  createSignedUrls(paths: string[], expiresIn: number, options?: {
+    download?: string | boolean;
+    cacheNonce?: string;
+  }): PromiseLike<StorageResponse<readonly StorageSignedUrlEntry[]>>;
+  getPublicUrl(path: string, options?: StorageUrlOptions): {
+    readonly data: {
+      readonly publicUrl: string;
+    };
+  };
+  remove(paths: StorageRemoveEntry[]): PromiseLike<StorageResponse<readonly StorageListEntry[]>>;
+  copy(from: string, to: string, options?: StorageDestinationOptions): PromiseLike<StorageResponse<{
+    readonly path: string;
+  }>>;
+  move(from: string, to: string, options?: StorageDestinationOptions): PromiseLike<StorageResponse<{
+    readonly message: string;
+  }>>;
+  purgeCache(path: string, options?: {
+    transformations?: true;
+  }, parameters?: StorageFetchParameters): PromiseLike<StorageResponse<{
+    readonly message: string;
+  }>>;
+  list(path?: string, options?: StorageSearchOptions, parameters?: StorageFetchParameters): PromiseLike<StorageResponse<readonly StorageListEntry[]>>;
+  listV2(options?: StorageSearchV2Options, parameters?: StorageFetchParameters): PromiseLike<StorageResponse<StorageListV2Result>>;
+}
+/**
+ * Storage's file API: `supabase.storage`, or anything with the same
+ * `from(bucket)`.
+ */
+interface StorageApi {
+  from(bucket: string): StorageBucketApi;
+  /**
+   * Finishes an upload to a signed upload URL: makes the caller the owner of
+   * the object when it has none. supabase-js has no such method, as Storage
+   * sets the owner from the caller's token; `supportStorage` adds it.
+   */
+  claimSignedUpload?(bucket: string, path: string): PromiseLike<StorageResponse<{
+    readonly path: string;
+  }>>;
+}
+/**
+ * What `bucket.connect()` takes: a `StorageApi`, or a client that carries one
+ * as `storage` (a supabase-js client).
+ */
+type StorageClient = StorageApi | {
+  readonly storage: StorageApi;
+};
+//#endregion
+//#region src/storage/ttl.d.ts
+declare const TTL: {
+  readonly minute: 60;
+  readonly hour: 3600;
+  readonly day: 86_400;
+  readonly week: 604_800;
+};
+type TtlPreset = keyof typeof TTL;
+//#endregion
+//#region src/storage/bucket.d.ts
+type BucketPolicy = BucketPolicyName | AccessBucketPolicy;
+interface BucketConfig<P extends string = string, Id extends string = string, V extends string = never> {
+  /** Bucket id, e.g. `customer-logos`. */
+  readonly id: Id;
+  /**
+   * Object path template, e.g.
+   * `{organizationId}/{customerId}/logo/{version}.webp`, or several for a
+   * bucket that stores objects in more than one layout. A path from values uses
+   * the template whose placeholders are exactly the values given, and a stored
+   * path string is accepted when any template matches it, so list the current
+   * layout first and keep older ones after it. A last segment `{...rest}`
+   * matches one or more segments.
+   */
+  readonly path: P | readonly [P, ...P[]];
+  readonly public?: boolean;
+  /**
+   * Generated `storage.objects` policies. `tenant` and `owner` match a path
+   * segment against the JWT; `public` allows reads (on a `public: true` bucket
+   * the public URLs need no policy, so none is written and nobody can list the
+   * objects); `none` leaves access to the secret key; `{ access }` calls the
+   * SQL modules' access contract (`tenant_ids_with`), or the `sql` templates it
+   * is given. Defaults to `none`.
+   *
+   * The access checks decide by role and scope only: for a permission with row
+   * conditions (e.g. `ownerId = principal.id`) the bucket would grant every
+   * object in the scope. `better-supabase doctor` (BS214) refuses keys the
+   * authorization provider doesn't mark `sqlComplete: true`.
+   */
+  readonly policy?: BucketPolicy;
+  /** `'5MiB'`, `'500KB'` or bytes. */
+  readonly fileSizeLimit?: string | number;
+  /** `['image/png', 'image/*']`. */
+  readonly allowedMimeTypes?: readonly string[];
+  /**
+   * Keep earlier versions of an object when it is overwritten or removed. Set
+   * by `apply()` through the Storage API; `sql()` can't write it.
+   */
+  readonly versioning?: boolean;
+  /**
+   * When noncurrent versions expire. Needs `versioning: true`; set by
+   * `apply()`, which removes a stored policy when this is unset.
+   */
+  readonly lifecycle?: BucketLifecycle;
+  /**
+   * The tenant segment. Set it and connected clients only touch paths whose
+   * `param` holds the caller's tenant: pass `{ context }` or `{ tenant }` to
+   * `connect()`, or `{ allTenants: true }` for cross-tenant admin work.
+   */
+  readonly tenant?: {
+    /** Placeholder holding the tenant id. Defaults to `organizationId`. */
+    readonly param?: string;
+    /**
+     * JWT claim paths, first match wins. Defaults to `tenant_id`, then
+     * `app_metadata.tenant_id`.
+     */
+    readonly claim?: string | readonly string[];
+    /** SQL expression for the tenant id, instead of `claim`. */
+    readonly sql?: string;
+  };
+  readonly owner?: {
+    /** Placeholder holding the user id. Defaults to `userId`. */
+    readonly param?: string;
+  };
+  /**
+   * Named image transformations, e.g. `{ thumb: { width: 96, height: 96,
+   * resize: "cover" } }`. `renderUrl`, `signedUrl` and `publicUrl` take the
+   * name wherever they take a transform. Width and height run from 1 to 2500
+   * and quality from 20 to 100.
+   */
+  readonly variants?: Readonly<Record<V, TransformOptions>>;
+}
+/** The values of one of the bucket's path templates. */
+type PathValues<P extends string> = P extends string ? TemplateValues<P> : never;
+/**
+ * A path from the values of one of the bucket's templates, or an existing path
+ * string (checked against the templates). `StoragePath`s of other buckets are
+ * rejected.
+ */
+type ObjectTarget<P extends string, Id extends string = string> = PathValues<P> | PathIn<Id>;
+/**
+ * A Storage image transformation. With both `width` and `height`, `cover` (the
+ * default) crops the center to that aspect ratio, `contain` fits the whole
+ * image inside it, and `fill` stretches it.
+ */
+interface TransformOptions {
+  readonly width?: number;
+  readonly height?: number;
+  readonly resize?: "cover" | "contain" | "fill";
+  readonly quality?: number;
+  readonly format?: "origin";
+}
+/** One of the bucket's variant names, or an inline transform. */
+type ImageTransform<V extends string = never> = V | TransformOptions;
+type UploadBody = Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | FormData | string;
+interface UploadOptions {
+  readonly contentType?: string;
+  readonly cacheControl?: string;
+  readonly upsert?: boolean;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly signal?: AbortSignal;
+  /**
+   * Upload progress from 0 to 1. Where `XMLHttpRequest` exists (browsers, React
+   * Native) the body goes to a signed upload URL so progress events arrive and
+   * `signal` cancels the request; elsewhere it reports 1 when done. Uploads
+   * with `metadata` or a stream body report 1 when done.
+   */
+  readonly onProgress?: (fraction: number) => void;
+}
+interface UrlOptions<V extends string = never> {
+  /** Seconds or a preset. Defaults to `hour`. */
+  readonly ttl?: number | TtlPreset;
+  /** A variant name or an inline transform. */
+  readonly transform?: ImageTransform<V>;
+  /** Serve as an attachment, optionally with a file name. */
+  readonly download?: boolean | string;
+  /**
+   * Added to the URL so the CDN and browsers fetch it again, e.g. the object's
+   * `updatedAt`.
+   */
+  readonly cacheNonce?: string;
+  /**
+   * A URL for this version of the object instead of the current one (a
+   * versioned bucket).
+   */
+  readonly versionId?: string;
+}
+interface DownloadOptions {
+  /** Read this version of the object instead of the current one. */
+  readonly versionId?: string;
+  readonly signal?: AbortSignal;
+}
+interface TransferOptions {
+  /** Copy or move this version of the source instead of the current one. */
+  readonly versionId?: string;
+}
+interface PurgeCacheOptions {
+  /** Purge only the transformed variants and keep the cached original. */
+  readonly transformations?: boolean;
+  readonly signal?: AbortSignal;
+}
+interface StoredObject {
+  readonly path: string;
+  readonly size?: number;
+  readonly contentType?: string;
+  readonly createdAt: string | null;
+  readonly updatedAt: string | null;
+}
+interface Reservation {
+  readonly path: string;
+  readonly token: string;
+  readonly signedUrl: string;
+}
+interface ReplaceOptions<Id extends string = string> extends UploadOptions {
+  /**
+   * Path the object replaces, checked like any other target before the upload.
+   * Removed after `commit` succeeds.
+   */
+  readonly previous?: string | null;
+  /**
+   * Store the new path, e.g. update the row. Throwing or returning an error
+   * `Result` removes the new object and keeps the previous one.
+   */
+  readonly commit?: (path: StoragePath<Id>) => unknown;
+}
+interface ReplaceResult<Id extends string = string> {
+  readonly path: StoragePath<Id>;
+  readonly removed: string | null;
+  /** Set when the previous object could not be removed. */
+  readonly cleanup?: DbError;
+}
+interface SweepOptions<P extends string> {
+  /** Only look under the path prefix these values fill. */
+  readonly within?: Partial<TemplateValues<P>>;
+  /**
+   * A cutoff instant, or a minimum age. A duration counts a day as 24 hours and
+   * cannot use months or years.
+   */
+  readonly olderThan: Temporal.Instant | Temporal.Duration;
+  /** Returns which of `paths` are still referenced. */
+  readonly referenced: (paths: readonly string[]) => PromiseLike<Iterable<string>> | Iterable<string>;
+  readonly dryRun?: boolean;
+  readonly batchSize?: number;
+  readonly signal?: AbortSignal;
+  readonly now?: () => Temporal.Instant;
+}
+interface SweepResult {
+  readonly scanned: number;
+  readonly orphans: readonly string[];
+  readonly removed: readonly string[];
+}
+interface BucketDrift {
+  readonly field: "missing" | "public" | "fileSizeLimit" | "allowedMimeTypes" | "versioning" | "lifecycle";
+  readonly expected: unknown;
+  readonly actual: unknown;
+  readonly message: string;
+}
+/**
+ * Bucket state as stored in `storage.buckets` (or `better-supabase`
+ * introspection).
+ */
+interface ActualBucket {
+  readonly public: boolean;
+  readonly fileSizeLimit?: number | null;
+  readonly allowedMimeTypes?: readonly string[] | null;
+  /**
+   * `storage.buckets.versioning_status`; leave it out when Storage has no
+   * versioning, and it isn't compared.
+   */
+  readonly versioning?: VersioningStatus | null;
+  /**
+   * `storage.buckets.lifecycle_configuration`; leave it out to skip the
+   * comparison.
+   */
+  readonly lifecycle?: unknown;
+}
+/**
+ * A supabase-js client with the secret key: `apply()` needs the bucket admin
+ * API.
+ */
+type StorageAdminClient = Pick<SupabaseClient, "storage">;
+interface BucketClient<P extends string, Id extends string = string, V extends string = never> {
+  readonly bucket: Bucket<P, Id, V>;
+  /**
+   * The object path, checked against the template and, with `tenant`, the
+   * caller's tenant.
+   */
+  path(target: ObjectTarget<P, Id>): Result<StoragePath<Id>>;
+  upload(target: ObjectTarget<P, Id>, body: UploadBody, options?: UploadOptions): AsyncResult<{
+    path: StoragePath<Id>;
+  }>;
+  download(target: ObjectTarget<P, Id>, options?: DownloadOptions): AsyncResult<Blob>;
+  exists(target: ObjectTarget<P, Id>): AsyncResult<boolean>;
+  remove(targets: readonly ObjectTarget<P, Id>[]): AsyncResult<readonly string[]>;
+  /**
+   * Copies an object to another path in the bucket; an existing object there is
+   * a `conflict`.
+   */
+  copy(from: ObjectTarget<P, Id>, to: ObjectTarget<P, Id>, options?: TransferOptions): AsyncResult<{
+    path: StoragePath<Id>;
+  }>;
+  /** Moves an object to another path in the bucket, as one Storage request. */
+  move(from: ObjectTarget<P, Id>, to: ObjectTarget<P, Id>, options?: TransferOptions): AsyncResult<{
+    path: StoragePath<Id>;
+  }>;
+  /** Every version of the object, newest first, including delete markers. */
+  versions(target: ObjectTarget<P, Id>, options?: {
+    signal?: AbortSignal;
+  }): AsyncResult<readonly ObjectVersion[]>;
+  /** Permanently removes versions of the object, current or noncurrent. */
+  removeVersions(target: ObjectTarget<P, Id>, versionIds: readonly string[]): AsyncResult<readonly string[]>;
+  /**
+   * Purges the CDN cache for the object. Needs the secret key, and on
+   * self-hosted Storage a configured CDN purge endpoint.
+   */
+  purgeCache(target: ObjectTarget<P, Id>, options?: PurgeCacheOptions): AsyncResult<void>;
+  list(within?: Partial<TemplateValues<P>>, options?: {
+    signal?: AbortSignal;
+  }): AsyncResult<readonly StoredObject[]>;
+  signedUrl(target: ObjectTarget<P, Id>, options?: UrlOptions<V>): AsyncResult<string>;
+  signedUrls(targets: readonly ObjectTarget<P, Id>[], options?: Omit<UrlOptions, "transform">): AsyncResult<readonly string[]>;
+  /**
+   * URL for public buckets. No request is made, so it returns a `Result` like
+   * `path()`: an error for a path outside the templates or the tenant.
+   */
+  publicUrl(target: ObjectTarget<P, Id>, options?: Omit<UrlOptions<V>, "ttl">): Result<string>;
+  /**
+   * Image transform URL for a variant name or an inline transform: public for
+   * public buckets, signed otherwise. Pass `download` to serve the resized copy
+   * as an attachment.
+   */
+  renderUrl(target: ObjectTarget<P, Id>, transform: ImageTransform<V>, options?: Omit<UrlOptions, "transform">): AsyncResult<string>;
+  /** Upload the new object, run `commit`, then remove the previous object. */
+  replace(target: ObjectTarget<P, Id>, body: UploadBody, options?: ReplaceOptions<Id>): AsyncResult<ReplaceResult<Id>>;
+  /** A signed upload URL for a browser or another service. */
+  reserve(target: ObjectTarget<P, Id>, options?: {
+    upsert?: boolean;
+  }): AsyncResult<Reservation>;
+  uploadReserved(reservation: Pick<Reservation, "path" | "token">, body: UploadBody, options?: UploadOptions): AsyncResult<{
+    path: StoragePath<Id>;
+  }>;
+  /**
+   * Finishes a reserved upload once the file is stored. In a support session it
+   * makes the target the owner and records the session; elsewhere Storage
+   * already set the owner, and it succeeds without a request.
+   */
+  claimReserved(reservation: Pick<Reservation, "path">): AsyncResult<{
+    path: StoragePath<Id>;
+  }>;
+  /**
+   * Removes objects that match a template and the `within` values, are old
+   * enough and are not referenced.
+   */
+  sweep(options: SweepOptions<P>): AsyncResult<SweepResult>;
+}
+interface Bucket<P extends string, Id extends string = string, V extends string = never> {
+  readonly id: Id;
+  /** The first path template. */
+  readonly template: P;
+  /** Every path template, in the order given. */
+  readonly templates: readonly P[];
+  readonly params: readonly TemplateParams<P>[];
+  readonly public: boolean;
+  readonly policy: BucketPolicy;
+  /**
+   * Placeholder holding the owning user's id: `owner.param` for `owner`
+   * buckets, otherwise `userId` when the template has it. Account deletion
+   * removes the objects it fills.
+   */
+  readonly owner: string | undefined;
+  /**
+   * Placeholder connected clients check against the caller's tenant; set by
+   * `tenant`.
+   */
+  readonly tenant: string | undefined;
+  readonly fileSizeLimit: number | undefined;
+  readonly allowedMimeTypes: readonly string[] | undefined;
+  readonly versioning: boolean;
+  readonly lifecycle: BucketLifecycle | undefined;
+  /** The named image transformations, `{}` when the bucket has none. */
+  readonly variants: Readonly<Record<V, TransformOptions>>;
+  /**
+   * Builds a path with the template whose placeholders are exactly the keys of
+   * `values`. A value Storage would refuse, or keys no template takes, is an
+   * `invalid_input` error.
+   */
+  path(values: PathValues<P>): Result<StoragePath<Id>>;
+  /** The values of the first template that matches `path`, or `null`. */
+  match(path: string): PathValues<P> | null;
+  /** Folder prefix filled by `values`, for listing. */
+  prefix(values?: Partial<TemplateValues<P>>): string;
+  /** Checks a size and content type against the bucket limits. */
+  check(file: {
+    size?: number;
+    type?: string;
+  }): DbError | undefined;
+  /** `insert into storage.buckets` plus `storage.objects` policies. Idempotent. */
+  sql(): string;
+  /** A `[storage.buckets.<id>]` section for `supabase/config.toml`. */
+  toml(): string;
+  drift(actual: ActualBucket | undefined): readonly BucketDrift[];
+  /**
+   * Creates or updates the bucket through the Storage API, including versioning
+   * and the lifecycle policy, which `sql()` can't set. Needs the secret key.
+   * Idempotent.
+   */
+  apply(client: StorageAdminClient): AsyncResult<AppliedBucket>;
+  connect(client: StorageClient, options?: BucketConnectOptions): BucketClient<P, Id, V>;
+}
+interface BucketConnectOptions {
+  /**
+   * Reuse a signed URL for the same path, `ttl`, `transform` and `download`
+   * until shortly before it expires (a tenth of the `ttl`, at most a minute).
+   * The cache belongs to this connection; connect once per request so URLs
+   * never cross users.
+   */
+  readonly cacheSignedUrls?: boolean;
+  /**
+   * The request context (`db.$context`, or what an adapter passes to
+   * `connect`). For a bucket with `tenant`, its tenant (`context.tenant`, the
+   * one `membershipsExtension()` resolved, or the `tenant.claim` claims) must
+   * fill the tenant segment of every path.
+   */
+  readonly context?: RequestContext;
+  /** The tenant every path must hold, instead of reading it from `context`. */
+  readonly tenant?: string;
+  /** Skip the tenant check, for admin jobs that work across tenants. */
+  readonly allTenants?: boolean;
+}
+declare function parseSize(value: string | number): number;
+/**
+ * A typed Storage bucket: path builders from a template, limits, generated SQL
+ * policies and `config.toml`, and helpers for the multi-step work apps repeat
+ * (replace, signed uploads, orphan cleanup).
+ *
+ * ```ts
+ * export const logos = defineBucket({
+ *   id: "customer-logos",
+ *   path: "{organizationId}/{customerId}/logo/{version}.webp",
+ *   policy: "tenant",
+ *   fileSizeLimit: "5MiB",
+ *   allowedMimeTypes: ["image/webp"],
+ * });
+ * ```
+ */
+declare function defineBucket<const P extends string, const Id extends string = string, const V extends string = never>(config: BucketConfig<P, Id, V>): Bucket<P, Id, V>;
+//#endregion
+export { TemplateValues as $, StorageBucketApi as A, StorageListV2Result as B, UploadOptions as C, TTL as D, parseSize as E, StorageFetchParameters as F, StorageSearchV2Options as G, StorageRemoveEntry as H, StorageFileOptions as I, StorageUrlOptions as J, StorageSignedUrlEntry as K, StorageListEntry as L, StorageDestinationOptions as M, StorageDownloadOptions as N, TtlPreset as O, StorageFailure as P, TemplateParams as Q, StorageListV2Folder as R, UploadBody as S, defineBucket as T, StorageResponse as U, StorageObjectInfo as V, StorageSearchOptions as W, StoragePath as X, PathIn as Y, AppliedBucket as Z, StoredObject as _, BucketConnectOptions as a, TransferOptions as b, DownloadOptions as c, PathValues as d, PurgeCacheOptions as f, StorageAdminClient as g, Reservation as h, BucketConfig as i, StorageClient as j, StorageApi as k, ImageTransform as l, ReplaceResult as m, Bucket as n, BucketDrift as o, ReplaceOptions as p, StorageTransform as q, BucketClient as r, BucketPolicy as s, ActualBucket as t, ObjectTarget as u, SweepOptions as v, UrlOptions as w, TransformOptions as x, SweepResult as y, StorageListV2Object as z };