better-supabase 0.5.0 → 0.6.0

package/dist/{index-SaTsEfGP.d.ts → bucket-Cl46E3jS.d.ts}

@@ -1,53 +1,76 @@
 /// <reference lib="esnext.temporal" />
-import { a as BucketPolicyName, t as AccessBucketPolicy, x as PermdockBucketPolicy } from "./types-Dnf_wRDz.js";
-import { _ as DbError, a as AsyncResult, u as Result } from "./executor-BunPOO-k.js";
-import { g as RequestContext } from "./plugin-o144f322.js";
-import { n as PermdockCatalog } from "./permdock-sql-C2Inc6Xc.js";
+import { b as DbError, f as Result, t as AsyncResult } from "./result-D7y2fT87.js";
+import { G as ObjectVersion, K as VersioningStatus, U as BucketLifecycle, s as BucketPolicyName, t as AccessBucketPolicy } from "./types-6BdhkmZe.js";
+import { m as RequestContext } from "./plugin-FGY8UhYm.js";
 import { n as StoragePath, t as PathIn } from "./path-Cv__-OTj.js";
-import { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
+import { n as TemplateValues, t as TemplateParams } from "./template-CwO38Do8.js";
 import { SupabaseClient } from "@supabase/supabase-js";
+//#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/apply.d.ts
+interface AppliedBucket {
+  /** The bucket did not exist and was created. */
+  readonly created: boolean;
+}
+//#endregion
 //#region src/storage/bucket.d.ts
-type BucketPolicy = BucketPolicyName | PermdockBucketPolicy | AccessBucketPolicy;
+type BucketPolicy = BucketPolicyName | AccessBucketPolicy;
 interface BucketConfig<P extends string = string, Id extends string = string> {
   /** Bucket id, e.g. `customer-logos`. */
   readonly id: Id;
-  /** Object path template, e.g. `{orgId}/{customerId}/logo/{version}.webp`. */
-  readonly path: P;
+  /**
+   * 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; `{ permdock, scope }` calls PermDock's SQL helpers;
-   * `{ access }` calls the SQL kit's access contract (`tenant_ids_with`).
-   * Defaults to `none`.
+   * the secret key; `{ access }` calls the SQL modules' access contract
+   * (`tenant_ids_with`), or the `sql` templates it is given. Defaults to
+   * `none`.
    *
-   * The helpers check role and scope only. Use `permdock` just for
-   * permissions whose grants have no row conditions beyond the scope: for a
-   * permission with row conditions (e.g. `ownerId = principal.id`) the bucket
-   * would grant every object in the scope. Pass `catalog` to refuse those
-   * keys here; `better-supabase doctor` (BS214) refuses them from the
-   * catalog file.
+   * 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;
-  /**
-   * PermDock's `permissions.catalog.json`. With it, a `permdock` policy
-   * naming a permission without `rowConditions: false` (including one the
-   * catalog doesn't list) throws.
-   */
-  readonly catalog?: PermdockCatalog;
   /** `'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 `orgId`. */
+    /** 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[];
@@ -59,18 +82,14 @@ interface BucketConfig<P extends string = string, Id extends string = string> {
     readonly param?: string;
   };
 }
+/** 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 template's values, or an existing path string (checked
- * against the template). `StoragePath`s of other buckets are rejected.
+ * 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> = TemplateValues<P> | PathIn<Id>;
-declare const TTL: {
-  readonly minute: 60;
-  readonly hour: 3600;
-  readonly day: 86_400;
-  readonly week: 604_800;
-};
-type TtlPreset = keyof typeof TTL;
+type ObjectTarget<P extends string, Id extends string = string> = PathValues<P> | PathIn<Id>;
 interface TransformOptions {
   readonly width?: number;
   readonly height?: number;
@@ -85,6 +104,13 @@ interface UploadOptions {
   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 {
   /** Seconds or a preset. Defaults to `hour`. */
@@ -92,6 +118,24 @@ interface UrlOptions {
   readonly transform?: TransformOptions;
   /** 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;
@@ -106,7 +150,10 @@ interface Reservation {
   readonly signedUrl: string;
 }
 interface ReplaceOptions<Id extends string = string> extends UploadOptions {
-  /** Path the object replaces. Removed after `commit` succeeds. */
+  /**
+   * 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
@@ -141,7 +188,7 @@ interface SweepResult {
   readonly removed: readonly string[];
 }
 interface BucketDrift {
-  readonly field: "missing" | "public" | "fileSizeLimit" | "allowedMimeTypes";
+  readonly field: "missing" | "public" | "fileSizeLimit" | "allowedMimeTypes" | "versioning" | "lifecycle";
   readonly expected: unknown;
   readonly actual: unknown;
   readonly message: string;
@@ -151,6 +198,10 @@ 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;
 }
 type StorageClient = Pick<SupabaseClient, "storage">;
 interface BucketClient<P extends string, Id extends string = string> {
@@ -160,18 +211,38 @@ interface BucketClient<P extends string, Id extends string = string> {
   upload(target: ObjectTarget<P, Id>, body: UploadBody, options?: UploadOptions): AsyncResult<{
     path: StoragePath<Id>;
   }>;
-  download(target: ObjectTarget<P, Id>, options?: {
-    signal?: AbortSignal;
-  }): AsyncResult<Blob>;
+  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): AsyncResult<string>;
   signedUrls(targets: readonly ObjectTarget<P, Id>[], options?: Omit<UrlOptions, "transform">): AsyncResult<readonly string[]>;
-  /** URL for public buckets. No request is made. */
-  publicUrl(target: ObjectTarget<P, Id>, options?: Omit<UrlOptions, "ttl">): 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, "ttl">): Result<string>;
   /** Image transform URL: public for public buckets, signed otherwise. */
   renderUrl(target: ObjectTarget<P, Id>, transform: TransformOptions, options?: Omit<UrlOptions, "transform">): AsyncResult<string>;
   /** Upload the new object, run `commit`, then remove the previous object. */
@@ -183,12 +254,15 @@ interface BucketClient<P extends string, Id extends string = string> {
   uploadReserved(reservation: Pick<Reservation, "path" | "token">, body: UploadBody, options?: UploadOptions): AsyncResult<{
     path: StoragePath<Id>;
   }>;
-  /** Removes objects that match the template, are old enough and are not referenced. */
+  /** 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> {
   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;
@@ -202,8 +276,16 @@ interface Bucket<P extends string, Id extends string = string> {
   readonly tenant: string | undefined;
   readonly fileSizeLimit: number | undefined;
   readonly allowedMimeTypes: readonly string[] | undefined;
-  path(values: TemplateValues<P>): StoragePath<Id>;
-  match(path: string): TemplateValues<P> | null;
+  readonly versioning: boolean;
+  readonly lifecycle: BucketLifecycle | undefined;
+  /**
+   * 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. */
@@ -216,6 +298,12 @@ interface Bucket<P extends string, Id extends string = 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: StorageClient): AsyncResult<AppliedBucket>;
   connect(client: StorageClient, options?: BucketConnectOptions): BucketClient<P, Id>;
 }
 interface BucketConnectOptions {
@@ -239,8 +327,6 @@ interface BucketConnectOptions {
   readonly allTenants?: boolean;
 }
 declare function parseSize(value: string | number): number;
-/** Maps a Storage error (`StorageApiError`, fetch failures) to a `DbError`. */
-declare function fromStorageError(raw: unknown, table?: string): DbError;
 /**
  * A typed Storage bucket: path builders from a template, limits, generated
  * SQL policies and `config.toml`, and helpers for the multi-step work apps
@@ -249,7 +335,7 @@ declare function fromStorageError(raw: unknown, table?: string): DbError;
  * ```ts
  * export const logos = defineBucket({
  *   id: 'customer-logos',
- *   path: '{orgId}/{customerId}/logo/{version}.webp',
+ *   path: '{organizationId}/{customerId}/logo/{version}.webp',
  *   policy: 'tenant',
  *   fileSizeLimit: '5MiB',
  *   allowedMimeTypes: ['image/webp'],
@@ -258,47 +344,4 @@ declare function fromStorageError(raw: unknown, table?: string): DbError;
  */
 declare function defineBucket<const P extends string, const Id extends string = string>(config: BucketConfig<P, Id>): Bucket<P, Id>;
 //#endregion
-//#region src/storage/presets.d.ts
-/** The image types browsers display everywhere. */
-declare const IMAGE_TYPES: readonly string[];
-interface ImageBucketOptions<P extends string, Id extends string> {
-  readonly id?: Id;
-  /** The path template; keep the preset's placeholders the policy relies on. */
-  readonly path?: P;
-  /** Defaults to `true`: images load from their public URL without signing. */
-  readonly public?: boolean;
-  readonly fileSizeLimit?: string | number;
-  readonly allowedMimeTypes?: readonly string[];
-  /** Replaces the preset's policy. */
-  readonly policy?: BucketPolicy;
-}
-type AvatarBucketOptions<P extends string, Id extends string> = ImageBucketOptions<P, Id>;
-interface OrgLogoBucketOptions<P extends string, Id extends string> extends ImageBucketOptions<P, Id> {
-  /**
-   * The permission that may upload, replace and delete a logo, checked
-   * through the access contract. Defaults to `organization.update`, the
-   * `organizations` module's update permission.
-   */
-  readonly permission?: string;
-  /**
-   * The tenant segment connected clients are held to. `false` lets one
-   * client upload for any organization the policy allows. Defaults to
-   * `{ param: 'orgId' }`.
-   */
-  readonly tenant?: BucketConfig["tenant"] | false;
-}
-declare const AVATAR_PATH = "{userId}/avatar-{version}.{ext}";
-declare const LOGO_PATH = "{orgId}/logo-{version}.{ext}";
-/**
- * A bucket for profile pictures: `{userId}/avatar-{version}.{ext}`, public,
- * 2 MiB of images, written only by their owner (the `owner` policy).
- */
-declare function avatarBucket<const P extends string = typeof AVATAR_PATH, const Id extends string = "avatars">(options?: AvatarBucketOptions<P, Id>): Bucket<P, Id>;
-/**
- * A bucket for organization logos: `{orgId}/logo-{version}.{ext}`, public,
- * 2 MiB of images, written by members with the update permission through
- * the access contract (`tenant_ids_with`), so it follows the app's roles.
- */
-declare function orgLogoBucket<const P extends string = typeof LOGO_PATH, const Id extends string = "organization-logos">(options?: OrgLogoBucketOptions<P, Id>): Bucket<P, Id>;
-//#endregion
-export { parseSize as A, TransformOptions as C, UrlOptions as D, UploadOptions as E, defineBucket as O, TTL as S, UploadBody as T, Reservation as _, avatarBucket as a, SweepOptions as b, Bucket as c, BucketConnectOptions as d, BucketDrift as f, ReplaceResult as g, ReplaceOptions as h, OrgLogoBucketOptions as i, fromStorageError as k, BucketClient as l, ObjectTarget as m, IMAGE_TYPES as n, orgLogoBucket as o, BucketPolicy as p, ImageBucketOptions as r, ActualBucket as s, AvatarBucketOptions as t, BucketConfig as u, StorageClient as v, TtlPreset as w, SweepResult as x, StoredObject as y };
+export { UrlOptions as C, TTL as D, AppliedBucket as E, TtlPreset as O, UploadOptions as S, parseSize as T, SweepOptions as _, BucketConnectOptions as a, TransformOptions as b, DownloadOptions as c, PurgeCacheOptions as d, ReplaceOptions as f, StoredObject as g, StorageClient as h, BucketConfig as i, ObjectTarget as l, Reservation as m, Bucket as n, BucketDrift as o, ReplaceResult as p, BucketClient as r, BucketPolicy as s, ActualBucket as t, PathValues as u, SweepResult as v, defineBucket as w, UploadBody as x, TransferOptions as y };