Gramforge API reference

blockquote(...children: readonly Inline[]): BlockquoteNode

bold(...children: readonly Inline[]): BoldNode

code(value: string): CodeNode

expandableBlockquote(...children: readonly Inline[]): ExpandableBlockquoteNode

gram(strings: TemplateStringsArray, ...values: readonly GramValue[]): RichTextNode[]

italic(...children: readonly Inline[]): ItalicNode

link(href: string, ...children: readonly Inline[]): LinkNode

mentionUser(userId: number, label: string): MentionNode

mentionUsername(username: string): MentionNode

pre(value: string, language?: PreLanguage): PreNode

spoiler(...children: readonly Inline[]): SpoilerNode

strikethrough(...children: readonly Inline[]): StrikethroughNode

text(value: string): TextNode

underline(...children: readonly Inline[]): UnderlineNode

Validate `actionId` at call time and return an explicitly-typed def. An invalid `actionId` is a programmer bug (a hardcoded literal that violates the `/^[a-z0-9]{1,8}$/` budget), not an expected runtime path, so this throws a descriptive `Error` rather than returning a result DU.

<TPayload extends Record<string, unknown>>(input: { actionId: string; payloadSchema: z.ZodType<TPayload>; fields: readonly (keyof TPayload & string)[]; }): CallbackActionDef<TPayload>

Decode a `callback_data` string against a namespace. Generic `TPayload` is the caller's asserted payload type; the actual shape is enforced by the matched action's zod schema, and the validated result is branded to `TPayload` only after a successful `safeParse`.

<TPayload, TActions extends Record<string, AnyCallbackActionDef> = Record<string, AnyCallbackActionDef>>(callbackData: string, namespace: CallbackNamespace<TActions>, deps: CallbackDecodeDeps): Promise<CallbackDecodeResult<TPayload>>

Encode via a namespace + action key. The key is narrowed to the namespace's declared action names (a bogus key is a compile-time error, not a runtime one); payload is a free `TPayload` here — `callbackButton` is the entry point that ties payload shape to the chosen action.

<TPayload extends Record<string, unknown>, TActions extends Record<string, AnyCallbackActionDef>>(namespace: CallbackNamespace<TActions>, actionKey: keyof TActions & string, payload: TPayload, deps: CallbackEncodeDeps): Promise<string>

Build one inline button for a bound action + typed payload. `payload` is statically tied to the action's declared payload shape, so a missing/extra field is a compile-time error.

<TPayload extends Record<string, unknown>>(text: string, action: BoundCallbackAction<TPayload>, payload: TPayload, deps: CallbackEncodeDeps): Promise<InlineKeyboardButton>

Shape a list of rows into an `InlineKeyboardMarkup`.

inlineKeyboard(rows: readonly (readonly InlineKeyboardButton[])[]): InlineKeyboardMarkup

Shape a list of buttons into a single keyboard row.

keyboardRow(buttons: readonly InlineKeyboardButton[]): readonly InlineKeyboardButton[]

Validate `namespaceId` at call time (programmer bug on failure → throw) and bind every action to the namespace id.

<TActions extends Record<string, AnyCallbackActionDef>>(input: { namespaceId: string; actions: TActions; }): CallbackNamespace<TActions>

A non-durable, non-evicting `PointerStore` backed by a `Map`. TEST-ONLY: it holds envelopes in process memory with no persistence, no eviction, and no cross-process visibility. Do NOT use in production — decode must survive a process restart, which this store does not.

createInMemoryPointerStore(): PointerStore

toChatId(value: number): IdResult<ChatId>

toMessageId(value: number): IdResult<MessageId>

The rendered plain text of a single node (its leaves concatenated in order).

nodeText(node: RichTextNode): string

UTF-16 code-unit length of the rendered text (the unit Telegram counts).

renderedLength(nodes: readonly RichTextNode[]): number

The rendered plain text of a node sequence.

renderPlainText(nodes: readonly RichTextNode[]): string

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

createCaptionText(nodes: readonly RichTextNode[]): CaptionTextResult

createMessageText(nodes: readonly RichTextNode[]): MessageTextResult

Read the validated nodes back out of a branded message/caption value.

messageNodes(message: MessageText | CaptionText): readonly RichTextNode[]

Read the rendered plain text back out of a branded message/caption value.

messageText(message: MessageText | CaptionText): string

collapsible(summary: readonly RichTextNode[], children: readonly RichBlockNode[]): CollapsibleBlock

heading(level: 1 | 2 | 3 | 4, children: readonly RichTextNode[]): HeadingBlock

math(latex: string): MathBlock

table(header: readonly (readonly RichTextNode[])[], rows: readonly (readonly (readonly RichTextNode[])[])[]): TableBlock

parseRichText(value: unknown): ParseRichTextResult

A value interpolable into a `gram` template.

type GramValue = RichTextNode | readonly RichTextNode[] | string

A child accepted by the builders: a node, or a bare string (wrapped as text).

type Inline = RichTextNode | string

type Brand = Brand<T, B>

A declared callback action: id + payload schema + positional field order.

type CallbackActionDef = CallbackActionDef<TPayload>

Dependencies a decode call needs. `hmacSecrets` is a `[current, ...previous]` list verified in order so a caller can grace-period a secret rotation; passing just `[current]` is the simpler valid default.

type CallbackDecodeDeps = {
  readonly pointerStore: PointerStore;
  readonly hmacSecrets: readonly Uint8Array[];
  readonly now: () => number;
}

The six mutually-exclusive outcomes of decoding a `callback_data` string.

type CallbackDecodeResult = CallbackDecodeResult<TPayload>

Dependencies an encode call needs: store + signing secret + clock + TTL.

type CallbackEncodeDeps = {
  readonly pointerStore: PointerStore;
  readonly hmacSecret: Uint8Array;
  readonly now: () => number;
  readonly ttlMs: number;
}

A short (1-8 char) action id, part of the compact wire format.

type CallbackActionId = string & z.BRAND<"CallbackActionId">

A short (1-4 char) namespace id, part of the compact wire format.

type CallbackNamespaceId = string & z.BRAND<"CallbackNamespaceId">

A fixed 22-char base64url (128-bit) pointer-store token.

type CallbackToken = string & z.BRAND<"CallbackToken">

The minimal Bot API inline button shape `core` produces.

type InlineKeyboardButton = {
  readonly text: string;
  readonly callback_data: string;
}

A grid of button rows, ready to drop into `reply_markup`.

type InlineKeyboardMarkup = {
  readonly inline_keyboard: readonly (readonly InlineKeyboardButton[])[];
}

An action bound to its namespace — self-contained for encoding.

type BoundCallbackAction = BoundCallbackAction<TPayload>

A compile-time registry of bound actions keyed by declaration name.

type CallbackNamespace = CallbackNamespace<TActions>

The signed-at-rest record a pointer token resolves to. `notAfter` is embedded here (not on the wire) and checked post-lookup so a still-resolvable token for a button that should be considered dead decodes as `expired`, not `ok`.

type PointerEnvelope = {
  readonly namespaceId: CallbackNamespaceId;
  readonly actionId: CallbackActionId;
  /** `JSON.stringify` of the zod-validated payload. */
  readonly payloadJson: string;
  /** Epoch ms; caller-chosen TTL horizon. */
  readonly notAfter: number;
}

Caller-supplied storage for spillover envelopes. `put` overwrite is a caller bug (tokens are 128-bit random, collision is cryptographically negligible), not something the codec guards against.

type PointerStore = {
  put(token: CallbackToken, envelope: PointerEnvelope): Promise<void>;
  get(token: CallbackToken): Promise<PointerEnvelope | undefined>;
}

A Telegram chat identifier (may be negative for groups/channels).

type ChatId = Brand<number, "ChatId">

type IdResult = IdResult<T>

A Telegram message identifier within a chat.

type MessageId = Brand<number, "MessageId">

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"

type CaptionTextResult = | { kind: "ok"; value: CaptionText }
  | { kind: "too-long"; limit: typeof CAPTION_TEXT_LIMIT; actual: number }

type MessageTextResult = | { kind: "ok"; value: MessageText }
  | { kind: "too-long"; limit: typeof MESSAGE_TEXT_LIMIT; actual: number }

type RichBlockNode = HeadingBlock | MathBlock | TableBlock | CollapsibleBlock

Nodes permitted directly inside a blockquote (excludes both blockquote variants).

type BlockquoteChild = | TextNode
  | CodeNode
  | PreNode
  | BoldNode
  | ItalicNode
  | UnderlineNode
  | StrikethroughNode
  | SpoilerNode
  | LinkNode
  | MentionNode

Mention target: by

type MentionTarget = | { readonly kind: "username"; readonly username: string }
  | { readonly kind: "user-id"; readonly userId: number; readonly label: string }

type ParseRichTextResult = | { kind: "ok"; value: RichTextNode[] }
  | { kind: "invalid"; message: string }

Language tag for a `pre` block, modeled as a discriminated union (no `.optional`).

type PreLanguage = | { readonly kind: "known"; readonly value: string }
  | { readonly kind: "unknown" }

type RichTextNode = | TextNode
  | CodeNode
  | PreNode
  | BoldNode
  | ItalicNode
  | UnderlineNode
  | StrikethroughNode
  | SpoilerNode
  | LinkNode
  | MentionNode
  | BlockquoteNode
  | ExpandableBlockquoteNode

interface DiagnosticEvent

kind: DiagnosticKind

category: string

detail: string

stack: string

data: Record<string, unknown>

timestamp: number

A RichText document proven to fit within the 1024-code-unit caption limit.

interface CaptionText

[CAPTION_TEXT_BRAND]: true

nodes: readonly RichTextNode[]

text: string

A RichText document proven to fit within the 4096-code-unit message limit.

interface MessageText

[MESSAGE_TEXT_BRAND]: true

nodes: readonly RichTextNode[]

text: string

interface CollapsibleBlock

kind: "collapsible"

summary: readonly RichTextNode[]

children: readonly RichBlockNode[]

interface HeadingBlock

kind: "heading"

level: 1 | 2 | 3 | 4

children: readonly RichTextNode[]

interface MathBlock

kind: "math"

latex: string

interface TableBlock

kind: "table"

header: readonly (readonly RichTextNode[])[]

rows: readonly (readonly (readonly RichTextNode[])[])[]

interface BlockquoteNode

kind: "blockquote"

children: readonly BlockquoteChild[]

interface BoldNode

kind: "bold"

children: readonly RichTextNode[]

interface CodeNode

kind: "code"

value: string

interface ExpandableBlockquoteNode

kind: "expandable-blockquote"

children: readonly BlockquoteChild[]

interface ItalicNode

kind: "italic"

children: readonly RichTextNode[]

interface LinkNode

kind: "link"

href: string

children: readonly RichTextNode[]

interface MentionNode

kind: "mention"

target: MentionTarget

interface PreNode

kind: "pre"

language: PreLanguage

children: readonly TextNode[]

interface SpoilerNode

kind: "spoiler"

children: readonly RichTextNode[]

interface StrikethroughNode

kind: "strikethrough"

children: readonly RichTextNode[]

interface TextNode

kind: "text"

value: string

interface UnderlineNode

kind: "underline"

children: readonly RichTextNode[]

Hard Bot API ceiling on `callback_data`, in UTF-8 bytes (Bot API 10.1).

const CALLBACK_DATA_MAX_BYTES: 64

const CallbackActionIdSchema: z.ZodType<CallbackActionId, z.ZodTypeDef, string>

const CallbackNamespaceIdSchema: z.ZodType<CallbackNamespaceId, z.ZodTypeDef, string>

const CallbackTokenSchema: z.ZodType<CallbackToken, z.ZodTypeDef, string>

const InlineKeyboardButtonSchema: z.ZodType<InlineKeyboardButton, z.ZodTypeDef, InlineKeyboardButton>

const InlineKeyboardMarkupSchema: z.ZodType<InlineKeyboardMarkup, z.ZodTypeDef, InlineKeyboardMarkup>

const CAPTION_TEXT_LIMIT: 1024

const MESSAGE_TEXT_LIMIT: 4096

const CollapsibleBlockSchema: z.ZodType<CollapsibleBlock, z.ZodTypeDef, CollapsibleBlock>

const HeadingBlockSchema: z.ZodType<HeadingBlock, z.ZodTypeDef, HeadingBlock>

const MathBlockSchema: z.ZodType<MathBlock, z.ZodTypeDef, MathBlock>

const RichBlockNodeSchema: z.ZodType<RichBlockNode, z.ZodTypeDef, RichBlockNode>

const TableBlockSchema: z.ZodType<TableBlock, z.ZodTypeDef, TableBlock>

The blockquote child union: every node kind except the two blockquote variants.

const BlockquoteChildSchema: z.ZodType<BlockquoteChild, z.ZodTypeDef, BlockquoteChild>

const BlockquoteNodeSchema: z.ZodType<BlockquoteNode, z.ZodTypeDef, BlockquoteNode>

const BoldNodeSchema: z.ZodType<BoldNode, z.ZodTypeDef, BoldNode>

const CodeNodeSchema: z.ZodType<CodeNode, z.ZodTypeDef, CodeNode>

const ExpandableBlockquoteNodeSchema: z.ZodType<ExpandableBlockquoteNode, z.ZodTypeDef, ExpandableBlockquoteNode>

const ItalicNodeSchema: z.ZodType<ItalicNode, z.ZodTypeDef, ItalicNode>

const LinkNodeSchema: z.ZodType<LinkNode, z.ZodTypeDef, LinkNode>

const MentionNodeSchema: z.ZodType<MentionNode, z.ZodTypeDef, MentionNode>

const PreNodeSchema: z.ZodType<PreNode, z.ZodTypeDef, PreNode>

const RichTextNodeSchema: z.ZodType<RichTextNode, z.ZodTypeDef, RichTextNode>

const RichTextSchema: z.ZodType<RichTextNode[], z.ZodTypeDef, RichTextNode[]>

const SpoilerNodeSchema: z.ZodType<SpoilerNode, z.ZodTypeDef, SpoilerNode>

const StrikethroughNodeSchema: z.ZodType<StrikethroughNode, z.ZodTypeDef, StrikethroughNode>

const TextNodeSchema: z.ZodType<TextNode, z.ZodTypeDef, TextNode>

const UnderlineNodeSchema: z.ZodType<UnderlineNode, z.ZodTypeDef, UnderlineNode>