@aws-blocks/bb-file-bucket 0.1.0

package/dist/index.aws.js

@@ -0,0 +1,183 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, ListObjectsV2Command, ListObjectVersionsCommand, CopyObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
+import { Logger } from '@aws-blocks/bb-logger';
+// Re-export public types
+export { FileBucketErrors } from './errors.js';
+/**
+ * File storage backed by Amazon S3.
+ *
+ * **When to use:** You need to store, retrieve, or serve binary files —
+ * user uploads, generated reports, images, videos, or static assets.
+ *
+ * **When NOT to use:** If you need structured key-value data with conditional
+ * writes, use `KVStore`. If you need queryable records with indexes, use
+ * `DistributedTable`.
+ *
+ * **Best practices:**
+ * - Use path prefixes to organize files (e.g., `uploads/{userId}/`, `reports/`)
+ * - Set `contentType` on `put()` to ensure correct MIME handling on download
+ * - Use `getFileHandle` / `createUploadHandle` for ergonomic browser file transfers
+ * - Use presigned URLs (`getUrl` / `putUrl`) when you need direct URL control
+ * - Prefer `scan({ prefix })` over unscoped `scan()` to limit enumeration cost
+ *
+ * **Scaling:** S3 scales automatically. No provisioned throughput. Costs are
+ * per-request plus storage. Individual objects up to 5 TB. For objects larger
+ * than ~100 MB, consider multipart upload.
+ */
+export class FileBucket extends Scope {
+    bbName = BB_NAME;
+    s3;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    constructor(scope, id, options) {
+        super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+        this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+        this.registerClientMiddleware('@aws-blocks/bb-file-bucket/middleware');
+        const bucketName = options?.bucket ? options.bucket.bucketName : this.fullId;
+        registerSdkIdentifiers(this.fullId, { bucketName });
+        this.s3 = new S3Client({
+            customUserAgent: this.buildUserAgentChain(),
+        });
+    }
+    async put(path, body, options) {
+        await this.s3.send(new PutObjectCommand({
+            Bucket: getSdkIdentifiers(this).bucketName,
+            Key: path,
+            Body: typeof body === 'string' ? Buffer.from(body) : body,
+            ContentType: options?.contentType,
+            Metadata: options?.metadata,
+            CacheControl: options?.cacheControl,
+        }));
+    }
+    async get(path, options) {
+        try {
+            const result = await this.s3.send(new GetObjectCommand({
+                Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+                ...(options ? { VersionId: options.versionId } : {}),
+            }));
+            const bytes = await result.Body.transformToByteArray();
+            return {
+                body: Buffer.from(bytes),
+                contentType: result.ContentType ?? 'application/octet-stream',
+                metadata: result.Metadata ?? {},
+                size: result.ContentLength ?? bytes.length,
+            };
+        }
+        catch (e) {
+            if (e.name === 'NoSuchKey')
+                return null;
+            throw e;
+        }
+    }
+    async delete(path, options) {
+        await this.s3.send(new DeleteObjectCommand({
+            Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+            ...(options ? { VersionId: options.versionId } : {}),
+        }));
+    }
+    async deleteBatch(paths) {
+        const CHUNK_SIZE = 1000;
+        for (let i = 0; i < paths.length; i += CHUNK_SIZE) {
+            const chunk = paths.slice(i, i + CHUNK_SIZE);
+            await this.s3.send(new DeleteObjectsCommand({
+                Bucket: getSdkIdentifiers(this).bucketName,
+                Delete: { Objects: chunk.map(Key => ({ Key })), Quiet: true },
+            }));
+        }
+    }
+    async getUrl(path, options) {
+        const opts = options;
+        return getSignedUrl(this.s3, new GetObjectCommand({
+            Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+            ...(opts?.versionId ? { VersionId: opts.versionId } : {}),
+        }), {
+            expiresIn: opts?.expiresIn ?? 3600,
+        });
+    }
+    async putUrl(path, options) {
+        return getSignedUrl(this.s3, new PutObjectCommand({
+            Bucket: getSdkIdentifiers(this).bucketName, Key: path, ContentType: options?.contentType,
+        }), { expiresIn: options?.expiresIn ?? 3600 });
+    }
+    async getFileHandle(path, options) {
+        const url = await this.getUrl(path, options);
+        return {
+            download: async () => {
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`Download failed: ${res.status}`);
+                return res.blob();
+            },
+            getUrl: () => url,
+            toJSON: () => ({ __blocks: 'file-bucket/download', url }),
+        };
+    }
+    async createUploadHandle(path, options) {
+        const url = await this.putUrl(path, options);
+        const contentType = options?.contentType;
+        return {
+            upload: async (body) => {
+                const headers = {};
+                if (contentType)
+                    headers['Content-Type'] = contentType;
+                const res = await fetch(url, { method: 'PUT', body, headers });
+                if (!res.ok)
+                    throw new Error(`Upload failed: ${res.status}`);
+            },
+            getUrl: () => url,
+            toJSON: () => ({ __blocks: 'file-bucket/upload', url, contentType }),
+        };
+    }
+    async *scan(options) {
+        let continuationToken;
+        do {
+            const result = await this.s3.send(new ListObjectsV2Command({
+                Bucket: getSdkIdentifiers(this).bucketName, Prefix: options?.prefix, ContinuationToken: continuationToken,
+            }));
+            for (const obj of result.Contents ?? []) {
+                yield { path: obj.Key, size: obj.Size ?? 0, lastModified: obj.LastModified ?? new Date() };
+            }
+            continuationToken = result.NextContinuationToken;
+        } while (continuationToken);
+    }
+    async listVersions(path) {
+        const versions = [];
+        let keyMarker;
+        let versionIdMarker;
+        do {
+            const result = await this.s3.send(new ListObjectVersionsCommand({
+                Bucket: getSdkIdentifiers(this).bucketName, Prefix: path, KeyMarker: keyMarker, VersionIdMarker: versionIdMarker,
+            }));
+            for (const v of result.Versions ?? []) {
+                if (v.Key !== path)
+                    continue; // prefix match may include other keys
+                versions.push({
+                    versionId: v.VersionId,
+                    lastModified: v.LastModified ?? new Date(),
+                    size: v.Size ?? 0,
+                    isCurrent: v.IsLatest ?? false,
+                });
+            }
+            keyMarker = result.NextKeyMarker;
+            versionIdMarker = result.NextVersionIdMarker;
+        } while (keyMarker);
+        // Newest first
+        versions.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+        return versions;
+    }
+    async restoreVersion(path, versionId) {
+        const encodedPath = path.split('/').map(s => encodeURIComponent(s)).join('/');
+        await this.s3.send(new CopyObjectCommand({
+            Bucket: getSdkIdentifiers(this).bucketName,
+            Key: path,
+            CopySource: `${getSdkIdentifiers(this).bucketName}/${path}?versionId=${versionId}`,
+        }));
+    }
+    static fromExisting(bucketName) {
+        return { __brand: 'ExternalBucketRef', bucketName };
+    }
+}

package/dist/index.browser.d.ts

@@ -0,0 +1,4 @@
+export declare class FileBucket {
+    constructor(...args: any[]);
+}
+//# sourceMappingURL=index.browser.d.ts.map

package/dist/index.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAIA,qBAAa,UAAU;gBACT,GAAG,IAAI,EAAE,GAAG,EAAE;CAC3B"}

package/dist/index.browser.js

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Browser stub - FileBucket runs server-side only
+export class FileBucket {
+    constructor(...args) { }
+}

package/dist/index.cdk.d.ts

@@ -0,0 +1,16 @@
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { FileBucketOptions, ExternalBucketRef } from './types.js';
+export { FileBucketErrors } from './errors.js';
+export type { FileBucketOptions, PutOptions, GetUrlOptions, PutUrlOptions, ScanOptions, FileContent, FileInfo, CorsRule, LifecycleRule, ExternalBucketRef } from './types.js';
+export declare class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends Scope {
+    private bucket;
+    /**
+     * Reference an existing S3 bucket instead of provisioning a new one.
+     * Mirrors the same factory exposed by the runtime build so the same code
+     * works in both contexts.
+     */
+    static fromExisting(bucketName: string): ExternalBucketRef;
+    constructor(scope: ScopeParent, id: string, options?: O);
+}
+//# sourceMappingURL=index.cdk.d.ts.map

package/dist/index.cdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAA2B,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGhG,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAU9K,qBAAa,UAAU,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,CAAE,SAAQ,KAAK;IACrF,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;gBAI9C,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAsDvD"}

package/dist/index.cdk.js

@@ -0,0 +1,75 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cdk from 'aws-cdk-lib';
+import { Duration, RemovalPolicy } from 'aws-cdk-lib';
+import { Scope } from '@aws-blocks/core/cdk';
+import { validateBucketName } from './bucket-name.js';
+export { FileBucketErrors } from './errors.js';
+const httpMethodMap = {
+    GET: s3.HttpMethods.GET,
+    PUT: s3.HttpMethods.PUT,
+    POST: s3.HttpMethods.POST,
+    DELETE: s3.HttpMethods.DELETE,
+    HEAD: s3.HttpMethods.HEAD,
+};
+export class FileBucket extends Scope {
+    bucket;
+    /**
+     * Reference an existing S3 bucket instead of provisioning a new one.
+     * Mirrors the same factory exposed by the runtime build so the same code
+     * works in both contexts.
+     */
+    static fromExisting(bucketName) {
+        return { __brand: 'ExternalBucketRef', bucketName };
+    }
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        if (options?.bucket) {
+            // `fromExisting`: don't provision; bind to the pre-existing bucket and
+            // grant read/write to the Blocks runtime Lambda.
+            this.bucket = s3.Bucket.fromBucketName(this, 'bucket', options.bucket.bucketName);
+            this.bucket.grantReadWrite(this.handler);
+            return;
+        }
+        // In sandbox mode, default to DESTROY + autoDeleteObjects so
+        // `cdk destroy` can fully clean up without manual bucket emptying.
+        // Explicit `removalPolicy` from the customer takes precedence.
+        // `autoDeleteObjects: true` is only valid paired with DESTROY (CDK
+        // validates this at construct time), so we tie the two together.
+        const isSandbox = cdk.Stack.of(this).node.tryGetContext('sandboxMode') === 'true';
+        const destroy = options?.removalPolicy === 'destroy' || (isSandbox && options?.removalPolicy === undefined);
+        // Bucket name is derived from the scope chain. Validate against S3's
+        // naming rules at synth so an invalid name fails here rather than at
+        // `cdk deploy` (where CloudFormation rejects it with a cryptic error).
+        validateBucketName(this.fullId);
+        this.bucket = new s3.Bucket(this, 'bucket', {
+            bucketName: this.fullId,
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            encryption: s3.BucketEncryption.S3_MANAGED,
+            versioned: options?.versioned ?? false,
+            removalPolicy: destroy
+                ? RemovalPolicy.DESTROY
+                : options?.removalPolicy === 'retain'
+                    ? RemovalPolicy.RETAIN
+                    : undefined,
+            autoDeleteObjects: destroy,
+            cors: options?.corsRules?.map((rule) => ({
+                allowedOrigins: rule.allowedOrigins,
+                allowedMethods: rule.allowedMethods.map(m => httpMethodMap[m]),
+                allowedHeaders: rule.allowedHeaders,
+                exposedHeaders: rule.exposedHeaders,
+                maxAge: rule.maxAge,
+            })),
+            lifecycleRules: options?.lifecycleRules?.map((rule) => ({
+                prefix: rule.prefix,
+                expiration: rule.expirationDays ? Duration.days(rule.expirationDays) : undefined,
+                transitions: rule.transitionToIaDays ? [{
+                        storageClass: s3.StorageClass.INFREQUENT_ACCESS,
+                        transitionAfter: Duration.days(rule.transitionToIaDays),
+                    }] : undefined,
+            })),
+        });
+        this.bucket.grantReadWrite(this.handler);
+    }
+}

package/dist/index.cdk.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.cdk.test.d.ts.map

package/dist/index.cdk.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.test.d.ts","sourceRoot":"","sources":["../src/index.cdk.test.ts"],"names":[],"mappings":""}

package/dist/index.cdk.test.js

@@ -0,0 +1,69 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK-side regression tests for FileBucket.
+ *
+ * History: FileBucket.fromExisting was advertised in types but the CDK
+ * constructor unconditionally provisioned a new S3 bucket. These tests pin
+ * the fix.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { FileBucket } from './index.cdk.js';
+class StubBlocksStack extends cdk.Stack {
+    handler;
+    id;
+    constructor(scope, id) {
+        super(scope, id);
+        this.id = id;
+        globalThis.CURRENT_BLOCKS_STACK = this;
+        this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
+            runtime: DEFAULT_NODE_RUNTIME,
+            handler: 'index.handler',
+            code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+        });
+    }
+}
+function setup() {
+    const app = new cdk.App();
+    // S3 bucket names must be lowercase. The default-mode FileBucket derives
+    // its bucket name from the scope chain, so keep ids lowercase.
+    const stack = new StubBlocksStack(app, 'teststack');
+    const parent = new Scope('app');
+    return { stack, parent };
+}
+test('CDK: default FileBucket provisions an S3 bucket', () => {
+    const { stack, parent } = setup();
+    new FileBucket(parent, 'uploads');
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::S3::Bucket', 1);
+});
+test('CDK: FileBucket.fromExisting does NOT provision a bucket (regression)', () => {
+    const { stack, parent } = setup();
+    new FileBucket(parent, 'uploads', {
+        bucket: FileBucket.fromExisting('preexisting-bucket-123'),
+    });
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::S3::Bucket', 0);
+});
+test('CDK: FileBucket.fromExisting returns a branded ref', () => {
+    const ref = FileBucket.fromExisting('foo');
+    assert.strictEqual(ref.bucketName, 'foo');
+    assert.strictEqual(ref.__brand, 'ExternalBucketRef');
+});
+test('CDK: default FileBucket with an over-long derived name throws at synth', () => {
+    const { parent } = setup();
+    // parent id "app" + "-" + a 60-char id => 64 chars, over the S3 limit.
+    assert.throws(() => new FileBucket(parent, 'u'.repeat(60)), (err) => err instanceof Error &&
+        err.name === 'ValidationFailed' &&
+        /63-character limit/.test(err.message));
+});
+test('CDK: fromExisting skips derived-name validation even when the chain is over-long', () => {
+    const { parent } = setup();
+    assert.doesNotThrow(() => new FileBucket(parent, 'u'.repeat(60), {
+        bucket: FileBucket.fromExisting('preexisting-bucket-123'),
+    }));
+});

package/dist/index.mock.d.ts

@@ -0,0 +1,246 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { FileBucketOptions, PutOptions, PutUrlOptions, ScanOptions, FileContent, FileInfo, ExternalBucketRef, FileDownloadClient, FileUploadClient, FileVersionInfo, GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor } from './types.js';
+export type { FileBucketOptions, PutOptions, GetUrlOptions, PutUrlOptions, ScanOptions, FileContent, FileInfo, CorsRule, LifecycleRule, ExternalBucketRef, FileDownloadClient, FileUploadClient, FileVersionInfo, FileDownloadDescriptor, FileUploadDescriptor, VersionedGetOptions, VersionedDeleteOptions, VersionedGetUrlOptions, GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor, } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export { FileBucketErrors } from './errors.js';
+/**
+ * File storage backed by Amazon S3.
+ *
+ * **When to use:** You need to store, retrieve, or serve binary files —
+ * user uploads, generated reports, images, videos, or static assets.
+ *
+ * **When NOT to use:** If you need structured key-value data with conditional
+ * writes, use `KVStore`. If you need queryable records with indexes, use
+ * `DistributedTable`.
+ *
+ * **Best practices:**
+ * - Use path prefixes to organize files (e.g., `uploads/{userId}/`, `reports/`)
+ * - Set `contentType` on `put()` to ensure correct MIME handling on download
+ * - Use presigned URLs (`getUrl` / `putUrl`) for direct browser upload/download
+ * - Use `getFileHandle` / `createUploadHandle` for ergonomic browser file transfers
+ * - Prefer `scan({ prefix })` over unscoped `scan()` to limit enumeration cost
+ *
+ * **Scaling:** S3 scales automatically. No provisioned throughput. Costs are
+ * per-request plus storage. Individual objects up to 5 TB. For objects larger
+ * than ~100 MB, consider multipart upload.
+ */
+export declare class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends Scope {
+    private dataDir;
+    private versioned;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options?: O);
+    /**
+     * Upload a file.
+     *
+     * Overwrites any existing file at the given path.
+     *
+     * @param path - The object key (e.g., `uploads/photo.jpg`).
+     * @param body - The file content.
+     * @param options - Optional metadata and content settings.
+     *
+     * @example
+     * ```typescript
+     * await bucket.put('reports/q1.pdf', pdfBuffer, {
+     *   contentType: 'application/pdf',
+     * });
+     * ```
+     */
+    put(path: string, body: Buffer | string, options?: PutOptions): Promise<void>;
+    /**
+     * Download a file.
+     *
+     * @param path - The object key.
+     * @param options - Optional. On versioned buckets, pass `{ versionId }` to retrieve a specific version.
+     * @returns The file content and metadata, or null if the file does not exist.
+     *
+     * @example
+     * ```typescript
+     * const file = await bucket.get('reports/q1.pdf');
+     * if (file) {
+     *   console.log(file.contentType); // 'application/pdf'
+     * }
+     * ```
+     */
+    get(path: string, options?: GetOptionsFor<O>): Promise<FileContent | null>;
+    /**
+     * Delete a file.
+     *
+     * On non-versioned buckets, permanently removes the file.
+     * On versioned buckets without `versionId`, places a delete marker (file appears deleted
+     * but previous versions are preserved). With `versionId`, permanently removes that version.
+     *
+     * No-op if the file does not exist (matches S3 behavior).
+     *
+     * @param path - The object key.
+     * @param options - Optional. On versioned buckets, pass `{ versionId }` to permanently delete a specific version.
+     *
+     * @example
+     * ```typescript
+     * await bucket.delete('uploads/old-photo.jpg');
+     * ```
+     */
+    delete(path: string, options?: DeleteOptionsFor<O>): Promise<void>;
+    /**
+     * Delete multiple files in a single operation.
+     *
+     * Uses S3 DeleteObjects for efficient bulk deletion (up to 1,000 keys
+     * per request). Chunking is handled internally.
+     *
+     * @param paths - The object keys to delete.
+     *
+     * @example
+     * ```typescript
+     * await bucket.deleteBatch(['tmp/a.txt', 'tmp/b.txt', 'tmp/c.txt']);
+     * ```
+     */
+    deleteBatch(paths: string[]): Promise<void>;
+    /**
+     * Generate a presigned URL for downloading a file.
+     *
+     * @param path - The object key.
+     * @param options - URL generation options.
+     * @returns A presigned URL string.
+     *
+     * @example
+     * ```typescript
+     * const url = await bucket.getUrl('reports/q1.pdf', { expiresIn: 3600 });
+     * ```
+     */
+    getUrl(path: string, options?: GetUrlOptionsFor<O>): Promise<string>;
+    /**
+     * Generate a presigned URL for uploading a file.
+     *
+     * @param path - The object key.
+     * @param options - URL generation options.
+     * @returns A presigned URL string.
+     *
+     * @example
+     * ```typescript
+     * const url = await bucket.putUrl('uploads/photo.jpg', {
+     *   expiresIn: 600,
+     *   contentType: 'image/jpeg',
+     * });
+     * ```
+     */
+    putUrl(path: string, options?: PutUrlOptions): Promise<string>;
+    /**
+     * Get a file handle for browser-side download.
+     *
+     * Returns a Transferable descriptor that the client middleware hydrates
+     * into an object with `.download()` and `.getUrl()` methods. Use this
+     * instead of `getUrl()` when you want the client to download files
+     * without manually managing presigned URLs.
+     *
+     * @param path - The object key.
+     * @param options - URL generation options.
+     * @returns A Transferable file download handle.
+     *
+     * @example
+     * ```typescript
+     * // Backend
+     * async getReport(name: string) {
+     *   return bucket.getFileHandle('reports/' + name);
+     * }
+     *
+     * // Frontend
+     * const file = await api.getReport('q1.pdf');
+     * const blob = await file.download();
+     * ```
+     */
+    getFileHandle(path: string, options?: GetUrlOptionsFor<O>): Promise<FileDownloadClient>;
+    /**
+     * Create an upload handle for browser-side file upload.
+     *
+     * Returns a Transferable descriptor that the client middleware hydrates
+     * into an object with `.upload(body)` and `.getUrl()` methods. Use this
+     * instead of `putUrl()` when you want the client to upload files
+     * without manually managing presigned URLs.
+     *
+     * @param path - The object key.
+     * @param options - URL generation options.
+     * @returns A Transferable file upload handle.
+     *
+     * @example
+     * ```typescript
+     * // Backend
+     * async getUploadSlot(name: string) {
+     *   return bucket.createUploadHandle('uploads/' + name, {
+     *     contentType: 'image/jpeg',
+     *   });
+     * }
+     *
+     * // Frontend
+     * const slot = await api.getUploadSlot('photo.jpg');
+     * await slot.upload(fileBlob);
+     * ```
+     */
+    createUploadHandle(path: string, options?: PutUrlOptions): Promise<FileUploadClient>;
+    /**
+     * List files in the bucket.
+     *
+     * Returns an `AsyncIterable` that paginates internally. Use `prefix`
+     * to scope the listing. Without a prefix, enumerates all files —
+     * this is expensive on large buckets.
+     *
+     * @param options - Listing options.
+     * @returns An async iterable of file info objects.
+     *
+     * @example
+     * ```typescript
+     * for await (const file of bucket.scan({ prefix: 'uploads/' })) {
+     *   console.log(file.path, file.size);
+     * }
+     * ```
+     */
+    scan(options?: ScanOptions): AsyncIterable<FileInfo>;
+    /**
+     * List all versions of a file. Only available on versioned buckets.
+     *
+     * Returns versions newest-first. Includes the current version and all
+     * previous versions. Does not include delete markers.
+     *
+     * @param path - The object key.
+     * @returns An array of version metadata, newest first.
+     *
+     * @example
+     * ```typescript
+     * const versions = await bucket.listVersions('report.pdf');
+     * for (const v of versions) {
+     *   console.log(v.versionId, v.lastModified, v.isCurrent);
+     * }
+     * ```
+     */
+    listVersions(path: string): Promise<FileVersionInfo[]>;
+    /**
+     * Restore a previous version of a file, making it the current version.
+     *
+     * Creates a new version that is a copy of the specified old version.
+     * On S3, this is implemented as a CopyObject from the old version to the same key.
+     *
+     * @param path - The object key.
+     * @param versionId - The version to restore.
+     *
+     * @example
+     * ```typescript
+     * const versions = await bucket.listVersions('report.pdf');
+     * await bucket.restoreVersion('report.pdf', versions[1].versionId);
+     * ```
+     */
+    restoreVersion(path: string, versionId: string): Promise<void>;
+    /**
+     * Create a reference to an existing S3 bucket not managed by this scope.
+     *
+     * @param bucketName - The name of the existing S3 bucket.
+     */
+    static fromExisting(bucketName: string): ExternalBucketRef;
+    private validateKey;
+    private writeMeta;
+    private readMeta;
+    private readVersionMeta;
+    private readMetaFile;
+    private walkDir;
+    private nextVersionId;
+}
+//# sourceMappingURL=index.mock.d.ts.map

package/dist/index.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"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"}