Skip to main content
Home
Browse packagesDocs
ImageSign In with GitHubImageSign In with GitLab

@gramio/files@0.6.1
Built and signed on GitHub Actions

latest
gramiojs/files
Works with
This package works with Node.js, Deno, Bun, BrowsersIt is unknown whether this package works with Cloudflare Workers
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Bun
This package works with Browsers
•JSR Score100%•
License
MIT
•
Downloads1/wk
•
Published3 weeks ago (0.6.1)

Set of utils for work with files and Telegram Bot API

Examples

Example 1

import { MediaInput, MediaUpload } from "@gramio/files";

// method for sendMediaGroup
context.sendMediaGroup([
     MediaInput.document(
         MediaUpload.url(
             "https://raw.githubusercontent.com/gramiojs/types/main/README.md"
         )
     ),
     MediaInput.document(MediaUpload.path("./package.json")),
]);

Classes

c
MediaInput

Class-helper with static methods that represents the content of a media message to be sent.

  • animation(
    media: TelegramInputMediaAnimation["media"],
    options?: Omit<TelegramInputMediaAnimation, "media" | "type">
    ): TelegramInputMediaAnimation

    Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent.

  • audio(
    media: TelegramInputMediaAudio["media"],
    options?: Omit<TelegramInputMediaAudio, "media" | "type">
    ): TelegramInputMediaAudio

    Represents an audio file to be treated as music to be sent.

  • document(
    media: TelegramInputMediaDocument["media"],
    options?: Omit<TelegramInputMediaDocument, "media" | "type">
    ): TelegramInputMediaDocument

    Represents a general file to be sent.

  • photo(
    media: TelegramInputMediaPhoto["media"],
    options?: Omit<TelegramInputMediaPhoto, "media" | "type">
    ): TelegramInputMediaPhoto

    Represents a photo to be sent.

  • video(
    media: TelegramInputMediaVideo["media"],
    options?: Omit<TelegramInputMediaVideo, "media" | "type">
    ): TelegramInputMediaVideo

    Represents a video to be sent.

c
MediaUpload

Class-helper with static methods for file uploading.

  • buffer(
    buffer: Exclude<BufferSource | ArrayBuffer, string>,
    filename?: string
    ): File

    Method for uploading Media File by BinaryLike (Buffer or ArrayBuffer and etc).

  • localPath(path: string): string

    Reference a file by its local path on a self-hosted Bot API server (--local mode) using the file:// URI scheme. The server reads the file straight from its own disk, so the bytes are never transferred over HTTP.

  • path(
    path: string,
    filename?: string
    ): Promise<File>

    Method for uploading Media File by local path.

  • stream(
    stream: Readable | ReadableStream,
    filename?: string
    ): Promise<File>

    Method for uploading Media File by Readable stream.

  • text(
    text: string,
    filename?: string
    ): File

    Method for uploading Media File by text content.

  • url(
    url: URL | string,
    filename?: string,
    options?: RequestInit
    ): Promise<File>

    Method for uploading Media File by URL (also with fetch options).

c
TelegramFileDownload(resolver: FileDownloadResolver)

Lazy, Response-like handle for downloading a Telegram file.

  • arrayBuffer(): Promise<ArrayBuffer>

    The whole file as an ArrayBuffer.

  • blob(): Promise<Blob>

    The whole file as a Blob.

  • bytes(): Promise<Uint8Array>

    The whole file as a Uint8Array.

  • info(): Promise<TelegramFile>

    The getFile metadata (file_id, file_path, file_size, …). Does not read the body.

  • json<T = unknown>(): Promise<T>

    The file parsed as JSON.

  • link(): Promise<string>

    A download URL for the file. Does not read the body.

  • resolve(): Promise<{ file: TelegramFile; source: FileDownloadSource; }>
    No documentation available
  • response(): Promise<Response>
    No documentation available
  • stream(): Promise<ReadableStream<Uint8Array>>

    A web ReadableStream of the file — pipe large files without buffering.

  • text(): Promise<string>

    The file decoded as UTF-8 text.

  • then<TResult1 = ArrayBuffer, TResult2 = never>(
    onfulfilled?:
    ((value: ArrayBuffer) => TResult1 | PromiseLike<TResult1>)
    | null,
    onrejected?:
    ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
    | null
    ): Promise<TResult1 | TResult2>

    PromiseLike: await download resolves the file bytes (back-compatible).

  • toFile(path: string): Promise<string>

    Save the file to path and return it. Copies on disk when possible (no extra transfer).

Functions

f
convertJsonToFormData<T extends keyof APIMethods>(
method: T,
params: NonNullable<APIMethodParams<T>>
): Promise<FormData>

Helper to convert JSON to FormData that can accept Telegram Bot API. if File is not top-level property it will be “attach://<file_attach_name>”

f
convertStreamToBuffer(stream: Readable): Promise<Buffer>

Helper for convert Readable stream to buffer

f
downloadFile(
bot: FileDownloadBot,
attachment: DownloadFileInput,
path?: string
): TelegramFileDownload | Promise<string>
2 overloads

Download a Telegram file. Returns a TelegramFileDownload handle (.bytes(), .text(), .json(), .blob(), .stream(), .toFile(), .link(), .info(); await it for an ArrayBuffer). Pass path to save straight to disk and get the path back.

f
extractFilesToFormData<T extends keyof APIMethods>(
method: T,
params: NonNullable<APIMethodParams<T>>
): Promise<[FormData | undefined, NonNullable<APIMethodParams<T>>]>

Helper to extract files from params and convert them to FormData. (Similar to convertJsonToFormData) if File is not top-level property it will be “attach://<file_attach_name>”

f
isBlob(blob?: TelegramInputFile | object | string): boolean

Guard to check is it Blob or Promise

f
isMediaUpload<T extends keyof APIMethods>(
method: T,
params: NonNullable<APIMethodParams<T>>
): boolean

Guard to check is method used for File Uploading

Interfaces

I
FileDownloadBot

The minimal Bot-shaped object downloadFile needs. The GramIO Bot satisfies it structurally, so you just pass the instance — and a custom "without gramio" wrapper can pass any object of this shape.

  • api: { getFile(params: { file_id: string; }): Promise<TelegramFile> | TelegramFile; }
    No documentation available
  • options: { token: string; api: { baseURL: string; }; files?: { source?: FileSource; localDir?: string; mountDir?: string; baseURL?: string; }; }
    No documentation available

Type Aliases

T
DownloadFileInput =
string
| { file_id: string; }
| { fileId: string; }
| { bigSize: { fileId: string; }; }

Anything downloadFile can turn into a file_id.

T
FileDownloadResolver = () => Promise<{ file: TelegramFile; source: FileDownloadSource; }>

Lazily resolves the file metadata + where to read it from.

T
FileDownloadSource =
{ type: "url"; url: string; }
| { type: "disk"; path: string; }
| { type: "data"; data: ArrayBuffer | Uint8Array; }

A resolved file location used by TelegramFileDownload.

T
FileSource =
"auto"
| "url"
| "disk"
| "rewrite"
| ((file: TelegramFile) => Promise<ArrayBuffer> | ArrayBuffer)

Strategy for how downloadFile obtains file bytes — mainly relevant with a local Bot API server (--local), where getFile returns an absolute path on the server's disk instead of a URL.

Variables

v
MEDIA_METHODS: MethodsWithMediaUpload

A set of methods with the function of checking whether a File has been passed in the parameters

Report package

Please provide a reason for reporting this package. We will review your report and take appropriate action.

Please review the JSR usage policy before submitting a report.

Add Package

deno add jsr:@gramio/files

Import symbol

import * as Set_of_utils_for_work_with_files_and_Telegram_Bot_API___Documentation__https___gramio_dev_files_overview_html__ from "@gramio/files";
or

Import directly with a jsr specifier

import * as Set_of_utils_for_work_with_files_and_Telegram_Bot_API___Documentation__https___gramio_dev_files_overview_html__ from "jsr:@gramio/files";