Transport Grammy API reference

Build a {@link GrammyClient} over an injected grammY `Api` instance.

createGrammyClient(api: Api): GrammyClient

mapGrammyError(error: unknown): DeliveryResult<never>

Test-only: clear the dedup set between tests.

resetDiagnostics(): void

setDiagnosticHook(fn: ((e: DiagnosticEvent) => void) | null): void

warnDegraded(context: string, detail: string): void

warnNotImplemented(category: string, detail: string): void

warnUnexpected(context: string, detail: string, data?: Record<string, unknown>): void

Outcome of a single Bot API call. `ok` carries the method's parsed result; every other variant is a typed, non-throwing failure.

type DeliveryResult = DeliveryResult<T>

Result of an `editMessageText` call. A chat-message edit returns the updated `Message`; an inline-message edit returns the wire literal `true` (there is no message object) — modeled as an explicit DU, never `Message | undefined`.

type EditMessageResult = {
  readonly kind: "edited";
  readonly message: TelegramMessage;
} | {
  readonly kind: "inlineEdited";
}

Runtime diagnostics — the house alternative to deferred-work comments. Three functions: `warnNotImplemented`, `warnDegraded`, `warnUnexpected`. Each fires once per stable key (except `warnUnexpected`, which always fires), is greppable, and can be piped into a UI panel via {@link setDiagnosticHook}. Usage: warnDegraded("MyModule.fallback", "linear interp — cubic deferred, spec:120-140"); warnNotImplemented("MyModule.featureX", "spec §4 not yet lowered"); warnUnexpected("MyModule.parse", "expected number, got string", { value });

type DiagnosticKind = "not-implemented" | "degraded" | "unexpected"

A live-progress message handle.

interface LiveMessage

update(text: string): void

flush(): Promise<DeliveryResult<TelegramMessage>>

finish(finalText: string): Promise<DeliveryResult<TelegramMessage>>

A Telegram `Message`, projected to the branded ids the transport exposes.

interface TelegramMessage

messageId: MessageId

chatId: ChatId

date: number

The grammY-backed client surface — mirrors `@gramforge/transport-fetch`'s `BotClient`.

interface GrammyClient

sendMessage(args: SendMessageArgs): Promise<DeliveryResult<TelegramMessage>>

sendPhoto(args: SendPhotoArgs): Promise<DeliveryResult<TelegramMessage>>

editMessageText(args: EditMessageTextArgs): Promise<DeliveryResult<EditMessageResult>>

sendMediaGroup(args: SendMediaGroupArgs): Promise<DeliveryResult<readonly TelegramMessage[]>>

answerCallbackQuery(args: AnswerCallbackQueryArgs): Promise<DeliveryResult<true>>

liveMessage(args: LiveMessageArgs): LiveMessage

interface DiagnosticEvent

kind: DiagnosticKind

category: string

detail: string

stack: string

data: Record<string, unknown>

timestamp: number