@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
• upload-level webhook pooling with durable receipt routing
• 2–10 native images in one Discord message with one group receipt

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.

Multiple webhooks

Use a webhook pool to spread complete uploads across independent Discord webhook rate-limit buckets. The default least-busy strategy selects the connection with the fewest active SDK operations and round-robins ties. round-robin is also available for fully deterministic routing.

import { createDiscordProvider } from "@minhvuong/pirate-storage-discord";

const discord = createDiscordProvider({
  webhooks: [
    env.DISCORD_WEBHOOK_PRIMARY,
    env.DISCORD_WEBHOOK_SECONDARY,
    env.DISCORD_WEBHOOK_TERTIARY,
  ],
  strategy: "least-busy", // default; or "round-robin"
  manifestSecret: env.STORAGE_MANIFEST_SECRET,
});

Image groups

const receipt = await storage.uploadGroup([image1, image2, image3], {
  provider: "discord",
});

const response = await storage.openGroupItem(receipt, receipt.items[0].id);
await storage.deleteGroup(receipt); // deletes every image in the group

Discord receives one message containing all 2–10 image attachments. The SDK stores its signed manifest in a second message and exposes both as one durable receipt. The configured partSize applies to every image separately—8 MiB per image by default, with a validated 10 MiB ceiling. A grouped image cannot be chunked because it must remain one native Discord attachment.

Discord may strip image metadata while creating native attachments. Group items therefore report exactOriginal: false and expose the provider-side byte count through item.stored.size; the source hash and size remain available under item.file as the durable upload identity.

Partial group deletion is intentionally not supported. Use separate uploads when files need independent lifecycles.

One webhook owns the complete upload: every part, generated preview, and manifest stays on that connection. The durable receipt stores only a safe identity such as connectionId: "webhook:123456789"; it never stores the webhook URL or token. Later calls to stat, open, preview, refresh, multipart resume/rollback, and delete route through that identity automatically.

Keep every webhook needed by existing receipts in the pool after a process restart. Removing a webhook credential means the SDK can no longer manage messages created by that webhook.

The original single-webhook configuration remains supported:

const discord = createDiscordProvider({
  webhookUrl: env.DISCORD_WEBHOOK_URL,
  manifestSecret: env.STORAGE_MANIFEST_SECRET,
});