nadia

# Changelog

All notable changes to this project will be documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

## 1.6.1 - 2026-06-26

### Added

- Added contributor guidelines covering local checks, live smoke tests,
  changelog expectations, Bot API maintenance, and the CI release process.

### Fixed

- Replaced low-level request setup failures for invalid option shapes and
  missing bot tokens with intentional `%Nadia.Model.Error{}` results before
  HTTP is attempted.

## 1.6.0 - 2026-06-26

### Added

- Added a tested bot example catalog covering command and callback routing,
  inline keyboards, and explicit multi-step conversation state.
- Added guides for learning paths, multiple bots, offline handler testing,
  production operation, and the Telegraph API.
- Added offline-tested media/file, persistent session backend, and bounded
  rate-limit examples with production caveats and ExDoc guides.
- Added typed Telegram `error_code` and `ResponseParameters` parsing while
  preserving `%Nadia.Model.Error{reason: reason}` compatibility.
- Added `file_unique_id` to `Nadia.Model.File` parsing.
- Added `Nadia.InputFile` for explicit file IDs, URLs, validated local paths,
  bounded iodata, and known-size streaming uploads, including multiple nested
  `attach://` parts without creating atoms from attachment names.
- Added `Nadia.InputMedia` builders for animation, audio, document, live photo,
  photo, and video payloads with fixed discriminators, typed album validation,
  and nested `Nadia.InputFile` support.
- Added `Nadia.InputPaidMedia` builders for live photos, photos, and videos,
  including typed 1-10 item validation and nested uploads for `sendPaidMedia`.
- Added `Nadia.InputPollMedia` link, location, sticker, and venue builders with
  context-aware validation for poll descriptions, quiz explanations, and poll
  options.
- Added `Nadia.InputPollOption` with UTF-8 and text-length validation, typed
  option-media validation, and locally knowable option-count and quiz
  `correct_option_ids` checks.
- Added `Nadia.InputRichMessage` HTML and Markdown builders plus
  `Nadia.InputRichMessageContent` for inline results, with context-aware
  draft-only construct checks and typed integration across send, draft, edit,
  guest, Web App, prepared-inline, and inline-query result paths.
- Added complete typed `Nadia.StoryArea` and `Nadia.ReactionType` construction
  for positions, location addresses, locations, suggested reactions, links,
  weather, and unique gifts, including official per-story variant limits.
- Added typed inline `InputMessageContent` builders for text, invoice,
  location, venue, and contact content, plus `Nadia.LabeledPrice` for invoice
  price portions.
- Added upload-only `Nadia.InputProfilePhoto` and `Nadia.InputStoryContent`
  builders with fixed discriminators and locally enforceable timestamp,
  duration, source, and boolean validation.
- Added `Nadia.InputSticker` static, animated, and video builders plus current
  sticker upload, creation, addition, replacement, and thumbnail request
  shapes. Historical PNG-and-emoji entry points remain compatibility shims.
- Added `Nadia.download_file/3,4,5`, a bounded streaming download-to-file API
  with metadata and actual-byte enforcement, no-overwrite atomic publication,
  partial cleanup, redirect/retry suppression, token-safe errors, and explicit
  hosted-versus-local Bot API behavior.
- Added an optional streaming download capability for HTTP adapters and
  redacted `Nadia.HTTPDownloadRequest`/`Nadia.HTTPRequest` inspection without
  breaking existing post-only custom adapters.
- Added current file identity and metadata parsing for animation, audio,
  document, live photo, sticker, video, video note, voice, video quality, chat
  photo, and sticker-set responses while retaining legacy `thumb` fields.
- Added an offline-tested, application-owned optimistic database session
  example with bounded compare-and-swap conflicts, update idempotency, and
  transactional outbox intent.

### Changed

- Reworked the README into a secure quick start and documentation map, grouped
  ExDoc guides, modules, and Bot API methods by task, and expanded the webhook
  guide with production-oriented delivery and secret verification guidance.
- Updated configuration, package metadata, and Telegraph reference text to
  remove insecure or misleading examples.
- Normalized structurally invalid Telegram and Telegraph response envelopes,
  made missing Telegram `file_path` values return an error, enabled local
  multipart uploads for `send_animation`, and refreshed nearby message/media
  documentation.
- Reworked Req multipart construction to preserve binary field names, stream
  paths and known-size Enumerables without whole-file buffering, and reject
  explicit path or size errors before the network call.
- Expanded persistent-session, media/download, and production guidance with
  database concurrency, outbox, duplicate-delivery, token exposure, memory,
  cleanup, and local Bot API caveats.
- Updated poll media encoding, media-group and edit-media guidance, sticker
  wrapper signatures, the tested media example, ExDoc navigation, and package
  documentation for typed outgoing media and bounded downloads.
- Expanded paid-media and poll structured-field encoding, preserved explicit
  false values, and integrated typed profile-photo and story uploads without
  narrowing raw map, keyword, struct, or pre-encoded JSON compatibility.
- Expanded poll, rich-message, inline-result, inline-message-content, and
  story-area encoding without narrowing raw maps, keyword lists, arbitrary
  structs, mixed lists, or pre-encoded JSON compatibility; malformed typed
  values now fail before HTTP.

## 1.5.0 - 2026-06-13

### Added

- Added `Nadia.SessionStore` and `Nadia.SessionStore.ETS` for optional,
  explicit bot session storage without adding persistence dependencies or a
  conversation DSL.

## 1.4.0 - 2026-06-13

### Added

- Added `Nadia.Webhook` framework-neutral helpers for parsing webhook request
  bodies, verifying Telegram secret token headers, building contexts, and
  dispatching updates without adding Plug or Phoenix as dependencies.
- Added a "Receive Webhook Updates" guide documenting the core helper-only
  webhook integration decision.
- Added `Nadia.set_webhook/1,2` documentation for `:secret_token` and
  JSON-array request encoding for `:allowed_updates` lists.

## 1.3.0 - 2026-06-13

### Added

- Added `mix nadia.gen.bot` to generate a starter bot handler, offline test,
  and polling setup instructions.
- Added a "Build Your First Bot" guide for generated polling bots.
- Documented Nadia's HTTP adapter structs and behaviour so generated tests and
  custom adapters have a stable public testing boundary.

## 1.2.0 - 2026-06-13

### Added

- Added `Nadia.Handler` and `Nadia.Dispatcher` for behaviour-first update
  dispatch, plus small command, text, callback, and fallback matching helpers
  for non-polling handlers.
- Added `Nadia.Polling`, an OTP long-polling worker that calls `getUpdates`,
  dispatches updates sequentially, tracks offsets in memory, and retries API or
  handler failures with bounded backoff.
- Added JSON-array request encoding for `Nadia.get_updates/1,2`
  `:allowed_updates` lists.

## 1.1.0 - 2026-06-13

### Added

- Added public incoming update parsing helpers:
  `Nadia.Parser.parse_update/1`, `Nadia.Parser.parse_update!/1`, and
  `Nadia.Parser.parse_updates/1`.
- Added `Nadia.Context` for extracting effective message/chat/user data from
  updates and replying or answering callback queries through existing Nadia API
  wrappers, including explicit `%Nadia.Client{}` support.

## 1.0.0 - 2026-06-12

### Added

- Added complete Telegram Bot API method coverage for Bot API 10.1, published
  on June 11, 2026. Nadia now wraps all 180 official Bot API methods, with 0
  missing and 0 extra remote methods in the release inventory.
- Added Bot API 10.1 rich-message wrappers for `sendRichMessage` and
  `sendRichMessageDraft`, plus `rich_message` request encoding for
  `editMessageText`.
- Added Bot API 10.1 join-request query wrappers for
  `answerChatJoinRequestQuery` and `sendChatJoinRequestWebApp`.
- Added focused Bot API 10.1 parser/model support for
  `User.supports_join_request_queries`, `Message.rich_message`,
  `ChatJoinRequest.query_id`, and `PollMedia.link`.
- Added Telegram poll response structs and parser coverage for `Message.poll`,
  update-level `poll` and `poll_answer` updates, poll option service messages,
  and `stopPoll` results.
- Added Telegram reaction response structs and parser coverage for
  `message_reaction` and `message_reaction_count` updates.
- Added Telegram chat boost response structs and parser coverage for
  `chat_boost`, `removed_chat_boost`, `Message.boost_added`, and
  `getUserChatBoosts` results.
- Added Telegram paid media response structs and parser coverage for
  `Message.paid_media`, `purchased_paid_media` updates, and `sendPaidMedia`
  results.
- Added Telegram managed bot response structs and parser coverage for
  `Message.managed_bot_created`, `managed_bot` updates, and
  `getManagedBotAccessSettings` results.
- Added Telegram business and guest-query response structs and parser coverage
  for `business_connection`, `deleted_business_messages`, business chat profile
  fields, and `answerGuestQuery` results.
- Added Bot API wrappers for guest queries, business connections, managed bot
  token/access settings, user chat boosts, and user personal chat messages.
- Added Bot API wrappers for business account read/delete, profile, gift
  settings, and Stars transfer maintenance.
- Added Bot API wrappers for business gift conversion, upgrade, and transfer
  maintenance.
- Added Bot API gift getter wrappers plus gift and owned-gift response
  structs/parser coverage.
- Added Bot API story wrappers plus `%Nadia.Model.Story{}` response parser
  coverage.
- Added Bot API Star balance getter wrappers and `%Nadia.Model.StarAmount{}`
  parser/model support.
- Added Bot API `getStarTransactions` wrapper plus Star transaction response
  structs/parser coverage.
- Added Bot API invoice wrappers for sending invoices and creating invoice
  links.
- Added Bot API wrappers for payment acknowledgement and Telegram Stars
  payment/subscription maintenance.
- Added Bot API wrappers for bulk message deletion and message reaction
  maintenance.
- Added Bot API wrappers for chat administration, membership restrictions,
  join-request moderation, chat metadata, pinned-message, and chat sticker-set
  maintenance.
- Added Bot API `setChatPhoto` wrapper with direct chat photo upload support.
- Added Bot API wrappers for bot lifecycle and public bot settings maintenance,
  including commands, descriptions, menu button, default administrator rights,
  and user emoji status updates.
- Added Bot API wrappers and response structs for object-returning bot settings
  getters, including commands, profile names/descriptions, menu buttons, and
  default administrator rights.
- Added Bot API wrappers and response structs for bot profile photos and Mini
  App prepared inline messages and keyboard buttons.
- Added Bot API organization verification wrappers for users and chats.
- Added Bot API outgoing gift wrappers for gifts and Premium subscriptions.
- Added Bot API forum topic wrappers, `%Nadia.Model.ForumTopic{}`, and parser
  coverage for `createForumTopic` and `getForumTopicIconStickers` results.
- Added Bot API wrappers for modern sticker set and custom emoji sticker
  maintenance, including `getCustomEmojiStickers` parser coverage.
- Added Bot API invite-link and user profile audio wrappers, plus
  `%Nadia.Model.ChatInviteLink{}` and `%Nadia.Model.UserProfileAudios{}`
  parser/model support.
- Added Bot API copy/forward wrappers for `copyMessage`, `copyMessages`, and
  `forwardMessages`, plus `%Nadia.Model.MessageId{}` parser/model support.
- Added Bot API send wrappers for `sendVideoNote`, `sendLivePhoto`,
  `sendMediaGroup`, `sendPaidMedia`, `sendPoll`, `sendDice`, and
  `sendMessageDraft`.
- Added Bot API `sendChecklist` wrapper plus checklist model/parser support for
  `Message.checklist`.
- Added Bot API updating-message wrappers for editing media, live locations,
  checklists, stopping polls, and approving or declining suggested posts.
- Added Bot API wrappers and parser/model support for Web App query answers,
  games, game high scores, and Passport data errors.

### Changed

- Prepared Nadia 1.0.0 as the first stable release after the transport,
  explicit-client, parser-safety, and complete Bot API method-coverage refresh.
- Upgraded Req to 0.6.1 for Nadia's default HTTP transport.
- Expanded Telegram response parsing for selected modern `Update`, `Message`,
  `User`, `MessageEntity`, and `PhotoSize` fields, including fixture-backed
  `getUpdates` coverage with string-key JSON decoding and no atom creation for
  unknown response fields.
- Preserved explicit `false` Telegram Bot API and Telegraph API request
  parameters while continuing to omit `nil` parameters.
- Replaced obsolete Telegram Bot API method wrappers `kick_chat_member` and
  `get_chat_members_count` with current `ban_chat_member` and
  `get_chat_member_count` wrappers.
- Added option-support arities for existing Bot API wrappers
  `forward_message`, `send_chat_action`, `delete_webhook`,
  `get_chat_administrators`, `unban_chat_member`, and `unpin_chat_message`.

## 0.9.0 - 2026-06-05

### Added

- Added `%Nadia.Client{}` for explicit bot configuration, including default and
  named application-config constructors.
- Added token-redacted inspect output for `%Nadia.Client{}`.
- Added client-aware public Telegram wrapper arities, such as
  `Nadia.send_message(client, chat_id, text, options)`, while preserving legacy
  single-bot arities.
- Added client-aware `Nadia.API.request/4`, `Nadia.API.request?/4`, and
  `Nadia.API.build_file_url/2`.
- Added a Nadia-owned HTTP boundary with normalized request/response structs
  and configurable HTTP adapters.
- Added default-off `:telegram_live` smoke tests for two explicit bot clients.

### Changed

- Raised the minimum supported Elixir version to 1.20 and aligned CI/release
  workflows with Elixir 1.20 on current Erlang/OTP releases.
- Promoted Req to Nadia's production HTTP transport for both Telegram Bot API
  and Telegraph API requests.
- Decode Telegram Bot API and Telegraph API responses without creating atoms
  from remote JSON keys; unknown response fields remain ignored until Nadia
  explicitly models them.
- Replaced Bot API and Telegraph cassette coverage with deterministic offline
  request/response tests.
- Normalized Telegraph transport errors and malformed JSON responses into
  `Nadia.Graph.Model.Error`.

### Removed

- Removed HTTPoison, hackney, ExVCR, and hackney-specific SOCKS proxy
  configuration.

## 0.8.0 - 2026-06-02

### Changed

- Raised the minimum supported Elixir version to 1.15.
- Refreshed runtime dependencies for modern Elixir and Erlang/OTP releases:
  `httpoison` 2.3, `jason` 1.4, and the current compatible Hackney dependency
  graph.
- Updated CI to verify formatting, compilation with warnings as errors, tests,
  and documentation generation on modern Elixir/OTP versions.

### Removed

- Removed the legacy `inch_ex` documentation check in favor of ExDoc generation
  with warnings treated as errors.