# Transport Grammy API reference

> Exports of @gramforge/transport-grammy.

Source: https://gramforge.n.yatsyk.com/docs/transport-grammy/jsdoc

## Functions

### createGrammyClient

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

```ts
createGrammyClient(api: Api): GrammyClient
```

### mapGrammyError

```ts
mapGrammyError(error: unknown): DeliveryResult<never>
```

### resetDiagnostics

Test-only: clear the dedup set between tests.

```ts
resetDiagnostics(): void
```

### setDiagnosticHook

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

### warnDegraded

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

### warnNotImplemented

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

### warnUnexpected

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

## Types

### DeliveryResult

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

```ts
type DeliveryResult = DeliveryResult<T>
```

### EditMessageResult

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`.

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

### DiagnosticKind

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 });

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

## Interfaces

### LiveMessage

A live-progress message handle.

```ts
interface LiveMessage
```

- `update(text: string): void` — Record the latest text and schedule a debounced flush (synchronous).
- `flush(): Promise<DeliveryResult<TelegramMessage>>` — Force an immediate write of the pending text now, bypassing the debounce.
- `finish(finalText: string): Promise<DeliveryResult<TelegramMessage>>` — Write `finalText` once immediately and close the instance.

### TelegramMessage

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

```ts
interface TelegramMessage
```

- `messageId: MessageId`
- `chatId: ChatId`
- `date: number`

### GrammyClient

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

```ts
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`

### DiagnosticEvent

```ts
interface DiagnosticEvent
```

- `kind: DiagnosticKind`
- `category: string`
- `detail: string`
- `stack: string`
- `data: Record<string, unknown>`
- `timestamp: number`