@minhvuong/pirate-storage-discord 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @minhvuong/pirate-storage-discord
+
+Discord storage provider for `@minhvuong/pirate-storage`.
+
+- 8 MiB default parts (10 MiB validated maximum)
+- bounded parallel uploads and up to 10 attachments per Discord message
+- HMAC-signed durable manifests
+- expiring CDN URL refresh
+- logical HTTP Range streaming with CDN fallback
+- native small-image previews and optional generated previews
+- best-effort Discord media proxy transforms
+- rollback and deletion
+
+Discord does not expose scoped presigned upload URLs. Credentials must remain in the consumer's
+server or Worker, which stays in the upload byte path.

package/dist/crypto.d.ts

@@ -0,0 +1,3 @@
+export declare function signManifest(value: unknown, secret: string | Uint8Array): Promise<string>;
+export declare function verifyManifestSignature(value: unknown, signature: string, secret: string | Uint8Array): Promise<boolean>;
+export declare function validateManifestSecret(secret: string | Uint8Array): void;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./provider";
+export * from "./transport";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,1046 @@
+// src/provider.ts
+import {
+  RangeNotSatisfiableError,
+  StorageError as StorageError2,
+  parseByteRange,
+  streamParts,
+  validateUploadSource
+} from "@minhvuong/pirate-storage";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+
+// src/crypto.ts
+var encoder = new TextEncoder;
+async function signManifest(value, secret) {
+  const key = await crypto.subtle.importKey("raw", secretBytes(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(stableStringify(value)));
+  return toHex(new Uint8Array(signature));
+}
+async function verifyManifestSignature(value, signature, secret) {
+  if (!/^[a-f0-9]{64}$/.test(signature))
+    return false;
+  const expected = await signManifest(value, secret);
+  let difference = 0;
+  for (let index = 0;index < expected.length; index += 1) {
+    difference |= expected.charCodeAt(index) ^ signature.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function validateManifestSecret(secret) {
+  if (secretBytes(secret).byteLength < 32) {
+    throw new Error("manifestSecret must contain at least 32 UTF-8 bytes");
+  }
+}
+function secretBytes(secret) {
+  const bytes = typeof secret === "string" ? encoder.encode(secret) : secret;
+  return new Uint8Array(bytes);
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value))
+    return `[${value.map(stableStringify).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+function toHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+// src/transport.ts
+import { StorageError } from "@minhvuong/pirate-storage";
+
+// src/types.ts
+import { z } from "zod";
+var discordAttachmentSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  size: z.number().int().nonnegative(),
+  url: z.string().url(),
+  proxy_url: z.string().url().optional(),
+  content_type: z.string().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional()
+});
+var discordMessageSchema = z.object({
+  id: z.string(),
+  channel_id: z.string(),
+  attachments: z.array(discordAttachmentSchema)
+});
+var discordChunkSchema = z.object({
+  index: z.number().int().nonnegative(),
+  size: z.number().int().positive(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  messageId: z.string(),
+  attachmentId: z.string(),
+  filename: z.string()
+});
+var discordPreviewLocatorSchema = z.object({
+  size: z.number().int().positive(),
+  contentType: z.string().regex(/^image\//),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  messageId: z.string(),
+  attachmentId: z.string(),
+  filename: z.string()
+});
+var discordManifestSchema = z.object({
+  version: z.literal(1),
+  uploadId: z.string().uuid(),
+  connectionId: z.string().min(1),
+  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}$/),
+  partSize: z.number().int().positive(),
+  createdAt: z.string().datetime(),
+  chunks: z.array(discordChunkSchema).min(1),
+  preview: discordPreviewLocatorSchema.optional()
+});
+var discordManifestEnvelopeSchema = z.object({
+  version: z.literal(1),
+  algorithm: z.literal("HMAC-SHA256"),
+  manifest: discordManifestSchema,
+  signature: z.string().regex(/^[a-f0-9]{64}$/)
+});
+var discordReceiptLocatorSchema = z.object({
+  channelId: z.string(),
+  manifestMessageId: z.string(),
+  manifestAttachmentId: z.string()
+});
+
+// src/transport.ts
+var DISCORD_HOSTS = new Set(["discord.com", "discordapp.com"]);
+
+class DiscordWebhookTransport {
+  connectionId;
+  #webhookUrl;
+  #fetch;
+  #logger;
+  #messageCache = new Map;
+  #nextRequestAt = 0;
+  constructor(webhookUrl, fetchImplementation = globalThis.fetch, logger) {
+    const parsed = validateWebhookUrl(webhookUrl);
+    this.#webhookUrl = parsed.url;
+    this.connectionId = `webhook:${parsed.webhookId}`;
+    this.#fetch = fetchImplementation;
+    this.#logger = logger;
+  }
+  async uploadAttachments(files, description, options = {}) {
+    if (files.length < 1 || files.length > 10) {
+      throw new StorageError("INVALID_INPUT", "Discord accepts between 1 and 10 attachments");
+    }
+    this.#logger?.debug?.("discord.upload.started", {
+      attachments: files.length,
+      bytes: files.reduce((total, file) => total + file.size, 0)
+    });
+    await this.#respectRateLimit(options.signal);
+    const form = new FormData;
+    form.append("payload_json", JSON.stringify({
+      content: description.slice(0, 2000),
+      allowed_mentions: { parse: [] },
+      attachments: files.map((file, index) => ({ id: index, filename: file.name }))
+    }));
+    files.forEach((file, index) => form.append(`files[${index}]`, file, file.name));
+    const response = await this.#fetchWithRateLimit(`${this.#webhookUrl}?wait=true`, { method: "POST", body: form, signal: options.signal }, options.signal);
+    const message = discordMessageSchema.parse(await response.json());
+    this.#logger?.debug?.("discord.upload.complete", {
+      messageId: message.id,
+      attachments: message.attachments.length
+    });
+    return message;
+  }
+  async getFreshAttachmentUrl(messageId, attachmentId, options = {}) {
+    const message = await this.getMessage(messageId, { signal: options.signal });
+    const attachment = attachmentId ? message.attachments.find((candidate) => candidate.id === attachmentId) : message.attachments[0];
+    if (!attachment) {
+      throw new StorageError("READ_FAILED", `Attachment '${attachmentId ?? "first"}' is missing from Discord message '${messageId}'`);
+    }
+    return options.proxy ? attachment.proxy_url ?? attachment.url : attachment.url;
+  }
+  invalidateMessage(messageId) {
+    this.#messageCache.delete(messageId);
+    this.#logger?.debug?.("discord.message_cache.invalidated", { messageId });
+  }
+  async deleteMessage(messageId, options = {}) {
+    this.invalidateMessage(messageId);
+    for (let attempt = 0;attempt < 6; attempt += 1) {
+      await this.#respectRateLimit(options.signal);
+      const response = await this.#fetch(`${this.#webhookUrl}/messages/${messageId}`, {
+        method: "DELETE",
+        signal: options.signal
+      });
+      this.#rememberRateLimit(response);
+      if (response.ok || response.status === 404)
+        return;
+      if (response.status !== 429) {
+        throw new StorageError("DELETE_FAILED", `Discord message deletion failed (${response.status})`, { status: 502 });
+      }
+      await sleep(await getRetryAfter(response), options.signal);
+    }
+    throw new StorageError("DELETE_FAILED", "Discord message deletion remained rate limited", {
+      status: 502
+    });
+  }
+  async getMessage(messageId, options = {}) {
+    const cached = this.#messageCache.get(messageId);
+    if (cached && cached.expiresAt > Date.now()) {
+      this.#logger?.debug?.("discord.message_cache.hit", { messageId });
+      return cached.message;
+    }
+    this.#logger?.debug?.("discord.message_cache.miss", { messageId });
+    await this.#respectRateLimit(options.signal);
+    const response = await this.#fetchWithRateLimit(`${this.#webhookUrl}/messages/${encodeURIComponent(messageId)}`, { signal: options.signal }, options.signal);
+    const message = discordMessageSchema.parse(await response.json());
+    this.#messageCache.set(messageId, {
+      message,
+      expiresAt: attachmentCacheExpiry(message)
+    });
+    return message;
+  }
+  async#fetchWithRateLimit(url, init, signal) {
+    for (let attempt = 0;attempt < 6; attempt += 1) {
+      const response = await this.#fetch(url, init);
+      this.#rememberRateLimit(response);
+      if (response.status !== 429) {
+        if (!response.ok) {
+          const detail = await response.text();
+          throw new StorageError("UPLOAD_FAILED", `Discord API failed (${response.status}): ${detail.slice(0, 300)}`, { status: response.status === 413 ? 413 : 502 });
+        }
+        return response;
+      }
+      const retryAfter = await getRetryAfter(response);
+      this.#logger?.warn?.("discord.rate_limit.retry", { attempt: attempt + 1, retryAfter });
+      await sleep(retryAfter, signal);
+    }
+    throw new StorageError("UPLOAD_FAILED", "Discord rate limit did not clear after six retries", {
+      status: 503
+    });
+  }
+  #rememberRateLimit(response) {
+    if (response.headers.get("x-ratelimit-remaining") !== "0")
+      return;
+    const resetAfterSeconds = Number(response.headers.get("x-ratelimit-reset-after"));
+    if (Number.isFinite(resetAfterSeconds)) {
+      this.#nextRequestAt = Math.max(this.#nextRequestAt, Date.now() + resetAfterSeconds * 1000);
+    }
+  }
+  async#respectRateLimit(signal) {
+    const delay = this.#nextRequestAt - Date.now();
+    if (delay > 0) {
+      this.#logger?.debug?.("discord.rate_limit.wait", { delay });
+      await sleep(delay, signal);
+    }
+  }
+}
+function validateWebhookUrl(value) {
+  const url = new URL(value);
+  const pathMatch = url.pathname.match(/^\/api(?:\/v\d+)?\/webhooks\/(\d+)\/[^/]+\/?$/);
+  if (url.protocol !== "https:" || !DISCORD_HOSTS.has(url.hostname) || !pathMatch?.[1]) {
+    throw new StorageError("INVALID_INPUT", "webhookUrl must be an HTTPS Discord incoming webhook URL");
+  }
+  url.search = "";
+  url.hash = "";
+  return { url: url.toString().replace(/\/$/, ""), webhookId: pathMatch[1] };
+}
+function attachmentCacheExpiry(message) {
+  const fallback = Date.now() + 5 * 60 * 1000;
+  let earliest = Number.POSITIVE_INFINITY;
+  for (const attachment of message.attachments) {
+    const expiryHex = new URL(attachment.url).searchParams.get("ex");
+    if (!expiryHex)
+      continue;
+    const expiry = Number.parseInt(expiryHex, 16) * 1000 - 60000;
+    if (Number.isFinite(expiry))
+      earliest = Math.min(earliest, expiry);
+  }
+  return Math.max(Date.now() + 5000, Math.min(fallback, earliest));
+}
+async function getRetryAfter(response) {
+  try {
+    const body = await response.clone().json();
+    if (typeof body.retry_after === "number")
+      return Math.max(250, body.retry_after * 1000);
+  } catch {}
+  const headerSeconds = Number(response.headers.get("retry-after"));
+  return Number.isFinite(headerSeconds) ? Math.max(250, headerSeconds * 1000) : 1000;
+}
+function sleep(milliseconds, signal) {
+  if (signal?.aborted)
+    return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, milliseconds);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(signal.reason);
+    }, { once: true });
+  });
+}
+
+// src/provider.ts
+var MEBIBYTE = 1024 * 1024;
+var DEFAULT_PART_SIZE = 8 * MEBIBYTE;
+var DEFAULT_MAX_FILE_SIZE = 2000000000;
+var DEFAULT_MEDIA_WINDOW = 2 * MEBIBYTE;
+var MAX_DISCORD_ATTACHMENT_SIZE = 10 * MEBIBYTE;
+var MANIFEST_CACHE_MS = 5 * 60 * 1000;
+
+class DiscordStorageProvider {
+  id = "discord";
+  capabilities;
+  #transport;
+  #secret;
+  #connectionId;
+  #partSize;
+  #maxFileSize;
+  #attachmentsPerMessage;
+  #uploadConcurrency;
+  #mediaWindowBytes;
+  #fetch;
+  #logger;
+  #manifestCache = new Map;
+  constructor(options) {
+    validateManifestSecret(options.manifestSecret);
+    if (!options.transport && !options.webhookUrl) {
+      throw new StorageError2("INVALID_INPUT", "Discord requires webhookUrl or a custom transport");
+    }
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#transport = options.transport ?? new DiscordWebhookTransport(options.webhookUrl, this.#fetch, options.logger);
+    this.#connectionId = options.connectionId ?? this.#transport.connectionId;
+    this.#secret = options.manifestSecret;
+    this.#partSize = boundedInteger(options.partSize ?? DEFAULT_PART_SIZE, 1, MAX_DISCORD_ATTACHMENT_SIZE, "partSize");
+    this.#maxFileSize = boundedInteger(options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE, 1, Number.MAX_SAFE_INTEGER, "maxFileSize");
+    this.#attachmentsPerMessage = boundedInteger(options.attachmentsPerMessage ?? 1, 1, 10, "attachmentsPerMessage");
+    this.#uploadConcurrency = boundedInteger(options.uploadConcurrency ?? 3, 1, 16, "uploadConcurrency");
+    this.#mediaWindowBytes = boundedInteger(options.mediaWindowBytes ?? DEFAULT_MEDIA_WINDOW, 1, Number.MAX_SAFE_INTEGER, "mediaWindowBytes");
+    this.#logger = options.logger;
+    this.capabilities = Object.freeze({
+      upload: true,
+      uploadStream: true,
+      multipartUpload: true,
+      parallelUpload: true,
+      resumableUpload: true,
+      read: true,
+      rangeRead: true,
+      delete: true,
+      preview: true,
+      nativePreview: true,
+      imageTransform: "experimental",
+      directClientUpload: false,
+      maxFileSize: this.#maxFileSize,
+      preferredPartSize: this.#partSize,
+      maxPartSize: MAX_DISCORD_ATTACHMENT_SIZE,
+      maxPartsPerRequest: 10
+    });
+  }
+  async upload(source, options) {
+    validateUploadSource(source, this.#maxFileSize);
+    validatePreview(options.preview, this.#partSize);
+    options.signal?.throwIfAborted();
+    const uploadId = crypto.randomUUID();
+    const createdMessageIds = new Set;
+    const chunks = [];
+    chunks.length = Math.ceil(source.size / this.#partSize);
+    const hasher = sha256.create();
+    const concurrency = boundedInteger(options.concurrency ?? this.#uploadConcurrency, 1, 16, "concurrency");
+    const inFlight = new Set;
+    const allOperations = [];
+    let batch = [];
+    let uploadedBytes = 0;
+    let preview;
+    const schedule = (pending) => {
+      const operation = this.#uploadChunkBatch(pending, source, chunks.length, createdMessageIds, options.signal).then((uploaded) => {
+        for (const chunk of uploaded) {
+          chunks[chunk.index] = chunk;
+          uploadedBytes += chunk.size;
+        }
+        options.onProgress?.({
+          phase: "uploading",
+          uploadedBytes,
+          totalBytes: source.size,
+          completedParts: chunks.filter(Boolean).length,
+          totalParts: chunks.length
+        });
+      });
+      inFlight.add(operation);
+      allOperations.push(operation);
+      operation.then(() => inFlight.delete(operation), () => inFlight.delete(operation));
+    };
+    try {
+      let index = 0;
+      for await (const bytes of streamParts(source.stream(), source.size, this.#partSize)) {
+        options.signal?.throwIfAborted();
+        hasher.update(bytes);
+        const directImage = chunks.length === 1 && source.contentType.startsWith("image/");
+        const filename = directImage ? source.name : `${uploadId}.part-${String(index + 1).padStart(6, "0")}`;
+        batch.push({
+          index,
+          bytes,
+          sha256: bytesToHex(sha256(bytes)),
+          filename,
+          file: new File([exactArrayBuffer(bytes)], filename, {
+            type: directImage ? source.contentType : "application/octet-stream"
+          })
+        });
+        index += 1;
+        if (batch.length === this.#attachmentsPerMessage) {
+          schedule(batch);
+          batch = [];
+          if (inFlight.size >= concurrency)
+            await Promise.race(inFlight);
+        }
+      }
+      if (batch.length > 0)
+        schedule(batch);
+      await Promise.all(allOperations);
+      if (chunks.some((chunk) => !chunk)) {
+        throw new StorageError2("UPLOAD_FAILED", "Discord upload did not return every file part");
+      }
+      const directAttachment = chunks.length === 1 ? chunks[0] : undefined;
+      if (directAttachment && source.contentType.startsWith("image/")) {
+        const message = await this.#transport.getMessage(directAttachment.messageId, {
+          signal: options.signal
+        });
+        const attachment = message.attachments.find((candidate) => candidate.id === directAttachment.attachmentId);
+        if (attachment?.width && attachment.height) {
+          preview = {
+            size: attachment.size,
+            contentType: attachment.content_type ?? source.contentType,
+            width: attachment.width,
+            height: attachment.height,
+            messageId: directAttachment.messageId,
+            attachmentId: directAttachment.attachmentId,
+            filename: attachment.filename
+          };
+        }
+      }
+      if (options.preview) {
+        preview = await this.#uploadPreview(source.name, options.preview, createdMessageIds, options.signal);
+      }
+      const manifest = {
+        version: 1,
+        uploadId,
+        connectionId: this.#connectionId,
+        name: source.name,
+        contentType: source.contentType,
+        size: source.size,
+        sha256: bytesToHex(hasher.digest()),
+        partSize: this.#partSize,
+        createdAt: new Date().toISOString(),
+        chunks,
+        preview
+      };
+      const envelope = {
+        version: 1,
+        algorithm: "HMAC-SHA256",
+        manifest,
+        signature: await signManifest(manifest, this.#secret)
+      };
+      options.onProgress?.({
+        phase: "finalizing",
+        uploadedBytes: source.size,
+        totalBytes: source.size,
+        completedParts: chunks.length,
+        totalParts: chunks.length
+      });
+      const manifestFile = new File([JSON.stringify(envelope)], `${uploadId}.manifest.json`, {
+        type: "application/json"
+      });
+      const manifestMessage = await this.#transport.uploadAttachments([manifestFile], `Storage manifest · ${safeMessageName(source.name)} · ${chunks.length} parts`, { signal: options.signal });
+      createdMessageIds.add(manifestMessage.id);
+      const manifestAttachment = manifestMessage.attachments[0];
+      if (!manifestAttachment || manifestAttachment.size !== manifestFile.size) {
+        throw new StorageError2("UPLOAD_FAILED", "Discord returned an invalid manifest attachment");
+      }
+      this.#manifestCache.set(manifestMessage.id, {
+        manifest,
+        expiresAt: Date.now() + MANIFEST_CACHE_MS
+      });
+      return toReceipt(manifest, manifestMessage.id, manifestMessage.channel_id, manifestAttachment.id);
+    } catch (error) {
+      await Promise.allSettled(allOperations);
+      await Promise.allSettled([...createdMessageIds].map((messageId) => this.#transport.deleteMessage(messageId).catch((cleanupError) => {
+        this.#logger?.warn?.("Could not roll back Discord message", {
+          messageId,
+          error: String(cleanupError)
+        });
+      })));
+      throw error;
+    }
+  }
+  async stat(receipt) {
+    const manifest = await this.#getManifest(receipt);
+    return {
+      name: manifest.name,
+      contentType: manifest.contentType,
+      size: manifest.size,
+      sha256: manifest.sha256,
+      preview: manifest.preview ? previewSummary(manifest.preview) : undefined
+    };
+  }
+  async beginMultipart(file, _options) {
+    validateUploadSource({
+      ...file,
+      stream: () => {
+        throw new StorageError2("INVALID_INPUT", "Multipart sources do not expose one stream");
+      }
+    }, this.#maxFileSize);
+    return {
+      partSize: this.#partSize,
+      maxConcurrency: this.#uploadConcurrency,
+      state: {
+        version: 1,
+        uploadId: crypto.randomUUID(),
+        connectionId: this.#connectionId,
+        name: file.name,
+        contentType: file.contentType,
+        size: file.size,
+        createdAt: new Date().toISOString()
+      }
+    };
+  }
+  async uploadPart(session, part) {
+    const state = parseMultipartState(session.state, this.#connectionId);
+    if (!Number.isInteger(part.index) || part.index < 0) {
+      throw new StorageError2("INVALID_INPUT", "Multipart part index must be non-negative");
+    }
+    if (part.bytes.byteLength <= 0 || part.bytes.byteLength > this.#partSize) {
+      throw new StorageError2("INVALID_INPUT", `Multipart part must contain between 1 and ${this.#partSize} bytes`);
+    }
+    const expectedParts = Math.ceil(state.size / this.#partSize);
+    if (part.index >= expectedParts) {
+      throw new StorageError2("INVALID_INPUT", "Multipart part index exceeds the declared file");
+    }
+    const expectedSize = part.index === expectedParts - 1 ? state.size - part.index * this.#partSize : this.#partSize;
+    if (part.bytes.byteLength !== expectedSize) {
+      throw new StorageError2("INVALID_INPUT", `Multipart part ${part.index} must contain exactly ${expectedSize} bytes`);
+    }
+    part.signal?.throwIfAborted();
+    const directImage = expectedParts === 1 && state.contentType.startsWith("image/");
+    const filename = directImage ? state.name : `${state.uploadId}.part-${String(part.index + 1).padStart(6, "0")}`;
+    const message = await this.#transport.uploadAttachments([
+      new File([exactArrayBuffer(part.bytes)], filename, {
+        type: directImage ? state.contentType : "application/octet-stream"
+      })
+    ], `Storage part ${part.index + 1}/${expectedParts} · ${safeMessageName(state.name)}`, { signal: part.signal });
+    const attachment = message.attachments[0];
+    if (!attachment || attachment.size !== part.bytes.byteLength) {
+      await this.#transport.deleteMessage(message.id).catch(() => {
+        return;
+      });
+      throw new StorageError2("UPLOAD_FAILED", `Discord returned an invalid multipart part`);
+    }
+    return {
+      index: part.index,
+      size: part.bytes.byteLength,
+      sha256: bytesToHex(sha256(part.bytes)),
+      locator: {
+        messageId: message.id,
+        attachmentId: attachment.id,
+        filename: attachment.filename,
+        contentType: attachment.content_type,
+        width: attachment.width,
+        height: attachment.height
+      }
+    };
+  }
+  async completeMultipart(session, parts, file, options) {
+    const state = parseMultipartState(session.state, this.#connectionId);
+    if (file.name !== state.name || file.contentType !== state.contentType || file.size !== state.size || !/^[a-f0-9]{64}$/.test(file.sha256)) {
+      throw new StorageError2("INVALID_INPUT", "Completed file metadata does not match the session");
+    }
+    validatePreview(options.preview, this.#partSize);
+    const sorted = parts.toSorted((left, right) => left.index - right.index);
+    const expectedParts = Math.ceil(file.size / this.#partSize);
+    if (sorted.length !== expectedParts) {
+      throw new StorageError2("INVALID_INPUT", `Expected ${expectedParts} multipart parts`);
+    }
+    const chunks = sorted.map((part, index) => {
+      const locator = parseMultipartPartLocator(part.locator);
+      const expectedSize = index === expectedParts - 1 ? file.size - index * this.#partSize : this.#partSize;
+      if (part.index !== index || part.size !== expectedSize || !/^[a-f0-9]{64}$/.test(part.sha256)) {
+        throw new StorageError2("INTEGRITY_FAILED", `Multipart part ${index} is invalid`);
+      }
+      return { index, size: part.size, sha256: part.sha256, ...locator };
+    });
+    const createdMessageIds = new Set;
+    try {
+      const nativePreview = chunks.length === 1 ? previewFromMultipartPart(sorted[0], state.contentType) : undefined;
+      const preview = options.preview ? await this.#uploadPreview(state.name, options.preview, createdMessageIds, options.signal) : nativePreview;
+      const manifest = {
+        version: 1,
+        uploadId: state.uploadId,
+        connectionId: state.connectionId,
+        name: state.name,
+        contentType: state.contentType,
+        size: state.size,
+        sha256: file.sha256,
+        partSize: this.#partSize,
+        createdAt: state.createdAt,
+        chunks,
+        preview
+      };
+      const envelope = {
+        version: 1,
+        algorithm: "HMAC-SHA256",
+        manifest,
+        signature: await signManifest(manifest, this.#secret)
+      };
+      const manifestFile = new File([JSON.stringify(envelope)], `${state.uploadId}.manifest.json`, {
+        type: "application/json"
+      });
+      const message = await this.#transport.uploadAttachments([manifestFile], `Storage manifest · ${safeMessageName(state.name)} · ${chunks.length} parts`, { signal: options.signal });
+      createdMessageIds.add(message.id);
+      const attachment = message.attachments[0];
+      if (!attachment || attachment.size !== manifestFile.size) {
+        throw new StorageError2("UPLOAD_FAILED", "Discord returned an invalid manifest attachment");
+      }
+      this.#manifestCache.set(message.id, {
+        manifest,
+        expiresAt: Date.now() + MANIFEST_CACHE_MS
+      });
+      return toReceipt(manifest, message.id, message.channel_id, attachment.id);
+    } catch (error) {
+      await Promise.allSettled([...createdMessageIds].map((messageId) => this.#transport.deleteMessage(messageId)));
+      throw error;
+    }
+  }
+  async abortMultipart(session, parts) {
+    parseMultipartState(session.state, this.#connectionId);
+    const messageIds = new Set(parts.map((part) => parseMultipartPartLocator(part.locator).messageId));
+    const results = await Promise.allSettled([...messageIds].map((messageId) => this.#transport.deleteMessage(messageId)));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length > 0) {
+      throw new StorageError2("DELETE_FAILED", `Could not abort ${failures.length} Discord multipart messages`, { cause: failures });
+    }
+  }
+  async open(receipt, options = {}) {
+    const manifest = await this.#getManifest(receipt, options.signal);
+    let range;
+    try {
+      range = parseByteRange(options.range, manifest.size);
+    } catch (error) {
+      if (error instanceof RangeNotSatisfiableError) {
+        return new Response(null, {
+          status: 416,
+          headers: { "Content-Range": `bytes */${manifest.size}` }
+        });
+      }
+      throw error;
+    }
+    const start = range?.start ?? 0;
+    const requestedEnd = range?.end ?? manifest.size - 1;
+    const media = isStreamableMedia(manifest.contentType) && !options.download;
+    const end = media ? Math.min(requestedEnd, start + this.#mediaWindowBytes - 1) : requestedEnd;
+    const partial = Boolean(range) || end < manifest.size - 1;
+    const length = end - start + 1;
+    const headers = new Headers({
+      "Accept-Ranges": "bytes",
+      "Cache-Control": "public, max-age=31536000, immutable",
+      "Content-Length": String(length),
+      "Content-Type": manifest.contentType,
+      "Content-Disposition": contentDisposition(manifest.name, options.download ?? false),
+      ETag: `"sha256-${manifest.sha256}"`,
+      "X-Content-Type-Options": "nosniff",
+      "X-Storage-Provider": "discord",
+      "X-Storage-Parts": String(manifest.chunks.length)
+    });
+    if (partial)
+      headers.set("Content-Range", `bytes ${start}-${end}/${manifest.size}`);
+    if (options.method === "HEAD")
+      return new Response(null, { status: partial ? 206 : 200, headers });
+    return new Response(this.#streamRange(manifest, start, end, options.signal), {
+      status: partial ? 206 : 200,
+      headers
+    });
+  }
+  async preview(receipt, options = {}) {
+    const manifest = await this.#getManifest(receipt, options.signal);
+    if (!manifest.preview) {
+      throw new StorageError2("READ_FAILED", "This Discord resource has no preview", {
+        status: 404
+      });
+    }
+    const location = await this.previewUrl(receipt, options);
+    return new Response(null, {
+      status: 307,
+      headers: { Location: location, "Cache-Control": "no-store" }
+    });
+  }
+  async previewUrl(receipt, options = {}) {
+    const manifest = await this.#getManifest(receipt, options.signal);
+    if (!manifest.preview) {
+      throw new StorageError2("READ_FAILED", "This Discord resource has no preview", {
+        status: 404
+      });
+    }
+    const freshUrl = await this.#transport.getFreshAttachmentUrl(manifest.preview.messageId, manifest.preview.attachmentId, { proxy: true, signal: options.signal });
+    const url = new URL(freshUrl);
+    const dimensions = normalizedDimensions(manifest.preview, options.width, options.height);
+    if (dimensions) {
+      url.searchParams.set("width", String(dimensions.width));
+      url.searchParams.set("height", String(dimensions.height));
+    }
+    if (options.format)
+      url.searchParams.set("format", options.format);
+    if (options.quality)
+      url.searchParams.set("quality", options.quality);
+    return url.toString();
+  }
+  async refresh(receipt) {
+    const manifest = await this.#getManifest(receipt);
+    const parts = await Promise.all(manifest.chunks.map((chunk) => this.#transport.getFreshAttachmentUrl(chunk.messageId, chunk.attachmentId)));
+    const preview = manifest.preview ? await this.#transport.getFreshAttachmentUrl(manifest.preview.messageId, manifest.preview.attachmentId, { proxy: true }) : undefined;
+    return { expires: true, parts, preview };
+  }
+  async delete(receipt, options = {}) {
+    const manifest = await this.#getManifest(receipt, options.signal);
+    const contentMessageIds = new Set([
+      ...manifest.chunks.map((chunk) => chunk.messageId),
+      ...manifest.preview ? [manifest.preview.messageId] : []
+    ]);
+    const results = await Promise.allSettled([...contentMessageIds].map((messageId) => this.#transport.deleteMessage(messageId, { signal: options.signal })));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length > 0) {
+      throw new StorageError2("DELETE_FAILED", `Could not delete ${failures.length} Discord content messages`, { status: 502, cause: failures });
+    }
+    await this.#transport.deleteMessage(receipt.locator.manifestMessageId, {
+      signal: options.signal
+    });
+    this.#manifestCache.delete(receipt.locator.manifestMessageId);
+  }
+  async#uploadChunkBatch(pending, source, totalParts, createdMessageIds, signal) {
+    const first = pending[0];
+    const last = pending[pending.length - 1];
+    if (!first || !last)
+      return [];
+    const directImage = totalParts === 1 && source.contentType.startsWith("image/");
+    const description = directImage ? `Storage original + preview · ${safeMessageName(source.name)}` : `Storage parts ${first.index + 1}-${last.index + 1}/${totalParts} · ${safeMessageName(source.name)}`;
+    const message = await this.#transport.uploadAttachments(pending.map((chunk) => chunk.file), description, { signal });
+    createdMessageIds.add(message.id);
+    return pending.map((chunk) => {
+      const attachment = message.attachments.find((candidate) => candidate.filename === chunk.filename);
+      if (!attachment || attachment.size !== chunk.bytes.byteLength) {
+        throw new StorageError2("UPLOAD_FAILED", `Discord returned an invalid attachment for part ${chunk.index + 1}`);
+      }
+      return {
+        index: chunk.index,
+        size: chunk.bytes.byteLength,
+        sha256: chunk.sha256,
+        messageId: message.id,
+        attachmentId: attachment.id,
+        filename: attachment.filename
+      };
+    });
+  }
+  async#uploadPreview(sourceName, generated, createdMessageIds, signal) {
+    const message = await this.#transport.uploadAttachments([generated.file], `Storage preview · ${safeMessageName(sourceName)} · ${generated.width}×${generated.height}`, { signal });
+    createdMessageIds.add(message.id);
+    const attachment = message.attachments[0];
+    if (!attachment || attachment.size !== generated.file.size) {
+      throw new StorageError2("UPLOAD_FAILED", "Discord returned an invalid preview attachment");
+    }
+    return {
+      size: attachment.size,
+      contentType: generated.file.type,
+      width: generated.width,
+      height: generated.height,
+      messageId: message.id,
+      attachmentId: attachment.id,
+      filename: attachment.filename
+    };
+  }
+  async#getManifest(receipt, signal) {
+    validateReceipt(receipt, this.#connectionId);
+    const messageId = receipt.locator.manifestMessageId;
+    const cached = this.#manifestCache.get(messageId);
+    if (cached && cached.expiresAt > Date.now()) {
+      validateManifest(cached.manifest, receipt);
+      this.#logger?.debug?.("manifest.cache.hit", { messageId });
+      return cached.manifest;
+    }
+    this.#logger?.debug?.("manifest.cache.miss", { messageId });
+    let url = await this.#transport.getFreshAttachmentUrl(messageId, receipt.locator.manifestAttachmentId, { signal });
+    let response = await this.#fetch(url, { signal });
+    if (!response.ok) {
+      this.#logger?.warn?.("manifest.cdn_url.refresh", { messageId, status: response.status });
+      this.#transport.invalidateMessage(messageId);
+      url = await this.#transport.getFreshAttachmentUrl(messageId, receipt.locator.manifestAttachmentId, { signal });
+      response = await this.#fetch(url, { signal });
+    }
+    if (!response.ok) {
+      throw new StorageError2("READ_FAILED", "Could not load the Discord storage manifest", {
+        status: 502
+      });
+    }
+    const envelope = discordManifestEnvelopeSchema.parse(await response.json());
+    if (!await verifyManifestSignature(envelope.manifest, envelope.signature, this.#secret)) {
+      throw new StorageError2("INTEGRITY_FAILED", "Discord manifest signature is invalid", {
+        status: 409
+      });
+    }
+    validateManifest(envelope.manifest, receipt);
+    this.#manifestCache.set(messageId, {
+      manifest: envelope.manifest,
+      expiresAt: Date.now() + MANIFEST_CACHE_MS
+    });
+    this.#logger?.debug?.("manifest.signature.verified", {
+      messageId,
+      parts: envelope.manifest.chunks.length
+    });
+    return envelope.manifest;
+  }
+  #streamRange(manifest, start, end, parentSignal) {
+    const abortController = new AbortController;
+    parentSignal?.addEventListener("abort", () => abortController.abort(parentSignal.reason), {
+      once: true
+    });
+    const iterator = this.#chunkIterator(manifest, start, end, abortController.signal);
+    return new ReadableStream({
+      async pull(controller) {
+        try {
+          const next = await iterator.next();
+          if (next.done)
+            controller.close();
+          else
+            controller.enqueue(next.value);
+        } catch (error) {
+          controller.error(error);
+        }
+      },
+      async cancel(reason) {
+        abortController.abort(reason);
+        await iterator.return?.(undefined);
+      }
+    });
+  }
+  async* #chunkIterator(manifest, start, end, signal) {
+    let chunkOffset = 0;
+    for (const chunk of manifest.chunks) {
+      const chunkEnd = chunkOffset + chunk.size - 1;
+      if (chunkEnd < start) {
+        chunkOffset += chunk.size;
+        continue;
+      }
+      if (chunkOffset > end)
+        break;
+      const localStart = Math.max(0, start - chunkOffset);
+      const localEnd = Math.min(chunk.size - 1, end - chunkOffset);
+      yield* this.#readChunk(chunk, localStart, localEnd, signal);
+      chunkOffset += chunk.size;
+    }
+  }
+  async* #readChunk(chunk, start, end, signal) {
+    const length = end - start + 1;
+    let response;
+    for (let attempt = 0;attempt < 2; attempt += 1) {
+      const url = await this.#transport.getFreshAttachmentUrl(chunk.messageId, chunk.attachmentId, {
+        signal
+      });
+      response = await this.#fetch(url, {
+        headers: start === 0 && end === chunk.size - 1 ? undefined : { Range: `bytes=${start}-${end}` },
+        signal
+      });
+      if (response.ok)
+        break;
+      this.#transport.invalidateMessage(chunk.messageId);
+    }
+    if (!response?.ok || !response.body) {
+      throw new StorageError2("READ_FAILED", `Discord CDN failed while reading part ${chunk.index}`);
+    }
+    const skip = response.status === 206 ? 0 : start;
+    if (response.status !== 206 && (start > 0 || end < chunk.size - 1)) {
+      this.#logger?.warn?.("cdn.range.fallback", {
+        messageId: chunk.messageId,
+        part: chunk.index,
+        upstreamStatus: response.status,
+        start,
+        end
+      });
+    }
+    const reader = response.body.getReader();
+    let skipped = 0;
+    let emitted = 0;
+    try {
+      while (emitted < length) {
+        const result = await reader.read();
+        if (result.done)
+          break;
+        let from = 0;
+        if (skipped < skip) {
+          const amount2 = Math.min(result.value.byteLength, skip - skipped);
+          skipped += amount2;
+          from += amount2;
+        }
+        if (from >= result.value.byteLength)
+          continue;
+        const amount = Math.min(result.value.byteLength - from, length - emitted);
+        emitted += amount;
+        yield result.value.subarray(from, from + amount);
+      }
+    } finally {
+      await reader.cancel().catch(() => {
+        return;
+      });
+    }
+    if (emitted !== length) {
+      throw new StorageError2("READ_FAILED", `Discord CDN returned a short part (${emitted}/${length})`);
+    }
+  }
+}
+function createDiscordProvider(options) {
+  return new DiscordStorageProvider(options);
+}
+function toReceipt(manifest, manifestMessageId, channelId, manifestAttachmentId) {
+  return {
+    version: 1,
+    provider: "discord",
+    connectionId: manifest.connectionId,
+    createdAt: manifest.createdAt,
+    file: {
+      name: manifest.name,
+      contentType: manifest.contentType,
+      size: manifest.size,
+      sha256: manifest.sha256
+    },
+    locator: { channelId, manifestMessageId, manifestAttachmentId },
+    preview: manifest.preview ? previewSummary(manifest.preview) : undefined
+  };
+}
+function previewSummary(preview) {
+  return {
+    contentType: preview.contentType,
+    size: preview.size,
+    width: preview.width,
+    height: preview.height
+  };
+}
+function validateReceipt(receipt, connectionId) {
+  const locator = discordReceiptLocatorSchema.safeParse(receipt.locator);
+  if (receipt.version !== 1 || receipt.provider !== "discord" || receipt.connectionId !== connectionId || !locator.success) {
+    throw new StorageError2("INVALID_RECEIPT", "Receipt does not belong to this Discord provider", {
+      status: 400,
+      cause: locator.success ? undefined : locator.error
+    });
+  }
+}
+function validateManifest(manifest, receipt) {
+  let size = 0;
+  for (const [index, chunk] of manifest.chunks.entries()) {
+    if (chunk.index !== index) {
+      throw new StorageError2("INTEGRITY_FAILED", "Discord manifest parts are out of order");
+    }
+    size += chunk.size;
+  }
+  if (size !== manifest.size || manifest.connectionId !== receipt.connectionId || manifest.name !== receipt.file.name || manifest.contentType !== receipt.file.contentType || manifest.size !== receipt.file.size || manifest.sha256 !== receipt.file.sha256) {
+    throw new StorageError2("INTEGRITY_FAILED", "Discord manifest does not match its receipt");
+  }
+}
+function validatePreview(preview, attachmentLimit) {
+  if (!preview)
+    return;
+  if (!preview.file.type.startsWith("image/")) {
+    throw new StorageError2("INVALID_INPUT", "Preview must be an image", { status: 400 });
+  }
+  if (preview.file.size <= 0 || preview.file.size > attachmentLimit) {
+    throw new StorageError2("FILE_TOO_LARGE", `Preview must be between 1 and ${attachmentLimit} bytes`, { status: 413 });
+  }
+  if (!Number.isInteger(preview.width) || preview.width <= 0) {
+    throw new StorageError2("INVALID_INPUT", "Preview width must be a positive integer");
+  }
+  if (!Number.isInteger(preview.height) || preview.height <= 0) {
+    throw new StorageError2("INVALID_INPUT", "Preview height must be a positive integer");
+  }
+}
+function normalizedDimensions(preview, width, height) {
+  if (width !== undefined && (!Number.isInteger(width) || width <= 0 || width > 1e4)) {
+    throw new StorageError2("INVALID_INPUT", "Preview width must be between 1 and 10000");
+  }
+  if (height !== undefined && (!Number.isInteger(height) || height <= 0 || height > 1e4)) {
+    throw new StorageError2("INVALID_INPUT", "Preview height must be between 1 and 10000");
+  }
+  if (width && height)
+    return { width, height };
+  if (width)
+    return { width, height: Math.max(1, Math.round(width * preview.height / preview.width)) };
+  if (height)
+    return { width: Math.max(1, Math.round(height * preview.width / preview.height)), height };
+  return;
+}
+function exactArrayBuffer(bytes) {
+  if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+    return bytes.buffer;
+  }
+  return bytes.slice().buffer;
+}
+function boundedInteger(value, minimum, maximum, name) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new StorageError2("INVALID_INPUT", `${name} must be an integer between ${minimum} and ${maximum}`);
+  }
+  return value;
+}
+function isStreamableMedia(contentType) {
+  return contentType.startsWith("video/") || contentType.startsWith("audio/");
+}
+function contentDisposition(filename, download) {
+  const disposition = download ? "attachment" : "inline";
+  const fallback = filename.replace(/[^\x20-\x7E]/g, "_").replace(/["\\]/g, "_");
+  return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+function safeMessageName(filename) {
+  return filename.replace(/[@`]/g, "_").slice(0, 160);
+}
+function parseMultipartState(value, connectionId) {
+  if (!value || typeof value !== "object") {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart session state is invalid");
+  }
+  const state = value;
+  if (state.version !== 1 || typeof state.uploadId !== "string" || typeof state.connectionId !== "string" || state.connectionId !== connectionId || typeof state.name !== "string" || typeof state.contentType !== "string" || !Number.isSafeInteger(state.size) || (state.size ?? 0) <= 0 || typeof state.createdAt !== "string") {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart session state is invalid");
+  }
+  return state;
+}
+function parseMultipartPartLocator(value) {
+  if (!value || typeof value !== "object") {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart part locator is invalid");
+  }
+  const locator = value;
+  if (typeof locator.messageId !== "string" || typeof locator.attachmentId !== "string" || typeof locator.filename !== "string") {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart part locator is invalid");
+  }
+  if (locator.width !== undefined && (!Number.isInteger(locator.width) || locator.width <= 0)) {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart preview width is invalid");
+  }
+  if (locator.height !== undefined && (!Number.isInteger(locator.height) || locator.height <= 0)) {
+    throw new StorageError2("INVALID_INPUT", "Discord multipart preview height is invalid");
+  }
+  return locator;
+}
+function previewFromMultipartPart(part, fallbackContentType) {
+  if (!part)
+    return;
+  const locator = parseMultipartPartLocator(part.locator);
+  if (!locator.width || !locator.height)
+    return;
+  return {
+    size: part.size,
+    contentType: locator.contentType ?? fallbackContentType,
+    width: locator.width,
+    height: locator.height,
+    messageId: locator.messageId,
+    attachmentId: locator.attachmentId,
+    filename: locator.filename
+  };
+}
+export {
+  discordReceiptLocatorSchema,
+  discordPreviewLocatorSchema,
+  discordMessageSchema,
+  discordManifestSchema,
+  discordManifestEnvelopeSchema,
+  discordChunkSchema,
+  discordAttachmentSchema,
+  createDiscordProvider,
+  DiscordWebhookTransport,
+  DiscordStorageProvider
+};

package/dist/provider.d.ts

@@ -0,0 +1,60 @@
+import { type ProviderMultipartPart, type ProviderMultipartSession, type ProviderCapabilities, type ProviderUploadOptions, type RefreshedProviderLinks, type StorageOpenOptions, type StoragePreviewOptions, type StorageProvider, type StorageUploadSource } from "@minhvuong/pirate-storage";
+import { type DiscordTransport } from "./transport";
+import { type DiscordLogger, type DiscordMultipartPartLocator, type DiscordMultipartState, type DiscordReceipt } from "./types";
+export interface DiscordProviderOptions {
+    webhookUrl?: string;
+    transport?: DiscordTransport;
+    manifestSecret: string | Uint8Array;
+    connectionId?: string;
+    partSize?: number;
+    maxFileSize?: number;
+    attachmentsPerMessage?: number;
+    uploadConcurrency?: number;
+    mediaWindowBytes?: number;
+    fetch?: typeof globalThis.fetch;
+    logger?: DiscordLogger;
+}
+export declare class DiscordStorageProvider implements StorageProvider<DiscordReceipt, DiscordMultipartState, DiscordMultipartPartLocator> {
+    #private;
+    readonly id: "discord";
+    readonly capabilities: ProviderCapabilities;
+    constructor(options: DiscordProviderOptions);
+    upload(source: StorageUploadSource, options: ProviderUploadOptions): Promise<DiscordReceipt>;
+    stat(receipt: DiscordReceipt): Promise<{
+        name: string;
+        contentType: string;
+        size: number;
+        sha256: string;
+        preview: {
+            contentType: string;
+            size: number;
+            width: number;
+            height: number;
+        } | undefined;
+    }>;
+    beginMultipart(file: {
+        name: string;
+        contentType: string;
+        size: number;
+    }, _options: ProviderUploadOptions): Promise<ProviderMultipartSession<DiscordMultipartState>>;
+    uploadPart(session: ProviderMultipartSession<DiscordMultipartState>, part: {
+        index: number;
+        bytes: Uint8Array;
+        signal?: AbortSignal;
+    }): Promise<ProviderMultipartPart<DiscordMultipartPartLocator>>;
+    completeMultipart(session: ProviderMultipartSession<DiscordMultipartState>, parts: ProviderMultipartPart<DiscordMultipartPartLocator>[], file: {
+        name: string;
+        contentType: string;
+        size: number;
+        sha256: string;
+    }, options: ProviderUploadOptions): Promise<DiscordReceipt>;
+    abortMultipart(session: ProviderMultipartSession<DiscordMultipartState>, parts: ProviderMultipartPart<DiscordMultipartPartLocator>[]): Promise<void>;
+    open(receipt: DiscordReceipt, options?: StorageOpenOptions): Promise<Response>;
+    preview(receipt: DiscordReceipt, options?: StoragePreviewOptions): Promise<Response>;
+    previewUrl(receipt: DiscordReceipt, options?: StoragePreviewOptions): Promise<string>;
+    refresh(receipt: DiscordReceipt): Promise<RefreshedProviderLinks>;
+    delete(receipt: DiscordReceipt, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export declare function createDiscordProvider(options: DiscordProviderOptions): DiscordStorageProvider;

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+import { type DiscordLogger, type DiscordMessage } from "./types";
+export interface DiscordTransport {
+    readonly connectionId: string;
+    uploadAttachments(files: readonly File[], description: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DiscordMessage>;
+    getFreshAttachmentUrl(messageId: string, attachmentId?: string, options?: {
+        proxy?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    getMessage(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DiscordMessage>;
+    invalidateMessage(messageId: string): void;
+    deleteMessage(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export declare class DiscordWebhookTransport implements DiscordTransport {
+    #private;
+    readonly connectionId: string;
+    constructor(webhookUrl: string, fetchImplementation?: typeof globalThis.fetch, logger?: DiscordLogger);
+    uploadAttachments(files: readonly File[], description: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DiscordMessage>;
+    getFreshAttachmentUrl(messageId: string, attachmentId?: string, options?: {
+        proxy?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    invalidateMessage(messageId: string): void;
+    deleteMessage(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    getMessage(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DiscordMessage>;
+}

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+import type { StorageReceipt } from "@minhvuong/pirate-storage";
+import { z } from "zod";
+export declare const discordAttachmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    filename: z.ZodString;
+    size: z.ZodNumber;
+    url: z.ZodString;
+    proxy_url: z.ZodOptional<z.ZodString>;
+    content_type: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const discordMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    channel_id: z.ZodString;
+    attachments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        filename: z.ZodString;
+        size: z.ZodNumber;
+        url: z.ZodString;
+        proxy_url: z.ZodOptional<z.ZodString>;
+        content_type: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DiscordAttachment = z.infer<typeof discordAttachmentSchema>;
+export type DiscordMessage = z.infer<typeof discordMessageSchema>;
+export declare const discordChunkSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    size: z.ZodNumber;
+    sha256: z.ZodString;
+    messageId: z.ZodString;
+    attachmentId: z.ZodString;
+    filename: z.ZodString;
+}, z.core.$strip>;
+export declare const discordPreviewLocatorSchema: z.ZodObject<{
+    size: z.ZodNumber;
+    contentType: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    messageId: z.ZodString;
+    attachmentId: z.ZodString;
+    filename: z.ZodString;
+}, z.core.$strip>;
+export declare const discordManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    uploadId: z.ZodString;
+    connectionId: z.ZodString;
+    name: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodNumber;
+    sha256: z.ZodString;
+    partSize: z.ZodNumber;
+    createdAt: z.ZodString;
+    chunks: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        size: z.ZodNumber;
+        sha256: z.ZodString;
+        messageId: z.ZodString;
+        attachmentId: z.ZodString;
+        filename: z.ZodString;
+    }, z.core.$strip>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        size: z.ZodNumber;
+        contentType: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        messageId: z.ZodString;
+        attachmentId: z.ZodString;
+        filename: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const discordManifestEnvelopeSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    algorithm: z.ZodLiteral<"HMAC-SHA256">;
+    manifest: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        uploadId: z.ZodString;
+        connectionId: z.ZodString;
+        name: z.ZodString;
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+        sha256: z.ZodString;
+        partSize: z.ZodNumber;
+        createdAt: z.ZodString;
+        chunks: z.ZodArray<z.ZodObject<{
+            index: z.ZodNumber;
+            size: z.ZodNumber;
+            sha256: z.ZodString;
+            messageId: z.ZodString;
+            attachmentId: z.ZodString;
+            filename: z.ZodString;
+        }, z.core.$strip>>;
+        preview: z.ZodOptional<z.ZodObject<{
+            size: z.ZodNumber;
+            contentType: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            messageId: z.ZodString;
+            attachmentId: z.ZodString;
+            filename: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    signature: z.ZodString;
+}, z.core.$strip>;
+export declare const discordReceiptLocatorSchema: z.ZodObject<{
+    channelId: z.ZodString;
+    manifestMessageId: z.ZodString;
+    manifestAttachmentId: z.ZodString;
+}, z.core.$strip>;
+export type DiscordChunk = z.infer<typeof discordChunkSchema>;
+export type DiscordPreviewLocator = z.infer<typeof discordPreviewLocatorSchema>;
+export type DiscordManifest = z.infer<typeof discordManifestSchema>;
+export type DiscordManifestEnvelope = z.infer<typeof discordManifestEnvelopeSchema>;
+export type DiscordReceiptLocator = z.infer<typeof discordReceiptLocatorSchema>;
+export type DiscordReceipt = StorageReceipt<"discord", DiscordReceiptLocator>;
+export interface DiscordMultipartState {
+    version: 1;
+    uploadId: string;
+    connectionId: string;
+    name: string;
+    contentType: string;
+    size: number;
+    createdAt: string;
+}
+export interface DiscordMultipartPartLocator {
+    messageId: string;
+    attachmentId: string;
+    filename: string;
+    contentType?: string;
+    width?: number;
+    height?: number;
+}
+export interface DiscordLogger {
+    debug?(message: string, context?: Readonly<Record<string, unknown>>): void;
+    warn?(message: string, context?: Readonly<Record<string, unknown>>): void;
+    error?(message: string, context?: Readonly<Record<string, unknown>>): void;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@minhvuong/pirate-storage-discord",
+  "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": {
+    "@minhvuong/pirate-storage": "workspace:*",
+    "@noble/hashes": "^2.0.1",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "typescript": "catalog:"
+  }
+}