@velajs/storage 0.3.1 → 0.3.2

package/dist/storage.controller.d.ts

@@ -1,21 +0,0 @@
-import { type Token, type Type } from '@velajs/vela';
-import type { StorageService } from './storage.service';
-import type { StorageAuthorizer } from './http/authorizer.types';
-export interface ResolvedHttpOptions {
-    driverName: string;
-    authorize?: StorageAuthorizer;
-    defaultPolicy: 'deny' | 'allow';
-    download: 'redirect' | 'proxy';
-    defaultExpiresIn: number;
-    maxExpiresIn: number;
-    maxUploadSize?: number;
-    maxListLimit: number;
-    deleteConcurrency: number;
-}
-/**
- * Build a vela controller exposing presigned/multipart upload + download
- * endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
- * so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
- * facade so gating/retry/prefix apply uniformly on the HTTP path.
- */
-export declare function createStorageController(basePath: string, serviceToken: Token<StorageService>, http: ResolvedHttpOptions): Type;

package/dist/storage.controller.js

@@ -1,386 +0,0 @@
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-function _ts_param(paramIndex, decorator) {
-    return function(target, key) {
-        decorator(target, key, paramIndex);
-    };
-}
-import { Controller, Get, Inject, Injectable, Post, Req } from "@velajs/vela";
-import { sanitizeKey } from "./object-key.js";
-import { StorageError } from "./storage.error.js";
-import { clampExpiry, dispositionHeader, mapError, parseRange, serializeStored } from "./http/http-helpers.js";
-/**
- * Build a vela controller exposing presigned/multipart upload + download
- * endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
- * so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
- * facade so gating/retry/prefix apply uniformly on the HTTP path.
- */ export function createStorageController(basePath, serviceToken, http) {
-    let StorageController = class StorageController {
-        svc;
-        constructor(svc){
-            this.svc = svc;
-        }
-        get storage() {
-            return this.svc.storage;
-        }
-        async authorize(c, action) {
-            if (!http.authorize) {
-                if (http.defaultPolicy === 'allow') return {};
-                throw new StorageError('AccessDenied', 'storage: no authorizer configured (default deny)');
-            }
-            const res = await http.authorize(action, {
-                req: c.req.raw,
-                ctx: c,
-                driver: http.driverName
-            });
-            if (res === false) throw new StorageError('AccessDenied', 'not allowed');
-            if (res === true) return {};
-            return res;
-        }
-        fail(c, e) {
-            const err = e instanceof StorageError ? e : StorageError.wrap(e);
-            const { wire, status } = mapError(err.code);
-            // Never echo a provider/transport/wrapped message to the client: those are
-            // flagged `internal` (driver <Message>/<Code>, StorageError.wrap, fromStatus)
-            // and can carry host/bucket/credential detail — including on a 4xx status.
-            // Redact internal errors at any status, plus all upstream (5xx) responses;
-            // 4xx codes with an author-vouched message echo it.
-            const message = err.internal || status >= 500 ? 'storage backend error' : err.message;
-            return c.json({
-                error: {
-                    code: wire,
-                    message
-                }
-            }, status);
-        }
-        async signUpload(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'sign-upload',
-                    key: b.key,
-                    contentType: b.contentType,
-                    size: b.size
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const upload = await this.storage.signedUploadUrl(key, {
-                    expiresIn: clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
-                    contentType: b.contentType,
-                    maxSize: ov.maxSize ?? http.maxUploadSize
-                });
-                return c.json({
-                    key,
-                    upload
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async multipartCreate(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'multipart-create',
-                    key: b.key,
-                    contentType: b.contentType
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const sm = this.storage.signedMultipart;
-                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
-                const created = await sm.create(key, {
-                    contentType: b.contentType,
-                    metadata: ov.metadata ?? b.metadata,
-                    partSize: b.partSize
-                });
-                return c.json({
-                    key,
-                    uploadId: created.uploadId,
-                    partSize: created.partSize
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async multipartSignPart(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'multipart-sign-part',
-                    key: b.key,
-                    uploadId: b.uploadId,
-                    partNumber: b.partNumber
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const sm = this.storage.signedMultipart;
-                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
-                const part = await sm.signPart(key, b.uploadId, b.partNumber, {
-                    expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn)
-                });
-                return c.json({
-                    partNumber: b.partNumber,
-                    method: 'PUT',
-                    url: part.url,
-                    headers: part.headers
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async multipartComplete(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'multipart-complete',
-                    key: b.key,
-                    uploadId: b.uploadId
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const sm = this.storage.signedMultipart;
-                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
-                return c.json(await sm.complete(key, b.uploadId, b.parts));
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async multipartAbort(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'multipart-abort',
-                    key: b.key,
-                    uploadId: b.uploadId
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const sm = this.storage.signedMultipart;
-                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
-                await sm.abort(key, b.uploadId);
-                return c.json({
-                    ok: true
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async list(c) {
-            try {
-                const prefix = c.req.query('prefix');
-                const ov = await this.authorize(c, {
-                    type: 'list',
-                    prefix
-                });
-                const limit = c.req.query('limit');
-                const res = await this.storage.list({
-                    prefix: ov.prefix ?? prefix,
-                    cursor: c.req.query('cursor'),
-                    delimiter: c.req.query('delimiter'),
-                    limit: limit ? Math.min(Number(limit), http.maxListLimit) : undefined
-                });
-                return c.json({
-                    items: res.items.map(serializeStored),
-                    prefixes: res.prefixes,
-                    cursor: res.cursor
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async head(c) {
-            try {
-                const key = sanitizeKey(c.req.query('key') ?? '');
-                const ov = await this.authorize(c, {
-                    type: 'head',
-                    key
-                });
-                const file = await this.storage.head(sanitizeKey(ov.key ?? key));
-                return c.json(serializeStored(file));
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async delete(c) {
-            try {
-                const b = await c.req.json();
-                const keys = b.keys.map((k)=>sanitizeKey(k));
-                const ov = await this.authorize(c, {
-                    type: 'delete',
-                    keys
-                });
-                const effective = (ov.keys ?? keys).map((k)=>sanitizeKey(k));
-                return c.json(await this.storage.delete(effective, {
-                    concurrency: http.deleteConcurrency
-                }));
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async download(c) {
-            try {
-                const key = sanitizeKey(c.req.query('key') ?? '');
-                const disp = c.req.query('disposition');
-                const ov = await this.authorize(c, {
-                    type: 'download',
-                    key
-                });
-                const ekey = sanitizeKey(ov.key ?? key);
-                const name = ekey.slice(ekey.lastIndexOf('/') + 1);
-                if (http.download === 'redirect' && this.storage.capabilities.signedUrl.supported) {
-                    const url = await this.storage.url(ekey, {
-                        expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
-                        responseContentDisposition: dispositionHeader(disp, name)
-                    });
-                    return c.redirect(url, 302);
-                }
-                const range = parseRange(c.req.header('range'));
-                const file = await this.storage.download(ekey, range ? {
-                    range
-                } : undefined);
-                const headers = new Headers({
-                    'content-type': file.type,
-                    'content-length': String(file.size),
-                    'content-disposition': dispositionHeader(disp, file.name)
-                });
-                if (file.etag) headers.set('etag', file.etag);
-                if (range) {
-                    headers.set('content-range', `bytes ${range.start}-${range.start + file.size - 1}/*`);
-                    return new Response(file.stream(), {
-                        status: 206,
-                        headers
-                    });
-                }
-                return new Response(file.stream(), {
-                    status: 200,
-                    headers
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-        async signDownload(c) {
-            try {
-                const b = await c.req.json();
-                const ov = await this.authorize(c, {
-                    type: 'download',
-                    key: b.key
-                });
-                const key = sanitizeKey(ov.key ?? b.key);
-                const expiresIn = clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn);
-                const url = await this.storage.url(key, {
-                    expiresIn
-                });
-                return c.json({
-                    url,
-                    expiresAt: Date.now() + expiresIn * 1000
-                });
-            } catch (e) {
-                return this.fail(c, e);
-            }
-        }
-    };
-    _ts_decorate([
-        Post('/sign-upload'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "signUpload", null);
-    _ts_decorate([
-        Post('/multipart/create'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "multipartCreate", null);
-    _ts_decorate([
-        Post('/multipart/sign-part'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "multipartSignPart", null);
-    _ts_decorate([
-        Post('/multipart/complete'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "multipartComplete", null);
-    _ts_decorate([
-        Post('/multipart/abort'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "multipartAbort", null);
-    _ts_decorate([
-        Get('/list'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "list", null);
-    _ts_decorate([
-        Get('/head'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "head", null);
-    _ts_decorate([
-        Post('/delete'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "delete", null);
-    _ts_decorate([
-        Get('/download'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "download", null);
-    _ts_decorate([
-        Post('/sign-download'),
-        _ts_param(0, Req()),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof Context === "undefined" ? Object : Context
-        ]),
-        _ts_metadata("design:returntype", Promise)
-    ], StorageController.prototype, "signDownload", null);
-    StorageController = _ts_decorate([
-        Controller(basePath),
-        Injectable(),
-        _ts_param(0, Inject(serviceToken)),
-        _ts_metadata("design:type", Function),
-        _ts_metadata("design:paramtypes", [
-            typeof StorageService === "undefined" ? Object : StorageService
-        ])
-    ], StorageController);
-    return StorageController;
-}

package/dist/storage.error.d.ts

@@ -1,38 +0,0 @@
-/**
- * The single error taxonomy for `@velajs/storage`. Every driver maps its
- * provider/transport failures onto a {@link StorageErrorCode}; the facade's
- * capability gates throw `Unsupported`; the retry loop keys off
- * {@link StorageError.retryable}; and the HTTP controller maps codes to
- * status via its own `codeToHttp()` table.
- */
-export type StorageErrorCode = 'NotFound' | 'AccessDenied' | 'Unsupported' | 'ReadOnly' | 'InvalidKey' | 'InvalidRequest' | 'Conflict' | 'RateLimited' | 'Network' | 'Timeout' | 'Aborted' | 'Provider' | 'Parse';
-export interface StorageErrorOptions {
-    cause?: unknown;
-    /** Underlying HTTP status, when the failure came from a transport response. */
-    status?: number;
-    /** Override the default retryability implied by {@link StorageErrorCode}. */
-    retryable?: boolean;
-    /**
-     * True when `message` came from a provider/transport/wrapped source rather
-     * than being authored as client-safe text. The HTTP controller redacts such
-     * messages so raw provider detail never reaches a client. Default false —
-     * a bare `new StorageError(code, msg)` is the author's vouch that `msg` is
-     * client-safe; driver/wrap code MUST set this when echoing provider text.
-     */
-    internal?: boolean;
-}
-export declare class StorageError extends Error {
-    name: string;
-    readonly code: StorageErrorCode;
-    readonly retryable: boolean;
-    readonly status: number | undefined;
-    /** Whether `message` is non-client-safe (provider/transport/wrapped origin). */
-    readonly internal: boolean;
-    constructor(code: StorageErrorCode, message: string, options?: StorageErrorOptions);
-    /** Wrap an arbitrary thrown value as a `StorageError` (idempotent). */
-    static wrap(e: unknown): StorageError;
-    /** Map a transport status code to a `StorageError` (5xx/429 retryable). */
-    static fromStatus(status: number, message: string, cause?: unknown): StorageError;
-}
-/** True for `AbortError`-shaped values (DOMException or `{ name: 'AbortError' }`). */
-export declare function isAbort(e: unknown): boolean;

package/dist/storage.error.js

@@ -1,52 +0,0 @@
-/**
- * The single error taxonomy for `@velajs/storage`. Every driver maps its
- * provider/transport failures onto a {@link StorageErrorCode}; the facade's
- * capability gates throw `Unsupported`; the retry loop keys off
- * {@link StorageError.retryable}; and the HTTP controller maps codes to
- * status via its own `codeToHttp()` table.
- */ /** Codes that are safe to retry by default (transient failures). */ const RETRYABLE = new Set([
-    'Network',
-    'RateLimited',
-    'Timeout',
-    'Provider'
-]);
-export class StorageError extends Error {
-    name = 'StorageError';
-    code;
-    retryable;
-    status;
-    /** Whether `message` is non-client-safe (provider/transport/wrapped origin). */ internal;
-    constructor(code, message, options){
-        super(message, options?.cause !== undefined ? {
-            cause: options.cause
-        } : undefined);
-        this.code = code;
-        this.status = options?.status;
-        this.retryable = options?.retryable ?? RETRYABLE.has(code);
-        this.internal = options?.internal ?? false;
-    }
-    /** Wrap an arbitrary thrown value as a `StorageError` (idempotent). */ static wrap(e) {
-        if (e instanceof StorageError) return e;
-        if (isAbort(e)) return new StorageError('Aborted', 'operation aborted', {
-            cause: e
-        });
-        // The wrapped message is arbitrary provider/host text — never client-safe.
-        return new StorageError('Provider', e instanceof Error ? e.message : String(e), {
-            cause: e,
-            internal: true
-        });
-    }
-    /** Map a transport status code to a `StorageError` (5xx/429 retryable). */ static fromStatus(status, message, cause) {
-        const code = status === 404 ? 'NotFound' : status === 403 || status === 401 ? 'AccessDenied' : status === 409 ? 'Conflict' : status === 429 ? 'RateLimited' : status >= 500 ? 'Provider' : 'InvalidRequest';
-        return new StorageError(code, message, {
-            status,
-            cause,
-            retryable: status === 429 || status >= 500,
-            // Message came off a transport response — treat as non-client-safe.
-            internal: true
-        });
-    }
-}
-/** True for `AbortError`-shaped values (DOMException or `{ name: 'AbortError' }`). */ export function isAbort(e) {
-    return typeof e === 'object' && e !== null && 'name' in e && e.name === 'AbortError';
-}

package/dist/storage.facade.d.ts

@@ -1,47 +0,0 @@
-import type { Body, CreateMultipartOptions, DeleteManyOptions, DeleteManyResult, DownloadOptions, ListOptions, ListResult, MultipartUpload, OperationOptions, SignedMultipartCapability, SignedUpload, SignUploadOptions, StorageCapabilities, StorageDriver, StorageOptions, StoredFile, UploadOptions, UploadResult, UrlOptions } from './storage.types';
-/**
- * The consumer-facing storage handle. Wraps a {@link StorageDriver} with
- * capability-gating (throws before any driver call), retry/timeout/abort,
- * prefix scoping, generic `move`/`deleteMany` fallbacks, multipart
- * orchestration, progress synthesis, and observability hooks.
- *
- * Framework-free — `StorageService` builds and caches one of these per bucket.
- */
-export declare class Storage {
-    #private;
-    constructor(opts: StorageOptions);
-    get raw(): unknown;
-    get driver(): StorageDriver;
-    get capabilities(): StorageCapabilities;
-    upload(key: string, body: Body, opts?: UploadOptions): Promise<UploadResult>;
-    download(key: string, opts?: DownloadOptions): Promise<StoredFile>;
-    head(key: string, opts?: OperationOptions): Promise<StoredFile>;
-    exists(key: string, opts?: OperationOptions): Promise<boolean>;
-    delete(key: string, opts?: OperationOptions): Promise<void>;
-    delete(keys: string[], opts?: DeleteManyOptions): Promise<DeleteManyResult>;
-    copy(from: string, to: string, opts?: OperationOptions): Promise<void>;
-    move(from: string, to: string, opts?: OperationOptions): Promise<void>;
-    list(opts?: ListOptions): Promise<ListResult>;
-    listAll(opts?: ListOptions): AsyncGenerator<StoredFile>;
-    url(key: string, opts?: UrlOptions): Promise<string>;
-    signedUploadUrl(key: string, opts: SignUploadOptions): Promise<SignedUpload>;
-    /** Prefix-bound view of the driver's presigned-multipart capability. */
-    get signedMultipart(): SignedMultipartCapability | undefined;
-    createMultipartUpload(key: string, opts?: CreateMultipartOptions): Promise<MultipartUpload>;
-    resumeMultipartUpload(key: string, uploadId: string): MultipartUpload;
-    /** A key-bound handle over the common single-object operations. */
-    file(key: string): FileHandle;
-    /** A read-only clone of this handle (mutations throw `ReadOnly`). */
-    readonly(): Storage;
-}
-export interface FileHandle {
-    readonly key: string;
-    upload(body: Body, opts?: UploadOptions): Promise<UploadResult>;
-    download(opts?: DownloadOptions): Promise<StoredFile>;
-    head(opts?: OperationOptions): Promise<StoredFile>;
-    exists(opts?: OperationOptions): Promise<boolean>;
-    delete(opts?: OperationOptions): Promise<void>;
-    url(opts?: UrlOptions): Promise<string>;
-    signedUploadUrl(opts: SignUploadOptions): Promise<SignedUpload>;
-}
-export declare function createStorage(opts: StorageOptions): Storage;