@yaebal/link-preview

fluent builder for telegram's link_preview_options — the field sendMessage, editMessageText, and friends take to control the automatic link preview.

install

terminal

pnpm add @yaebal/link-preview

usage

linkPreview(url?) starts a builder, optionally pre-seeded with a url. chain the options you need, then call .build() to get the plain LinkPreviewOptions object the api expects.

bot.ts

import { linkPreview } from "@yaebal/link-preview";

bot.command("share", (ctx) =>
  ctx.reply("check this out: https://example.com", {
    link_preview_options: linkPreview("https://example.com")
      .showAboveText()
      .preferLargeMedia()
      .build(),
  }),
);

disabling the preview

disableLinkPreview() is a shorthand for { is_disabled: true } when there's nothing else to configure:

disable.ts

import { disableLinkPreview, linkPreview } from "@yaebal/link-preview";

// shorthand — nothing else to configure
await ctx.reply("no preview here: https://example.com", {
  link_preview_options: disableLinkPreview(),
});

// same thing spelled out via the builder
await ctx.reply("no preview here: https://example.com", {
  link_preview_options: linkPreview().disable().build(),
});

api

export	signature	description
`linkPreview`	`(url?: string) => LinkPreview`	starts a builder, optionally pre-seeded with `.url(url)`
`disableLinkPreview`	`() => LinkPreviewOptions`	shorthand for `{ is_disabled: true }`

LinkPreview

every method returns this, so calls chain in any order.

method	sets	description
`.url(url)`	`url`	url to preview; if omitted, telegram uses the first url found in the message text
`.disable(value = true)`	`is_disabled`	hides the preview entirely
`.preferSmallMedia(value = true)`	`prefer_small_media`	shrinks the preview media; ignored if the url isn't set or resizing isn't supported for it
`.preferLargeMedia(value = true)`	`prefer_large_media`	enlarges the preview media; ignored if the url isn't set or resizing isn't supported for it
`.showAboveText(value = true)`	`show_above_text`	renders the preview above the message text instead of below it
`.build()`	—	returns the plain `LinkPreviewOptions` object
`.toJSON()`	—	same as `.build()`, for `JSON.stringify`

tojson.ts

// the builder also serializes correctly on its own, since Api stringifies
// request bodies through JSON.stringify — link_preview_options: linkPreview(...)
// would produce the same wire payload as .build(), but .build() keeps the
// param's static type as plain LinkPreviewOptions.
JSON.stringify({ link_preview_options: linkPreview("https://example.com").showAboveText() });

.preferSmallMedia() and .preferLargeMedia() are independent flags with no mutual-exclusion logic — that matches telegram's own api shape, which is equally permissive.

no context wiring, no bot.install(...) — this package is a plain builder you call wherever you build request options.