@minhvuong/pirate-storage 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# Drive storage SDK
+
+Self-hosted, provider-oriented file storage helpers. Applications own their deployment,
+credentials, authentication, receipts, and database.
+
+## Packages
+
+| Package                          | Purpose                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| `@minhvuong/pirate-storage`                 | Core contracts, receipts, orchestration, hooks, Range parsing, journals |
+| `@drive/storage-discord`         | Discord webhook transport and production storage provider               |
+| `@drive/storage-server`          | Typed file routes and Fetch/Worker upload handler                       |
+| `@drive/storage-client`          | Browser multipart uploader                                              |
+| `@drive/storage-preview-browser` | Optional JPEG/PNG preview Web Worker                                    |
+
+`@drive/*` is the internal workspace scope. Replace it with an owned registry scope before public
+publication.
+
+## Server or Worker
+
+```ts
+import { MemoryUploadJournal, createStorage } from "@minhvuong/pirate-storage";
+import { createDiscordProvider } from "@drive/storage-discord";
+import { createFetchHandler, createFileRoute, defineFileRouter } from "@drive/storage-server";
+
+const discord = createDiscordProvider({
+  webhookUrl: env.DISCORD_WEBHOOK_URL,
+  manifestSecret: env.STORAGE_MANIFEST_SECRET,
+  partSize: 8 * 1024 * 1024,
+  attachmentsPerMessage: 4,
+  uploadConcurrency: 3,
+});
+
+const storage = createStorage({
+  providers: { discord },
+  defaultProvider: "discord",
+});
+
+const f = createFileRoute();
+const router = defineFileRouter({
+  attachments: f({
+    provider: "discord",
+    accept: ["image/*", "video/*", "application/pdf"],
+    maxFileSize: 2_000_000_000,
+  })
+    .input((value) => uploadInputSchema.parse(value))
+    .middleware(async ({ request }) => {
+      const user = await requireUser(request);
+      return { userId: user.id };
+    })
+    .onUploadComplete(async ({ receipt, metadata }) => {
+      // Prisma, Drizzle, D1, Convex, raw SQL, or anything else belongs here.
+      return database.files.create({ receipt, ownerId: metadata.userId });
+    }),
+});
+
+export const handleStorage = createFetchHandler({
+  storage,
+  router,
+  journal: new MemoryUploadJournal(), // Development only; use durable storage in production.
+});
+```
+
+The handler is Fetch-standard and can be mounted in a Cloudflare Worker, TanStack Start server
+route, Next route handler, Bun server, or any runtime that accepts `Request` and returns `Response`.
+
+## Browser
+
+```ts
+import { createUploader } from "@drive/storage-client";
+import { createBrowserImagePreview } from "@drive/storage-preview-browser";
+
+const uploader = createUploader({
+  endpoint: "/api/storage",
+  headers: async () => ({ Authorization: `Bearer ${await getSessionToken()}` }),
+  previewGenerators: [createBrowserImagePreview()],
+});
+
+const task = uploader.createUpload("attachments", file, {
+  input: { folderId },
+  concurrency: 3,
+  onProgress: console.log,
+});
+
+task.pause();
+task.resume();
+const { receipt, serverData } = await task.done;
+```
+
+The browser uploads bounded parts to the application's authenticated handler. It never receives a
+Discord webhook or bot credential. Discord has no scoped presigned-upload mechanism.
+
+## Imperative API
+
+```ts
+const receipt = await storage.upload(file, { provider: "discord" });
+const receipts = await storage.uploadMany(files, { provider: "discord" });
+const remote = await storage.uploadFromUrl(url, { provider: "discord" });
+
+await storage.stat(receipt);
+await storage.verify(receipt);
+const response = await storage.open(receipt, { range: "bytes=0-1048575" });
+const httpResponse = await storage.toResponse(receipt, request);
+const preview = await storage.preview(receipt, { width: 800, format: "webp" });
+const freshLinks = await storage.refresh(receipt);
+await storage.delete(receipt);
+```
+
+Providers declare capabilities instead of being forced to implement features they cannot support.
+Future providers can omit Range reads, multipart upload, deletion, preview generation, or transforms
+and expose those limitations through `provider.capabilities`.
+
+## Production notes
+
+- Store the complete versioned receipt JSON in the consumer's database.
+- Never persist Discord CDN URLs; they are signed and expire.
+- Use at least 32 random bytes for `STORAGE_MANIFEST_SECRET` and back it up.
+- Replace `MemoryUploadJournal` with a Durable Object, D1, Redis, or another atomic durable adapter.
+- Protect every upload-session endpoint with application authentication.
+- Restrict `uploadFromUrl` destinations to avoid SSRF in server applications.
+- Discord image proxy transforms are experimental and should have an application fallback.

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export type StorageErrorCode = "INVALID_INPUT" | "INVALID_RECEIPT" | "PROVIDER_NOT_FOUND" | "CAPABILITY_UNSUPPORTED" | "FILE_TOO_LARGE" | "UPLOAD_FAILED" | "READ_FAILED" | "DELETE_FAILED" | "INTEGRITY_FAILED" | "RANGE_NOT_SATISFIABLE" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED";
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(code: StorageErrorCode, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+export declare class UnsupportedCapabilityError extends StorageError {
+    constructor(provider: string, capability: string);
+}
+export declare class RangeNotSatisfiableError extends StorageError {
+    constructor(message?: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./errors";
+export * from "./journal";
+export * from "./provider";
+export * from "./range";
+export * from "./receipt";
+export * from "./source";
+export * from "./storage";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,484 @@
+// src/errors.ts
+class StorageError extends Error {
+  code;
+  status;
+  cause;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "StorageError";
+    this.code = code;
+    this.status = options.status;
+    this.cause = options.cause;
+  }
+}
+
+class UnsupportedCapabilityError extends StorageError {
+  constructor(provider, capability) {
+    super("CAPABILITY_UNSUPPORTED", `Provider '${provider}' does not support ${capability}`, {
+      status: 501
+    });
+    this.name = "UnsupportedCapabilityError";
+  }
+}
+
+class RangeNotSatisfiableError extends StorageError {
+  constructor(message = "The requested byte range is not satisfiable") {
+    super("RANGE_NOT_SATISFIABLE", message, { status: 416 });
+    this.name = "RangeNotSatisfiableError";
+  }
+}
+// src/journal.ts
+class MemoryUploadJournal {
+  #sessions = new Map;
+  #queues = new Map;
+  async create(session) {
+    this.#prune();
+    if (this.#sessions.has(session.id)) {
+      throw new StorageError("INVALID_INPUT", `Upload session '${session.id}' already exists`);
+    }
+    this.#sessions.set(session.id, structuredClone(session));
+  }
+  async get(id) {
+    this.#prune();
+    const session = this.#sessions.get(id);
+    return session ? structuredClone(session) : undefined;
+  }
+  putPart(id, part) {
+    return this.#mutate(id, (session) => {
+      if (session.status !== "active") {
+        throw new StorageError("INVALID_INPUT", `Upload session '${id}' is not active`);
+      }
+      session.parts[String(part.index)] = structuredClone(part);
+    });
+  }
+  setStatus(id, status) {
+    return this.#mutate(id, (session) => {
+      session.status = status;
+    });
+  }
+  setResult(id, result) {
+    return this.#mutate(id, (session) => {
+      session.status = "complete";
+      session.result = structuredClone(result);
+    });
+  }
+  async remove(id) {
+    await this.#queues.get(id)?.catch(() => {
+      return;
+    });
+    this.#sessions.delete(id);
+    this.#queues.delete(id);
+  }
+  #mutate(id, update) {
+    const previous = this.#queues.get(id) ?? Promise.resolve();
+    const operation = previous.then(() => {
+      this.#prune();
+      const current = this.#sessions.get(id);
+      if (!current) {
+        throw new StorageError("SESSION_NOT_FOUND", `Upload session '${id}' was not found`, {
+          status: 404
+        });
+      }
+      const session = structuredClone(current);
+      update(session);
+      this.#sessions.set(id, session);
+      return structuredClone(session);
+    });
+    this.#queues.set(id, operation);
+    operation.then(() => {
+      if (this.#queues.get(id) === operation)
+        this.#queues.delete(id);
+    }, () => {
+      if (this.#queues.get(id) === operation)
+        this.#queues.delete(id);
+    });
+    return operation;
+  }
+  #prune() {
+    const now = Date.now();
+    for (const [id, session] of this.#sessions) {
+      if (Date.parse(session.expiresAt) <= now)
+        this.#sessions.delete(id);
+    }
+  }
+}
+// src/provider.ts
+var capabilityDefaults = Object.freeze({
+  upload: false,
+  uploadStream: false,
+  multipartUpload: false,
+  parallelUpload: false,
+  resumableUpload: false,
+  read: false,
+  rangeRead: false,
+  delete: false,
+  preview: false,
+  nativePreview: false,
+  imageTransform: "none",
+  directClientUpload: false
+});
+function providerCapabilities(capabilities) {
+  return Object.freeze({ ...capabilityDefaults, ...capabilities });
+}
+function defineStorageProvider(provider) {
+  return provider;
+}
+// src/range.ts
+function parseByteRange(header, size) {
+  if (!header)
+    return null;
+  if (!header.startsWith("bytes=") || header.includes(",") || size <= 0) {
+    throw new RangeNotSatisfiableError;
+  }
+  const value = header.slice("bytes=".length).trim();
+  const separator = value.indexOf("-");
+  if (separator === -1)
+    throw new RangeNotSatisfiableError;
+  const rawStart = value.slice(0, separator).trim();
+  const rawEnd = value.slice(separator + 1).trim();
+  if (!rawStart && !rawEnd)
+    throw new RangeNotSatisfiableError;
+  if (!rawStart) {
+    const suffixLength = Number(rawEnd);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0) {
+      throw new RangeNotSatisfiableError;
+    }
+    return { start: Math.max(0, size - suffixLength), end: size - 1 };
+  }
+  const start = Number(rawStart);
+  const requestedEnd = rawEnd ? Number(rawEnd) : size - 1;
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0 || requestedEnd < start || start >= size) {
+    throw new RangeNotSatisfiableError;
+  }
+  return { start, end: Math.min(requestedEnd, size - 1) };
+}
+// src/receipt.ts
+import { z } from "zod";
+var storedFileSchema = z.object({
+  name: z.string().min(1).max(255),
+  contentType: z.string().min(1).max(200),
+  size: z.number().int().positive(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/)
+});
+var previewSchema = z.object({
+  contentType: z.string().regex(/^image\//),
+  size: z.number().int().positive(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive()
+});
+var storageReceiptSchema = z.object({
+  version: z.literal(1),
+  provider: z.string().min(1),
+  connectionId: z.string().min(1),
+  createdAt: z.string().datetime(),
+  file: storedFileSchema,
+  locator: z.unknown(),
+  preview: previewSchema.optional()
+});
+function parseReceipt(value) {
+  const result = storageReceiptSchema.safeParse(value);
+  if (!result.success) {
+    throw new StorageError("INVALID_RECEIPT", "The storage receipt is invalid", {
+      status: 400,
+      cause: result.error
+    });
+  }
+  return result.data;
+}
+function serializeReceipt(receipt) {
+  return JSON.stringify(storageReceiptSchema.parse(receipt));
+}
+// src/source.ts
+function normalizeUploadSource(input) {
+  if (typeof File !== "undefined" && input instanceof File) {
+    return {
+      name: input.name,
+      contentType: input.type || "application/octet-stream",
+      size: input.size,
+      stream: () => input.stream(),
+      blob: input
+    };
+  }
+  if (!("body" in input)) {
+    throw new StorageError("INVALID_INPUT", "Expected a File or streaming upload descriptor");
+  }
+  const streamFactory = typeof input.body === "function" ? input.body : once(input.body);
+  const source = {
+    name: input.name,
+    contentType: input.contentType || "application/octet-stream",
+    size: input.size,
+    stream: streamFactory
+  };
+  validateUploadSource(source);
+  return source;
+}
+function validateUploadSource(source, maxFileSize) {
+  if (!source.name || source.name.length > 255 || !Number.isSafeInteger(source.size)) {
+    throw new StorageError("INVALID_INPUT", "Choose a valid, non-empty file", { status: 400 });
+  }
+  if (source.size <= 0) {
+    throw new StorageError("INVALID_INPUT", "Choose a non-empty file", { status: 400 });
+  }
+  if (maxFileSize !== undefined && source.size > maxFileSize) {
+    throw new StorageError("FILE_TOO_LARGE", `File exceeds the provider's ${maxFileSize} byte limit`, { status: 413 });
+  }
+  if (!source.contentType || source.contentType.length > 200) {
+    throw new StorageError("INVALID_INPUT", "Choose a valid file content type", { status: 400 });
+  }
+}
+async function* streamParts(body, expectedSize, partSize) {
+  const reader = body.getReader();
+  let total = 0;
+  let offset = 0;
+  let part = new Uint8Array(Math.min(partSize, expectedSize));
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done)
+        break;
+      if (total + result.value.byteLength > expectedSize) {
+        throw new StorageError("INVALID_INPUT", "Upload stream exceeds its declared size", {
+          status: 400
+        });
+      }
+      let inputOffset = 0;
+      while (inputOffset < result.value.byteLength) {
+        const amount = Math.min(part.byteLength - offset, result.value.byteLength - inputOffset);
+        part.set(result.value.subarray(inputOffset, inputOffset + amount), offset);
+        inputOffset += amount;
+        offset += amount;
+        total += amount;
+        if (offset === part.byteLength) {
+          yield part;
+          offset = 0;
+          if (total < expectedSize)
+            part = new Uint8Array(Math.min(partSize, expectedSize - total));
+        }
+      }
+    }
+    if (total !== expectedSize) {
+      throw new StorageError("INVALID_INPUT", "Upload stream ended before its declared size", {
+        status: 400
+      });
+    }
+    if (offset > 0)
+      yield part.subarray(0, offset);
+  } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
+  }
+}
+function once(stream) {
+  let consumed = false;
+  return () => {
+    if (consumed) {
+      throw new StorageError("INVALID_INPUT", "This upload stream has already been consumed");
+    }
+    consumed = true;
+    return stream;
+  };
+}
+// src/storage.ts
+class Storage {
+  #providers;
+  #defaultProvider;
+  #previewGenerators;
+  #hooks;
+  constructor(options) {
+    this.#providers = options.providers;
+    this.#defaultProvider = options.defaultProvider;
+    this.#previewGenerators = options.previewGenerators ?? [];
+    this.#hooks = options.hooks;
+  }
+  capabilities(provider) {
+    return this.#provider(provider).capabilities;
+  }
+  provider(provider) {
+    return this.#provider(provider);
+  }
+  async upload(input, options = {}) {
+    const providerName = options.provider ?? this.#defaultProvider;
+    if (!providerName) {
+      throw new StorageError("PROVIDER_NOT_FOUND", "An upload provider is required", {
+        status: 400
+      });
+    }
+    const provider = this.#provider(providerName);
+    const source = normalizeUploadSource(input);
+    validateUploadSource(source, provider.capabilities.maxFileSize);
+    try {
+      const preview = await this.#preparePreview(source, options);
+      const receipt = await provider.upload(source, {
+        signal: options.signal,
+        preview,
+        concurrency: options.concurrency,
+        metadata: options.metadata,
+        onProgress: options.onProgress
+      });
+      await this.#hooks?.onUploadComplete?.({
+        receipt,
+        metadata: options.metadata
+      });
+      return receipt;
+    } catch (error) {
+      await this.#hooks?.onUploadError?.({ error, provider: providerName, source });
+      throw error;
+    }
+  }
+  async uploadMany(inputs, options = {}) {
+    const concurrency = positiveInteger(options.fileConcurrency ?? 2, "fileConcurrency");
+    const results = new Array(inputs.length);
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, inputs.length) }, async () => {
+      while (cursor < inputs.length) {
+        const index = cursor;
+        cursor += 1;
+        const input = inputs[index];
+        if (input)
+          results[index] = await this.upload(input, options);
+      }
+    }));
+    return results;
+  }
+  async uploadFromUrl(value, options = {}) {
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    const response = await fetchImplementation(value, {
+      ...options.request,
+      signal: options.signal ?? options.request?.signal
+    });
+    if (!response.ok || !response.body) {
+      throw new StorageError("INVALID_INPUT", `Remote upload source failed (${response.status})`, {
+        status: 400
+      });
+    }
+    const length = Number(response.headers.get("content-length"));
+    if (!Number.isSafeInteger(length) || length <= 0) {
+      await response.body.cancel().catch(() => {
+        return;
+      });
+      throw new StorageError("INVALID_INPUT", "Remote upload source must return a positive Content-Length", { status: 400 });
+    }
+    const url = new URL(response.url || String(value));
+    const fallbackName = decodeURIComponent(url.pathname.split("/").filter(Boolean).at(-1) ?? "download");
+    return this.upload({
+      name: options.name ?? fallbackName,
+      contentType: options.contentType ?? response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream",
+      size: length,
+      body: response.body
+    }, options);
+  }
+  async stat(receiptValue) {
+    const receipt = parseReceipt(receiptValue);
+    return this.#providerForReceipt(receipt).stat(receipt);
+  }
+  async verify(receiptValue) {
+    await this.stat(receiptValue);
+    return true;
+  }
+  async open(receiptValue, options = {}) {
+    const receipt = parseReceipt(receiptValue);
+    const provider = this.#providerForReceipt(receipt);
+    if (!provider.open)
+      throw new UnsupportedCapabilityError(provider.id, "reads");
+    return provider.open(receipt, options);
+  }
+  async toResponse(receiptValue, request) {
+    const url = new URL(request.url);
+    return this.open(receiptValue, {
+      method: request.method === "HEAD" ? "HEAD" : "GET",
+      range: request.headers.get("range"),
+      download: url.searchParams.get("download") === "1",
+      signal: request.signal
+    });
+  }
+  async preview(receiptValue, options = {}) {
+    const receipt = parseReceipt(receiptValue);
+    const provider = this.#providerForReceipt(receipt);
+    if (!provider.preview)
+      throw new UnsupportedCapabilityError(provider.id, "previews");
+    return provider.preview(receipt, options);
+  }
+  async refresh(receiptValue) {
+    const receipt = parseReceipt(receiptValue);
+    const provider = this.#providerForReceipt(receipt);
+    if (!provider.refresh)
+      throw new UnsupportedCapabilityError(provider.id, "URL refresh");
+    return provider.refresh(receipt);
+  }
+  async delete(receiptValue, options = {}) {
+    const receipt = parseReceipt(receiptValue);
+    const provider = this.#providerForReceipt(receipt);
+    if (!provider.delete)
+      throw new UnsupportedCapabilityError(provider.id, "deletion");
+    await provider.delete(receipt, options);
+    await this.#hooks?.onDeleteComplete?.({ receipt });
+  }
+  async deleteMany(receipts) {
+    return Promise.allSettled(receipts.map((receipt) => this.delete(receipt)));
+  }
+  #provider(provider) {
+    const selected = this.#providers[provider];
+    if (!selected) {
+      throw new StorageError("PROVIDER_NOT_FOUND", `Storage provider '${provider}' is not configured`, {
+        status: 400
+      });
+    }
+    return selected;
+  }
+  #providerForReceipt(receipt) {
+    const provider = this.#providers[receipt.provider];
+    if (!provider) {
+      throw new StorageError("PROVIDER_NOT_FOUND", `Storage provider '${receipt.provider}' is not configured`, { status: 400 });
+    }
+    if (provider.id !== receipt.provider) {
+      throw new StorageError("INVALID_RECEIPT", "Receipt provider does not match configuration");
+    }
+    return provider;
+  }
+  async#preparePreview(source, options) {
+    if (options.preview === false || options.previewGenerator === false)
+      return;
+    if (options.preview)
+      return options.preview;
+    const candidates = options.previewGenerator ? this.#previewGenerators.filter((generator) => generator.id === options.previewGenerator) : this.#previewGenerators;
+    for (const generator of candidates) {
+      if (await generator.supports(source)) {
+        return generator.generate(source, {
+          signal: options.signal,
+          onProgress: options.onPreviewProgress
+        });
+      }
+    }
+    if (options.previewGenerator && candidates.length === 0) {
+      throw new StorageError("INVALID_INPUT", `Preview generator '${options.previewGenerator}' is not configured`);
+    }
+    return;
+  }
+}
+function createStorage(options) {
+  return new Storage(options);
+}
+function positiveInteger(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new StorageError("INVALID_INPUT", `${name} must be a positive integer`);
+  }
+  return value;
+}
+export {
+  validateUploadSource,
+  streamParts,
+  storageReceiptSchema,
+  serializeReceipt,
+  providerCapabilities,
+  parseReceipt,
+  parseByteRange,
+  normalizeUploadSource,
+  defineStorageProvider,
+  createStorage,
+  UnsupportedCapabilityError,
+  StorageError,
+  Storage,
+  RangeNotSatisfiableError,
+  MemoryUploadJournal
+};

package/dist/journal.d.ts

@@ -0,0 +1,34 @@
+import type { ProviderMultipartPart, StoredFile } from "./types";
+export type UploadSessionStatus = "active" | "completing" | "complete" | "aborted";
+export interface UploadSession<State = unknown, Locator = unknown> {
+    id: string;
+    provider: string;
+    route: string;
+    file: Omit<StoredFile, "sha256"> & {
+        sha256?: string;
+    };
+    providerState: State;
+    partSize: number;
+    parts: Record<string, ProviderMultipartPart<Locator>>;
+    status: UploadSessionStatus;
+    result?: unknown;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface UploadJournal {
+    create(session: UploadSession): Promise<void>;
+    get(id: string): Promise<UploadSession | undefined>;
+    putPart(id: string, part: ProviderMultipartPart): Promise<UploadSession>;
+    setStatus(id: string, status: UploadSessionStatus): Promise<UploadSession>;
+    setResult(id: string, result: unknown): Promise<UploadSession>;
+    remove(id: string): Promise<void>;
+}
+export declare class MemoryUploadJournal implements UploadJournal {
+    #private;
+    create(session: UploadSession): Promise<void>;
+    get(id: string): Promise<UploadSession | undefined>;
+    putPart(id: string, part: ProviderMultipartPart): Promise<UploadSession>;
+    setStatus(id: string, status: UploadSessionStatus): Promise<UploadSession>;
+    setResult(id: string, result: unknown): Promise<UploadSession>;
+    remove(id: string): Promise<void>;
+}

package/dist/provider.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderCapabilities, StorageProvider } from "./types";
+/** Build a complete capability declaration without forcing small providers to repeat false flags. */
+export declare function providerCapabilities(capabilities: Partial<ProviderCapabilities>): ProviderCapabilities;
+/** Identity helper that preserves a provider's receipt, multipart-state, and locator inference. */
+export declare function defineStorageProvider<const Provider extends StorageProvider<any, any, any>>(provider: Provider): Provider;

package/dist/range.d.ts

@@ -0,0 +1,5 @@
+export interface ByteRange {
+    start: number;
+    end: number;
+}
+export declare function parseByteRange(header: string | null | undefined, size: number): ByteRange | null;

package/dist/receipt.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { StorageReceipt } from "./types";
+export declare const storageReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    provider: z.ZodString;
+    connectionId: z.ZodString;
+    createdAt: z.ZodString;
+    file: z.ZodObject<{
+        name: z.ZodString;
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>;
+    locator: z.ZodUnknown;
+    preview: z.ZodOptional<z.ZodObject<{
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function parseReceipt(value: unknown): StorageReceipt;
+export declare function serializeReceipt(receipt: StorageReceipt): string;

package/dist/source.d.ts

@@ -0,0 +1,4 @@
+import type { StorageUploadInput, StorageUploadSource } from "./types";
+export declare function normalizeUploadSource(input: StorageUploadInput): StorageUploadSource;
+export declare function validateUploadSource(source: StorageUploadSource, maxFileSize?: number): void;
+export declare function streamParts(body: ReadableStream<Uint8Array>, expectedSize: number, partSize: number): AsyncGenerator<Uint8Array>;

package/dist/storage.d.ts

@@ -0,0 +1,50 @@
+import type { GeneratedPreview, PreviewGenerator, ProviderMap, ReceiptForMap, ReceiptForProvider, StorageHooks, StorageOpenOptions, StoragePreviewOptions, StorageProvider, StorageUploadInput } from "./types";
+export interface CreateStorageOptions<Providers extends ProviderMap> {
+    providers: Providers;
+    defaultProvider?: keyof Providers & string;
+    previewGenerators?: readonly PreviewGenerator[];
+    hooks?: StorageHooks<ReceiptForMap<Providers>>;
+}
+export interface UploadOptions<Provider extends string = string> {
+    provider?: Provider;
+    preview?: GeneratedPreview | false;
+    previewGenerator?: string | false;
+    signal?: AbortSignal;
+    concurrency?: number;
+    metadata?: Readonly<Record<string, unknown>>;
+    onProgress?: Parameters<StorageProvider["upload"]>[1]["onProgress"];
+    onPreviewProgress?: (event: {
+        stage: string;
+        percentage: number;
+    }) => void;
+}
+export interface UploadFromUrlOptions<Provider extends string = string> extends UploadOptions<Provider> {
+    name?: string;
+    contentType?: string;
+    fetch?: typeof globalThis.fetch;
+    request?: RequestInit;
+}
+export declare class Storage<Providers extends ProviderMap> {
+    #private;
+    constructor(options: CreateStorageOptions<Providers>);
+    capabilities<Provider extends keyof Providers & string>(provider: Provider): import("./types").ProviderCapabilities;
+    provider<Provider extends keyof Providers & string>(provider: Provider): Providers[Provider];
+    upload<Provider extends keyof Providers & string>(input: StorageUploadInput, options?: UploadOptions<Provider>): Promise<ReceiptForProvider<Providers[Provider]>>;
+    uploadMany<Provider extends keyof Providers & string>(inputs: readonly StorageUploadInput[], options?: UploadOptions<Provider> & {
+        fileConcurrency?: number;
+    }): Promise<Array<ReceiptForProvider<Providers[Provider]>>>;
+    uploadFromUrl<Provider extends keyof Providers & string>(value: string | URL, options?: UploadFromUrlOptions<Provider>): Promise<ReceiptForProvider<Providers[Provider]>>;
+    stat(receiptValue: unknown): Promise<import("./types").StoredFile & {
+        preview?: import("./types").StoredPreview;
+    }>;
+    verify(receiptValue: unknown): Promise<true>;
+    open(receiptValue: unknown, options?: StorageOpenOptions): Promise<Response>;
+    toResponse(receiptValue: unknown, request: Request): Promise<Response>;
+    preview(receiptValue: unknown, options?: StoragePreviewOptions): Promise<Response>;
+    refresh(receiptValue: unknown): Promise<import("./types").RefreshedProviderLinks>;
+    delete(receiptValue: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    deleteMany(receipts: readonly unknown[]): Promise<PromiseSettledResult<void>[]>;
+}
+export declare function createStorage<const Providers extends ProviderMap>(options: CreateStorageOptions<Providers>): Storage<Providers>;

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+export type MaybePromise<T> = T | Promise<T>;
+export interface StoredFile {
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+}
+export interface StoredPreview {
+    contentType: string;
+    size: number;
+    width: number;
+    height: number;
+}
+export interface StorageReceipt<Provider extends string = string, Locator = unknown> {
+    version: 1;
+    provider: Provider;
+    connectionId: string;
+    createdAt: string;
+    file: StoredFile;
+    locator: Locator;
+    preview?: StoredPreview;
+}
+export interface StorageUploadSource {
+    name: string;
+    contentType: string;
+    size: number;
+    stream(): ReadableStream<Uint8Array>;
+    /** Present when the original input is Blob-compatible, such as a browser File. */
+    blob?: Blob;
+}
+export type StorageUploadInput = File | {
+    name: string;
+    contentType?: string;
+    size: number;
+    body: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+};
+export interface GeneratedPreview {
+    file: File;
+    width: number;
+    height: number;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface PreviewGenerationContext {
+    signal?: AbortSignal;
+    onProgress?: (event: {
+        stage: string;
+        percentage: number;
+    }) => void;
+}
+export interface PreviewGenerator {
+    readonly id: string;
+    supports(source: StorageUploadSource): MaybePromise<boolean>;
+    generate(source: StorageUploadSource, context: PreviewGenerationContext): Promise<GeneratedPreview | undefined>;
+}
+export interface ProviderCapabilities {
+    readonly upload: boolean;
+    readonly uploadStream: boolean;
+    readonly multipartUpload: boolean;
+    readonly parallelUpload: boolean;
+    readonly resumableUpload: boolean;
+    readonly read: boolean;
+    readonly rangeRead: boolean;
+    readonly delete: boolean;
+    readonly preview: boolean;
+    readonly nativePreview: boolean;
+    readonly imageTransform: "none" | "experimental" | "supported";
+    readonly directClientUpload: boolean;
+    readonly maxFileSize?: number;
+    readonly preferredPartSize?: number;
+    readonly maxPartSize?: number;
+    readonly maxPartsPerRequest?: number;
+}
+export interface ProviderUploadOptions {
+    signal?: AbortSignal;
+    preview?: GeneratedPreview;
+    concurrency?: number;
+    metadata?: Readonly<Record<string, unknown>>;
+    onProgress?: (event: StorageProgressEvent) => void;
+}
+export interface StorageProgressEvent {
+    phase: "preparing" | "uploading" | "finalizing";
+    uploadedBytes: number;
+    totalBytes: number;
+    completedParts?: number;
+    totalParts?: number;
+}
+export interface StorageOpenOptions {
+    method?: "GET" | "HEAD";
+    range?: string | null;
+    download?: boolean;
+    signal?: AbortSignal;
+}
+export interface StoragePreviewOptions {
+    width?: number;
+    height?: number;
+    format?: "avif" | "jpeg" | "jpg" | "png" | "webp";
+    quality?: "low" | "high" | "lossless";
+    signal?: AbortSignal;
+}
+export interface RefreshedProviderLinks {
+    expires: boolean;
+    parts: string[];
+    preview?: string;
+}
+export interface ProviderMultipartSession<State = unknown> {
+    state: State;
+    partSize: number;
+    maxConcurrency?: number;
+}
+export interface ProviderMultipartPart<Locator = unknown> {
+    index: number;
+    size: number;
+    sha256: string;
+    locator: Locator;
+}
+export interface StorageProvider<Receipt extends StorageReceipt = StorageReceipt, MultipartState = unknown, MultipartLocator = unknown> {
+    readonly id: Receipt["provider"];
+    readonly capabilities: ProviderCapabilities;
+    upload(source: StorageUploadSource, options: ProviderUploadOptions): Promise<Receipt>;
+    stat(receipt: Receipt): Promise<StoredFile & {
+        preview?: StoredPreview;
+    }>;
+    open?(receipt: Receipt, options: StorageOpenOptions): Promise<Response>;
+    delete?(receipt: Receipt, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    preview?(receipt: Receipt, options: StoragePreviewOptions): Promise<Response>;
+    refresh?(receipt: Receipt): Promise<RefreshedProviderLinks>;
+    beginMultipart?(file: Omit<StoredFile, "sha256">, options: ProviderUploadOptions): Promise<ProviderMultipartSession<MultipartState>>;
+    uploadPart?(session: ProviderMultipartSession<MultipartState>, part: {
+        index: number;
+        bytes: Uint8Array;
+        signal?: AbortSignal;
+    }): Promise<ProviderMultipartPart<MultipartLocator>>;
+    completeMultipart?(session: ProviderMultipartSession<MultipartState>, parts: ProviderMultipartPart<MultipartLocator>[], file: StoredFile, options: ProviderUploadOptions): Promise<Receipt>;
+    abortMultipart?(session: ProviderMultipartSession<MultipartState>, parts: ProviderMultipartPart<MultipartLocator>[]): Promise<void>;
+}
+export type ProviderMap = Readonly<Record<string, StorageProvider<StorageReceipt, any, any>>>;
+export type ReceiptForProvider<Provider> = Provider extends StorageProvider<infer Receipt, any, any> ? Receipt : never;
+export type ReceiptForMap<Providers extends ProviderMap> = ReceiptForProvider<Providers[keyof Providers]>;
+export interface StorageHooks<Receipt extends StorageReceipt = StorageReceipt> {
+    onUploadComplete?(context: {
+        receipt: Receipt;
+        metadata?: Readonly<Record<string, unknown>>;
+    }): MaybePromise<unknown>;
+    onUploadError?(context: {
+        error: unknown;
+        provider: string;
+        source: StorageUploadSource;
+    }): MaybePromise<void>;
+    onDeleteComplete?(context: {
+        receipt: Receipt;
+    }): MaybePromise<void>;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@minhvuong/pirate-storage",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target browser --packages external && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "typescript": "catalog:"
+  }
+}