@minhvuong/pirate-storage-telegram

Provider-neutral Telegram storage behavior for Pirate Storage. Runtime connections live in the companion server or Worker package.

Features include one-message MTProto uploads up to the configured Telegram limit, resumable and parallel browser parts, HMAC-signed caption manifests, Range streaming, native thumbnail/video-quality/cover discovery, deletion, custom thumbnails, and typed native modes: auto, document, photo, video, audio, voice, animation, and video-note.

const receipt = await storage.upload(file, {
  provider: "telegram",
  providerOptions: {
    mode: "video",
    width: 1920,
    height: 1080,
    duration: 42,
    supportsStreaming: true,
  },
});

return storage.toResponse(receipt, request); // HEAD, GET, and Range

Native image albums

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

const response = await storage.openGroupItem(receipt, receipt.items[0].id);
const preview = await storage.previewGroupItem(receipt, receipt.items[0].id, { width: 640 });
await storage.deleteGroup(receipt); // deletes the complete album and manifest

The provider sends 2–10 JPEG, PNG, or WebP images with Telegram's native sendMediaGroup flow. Telegram internally creates one message per album item but presents them as one grouped album. The SDK binds every message to one HMAC-signed group receipt and deletes the album as one lifecycle unit. Each image uses the same configured per-file MTProto limit as a standalone upload. Telegram's 10 MiB boundary only selects the small-file or big-file upload protocol; it is not a photo limit.

Partial album deletion is intentionally not supported. Upload images separately when they require independent deletion.

photo mode lets Telegram recompress the image, so receipt.telegram.exactOriginal is false. Use document when exact bytes matter. Auto mode sends ordinary images as photos, video as video, audio as audio, GIF as animation, and everything else as a document.

Temporary MTProto parts are not permanent objects. A durable journal can resume after a process reload while Telegram still retains the parts; an expired part set produces SESSION_EXPIRED and must be restarted.