Add source-linked API reference

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Deploy API reference
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: npm ci --prefix docs
+
+      - name: Build and verify API reference
+        run: npm run check --prefix docs
+
+      - name: Configure Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v6
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -173,4 +173,6 @@ Thumbs.db
 
 # Project specific
 notes/
-tma.js/
+tma.js/
+docs/node_modules/
+docs/dist/

docs/README.md

@@ -0,0 +1,21 @@
+# API reference site
+
+This directory contains the reproducible Sourcey API reference for
+`telegram-init-data`. The authored configuration is `sourcey.config.ts`; the
+Markdown under `generated/` is rebuilt directly from the Python package before
+every site build.
+
+```bash
+cd docs
+npm ci
+npm run check
+```
+
+`npm run check` regenerates the reference, builds the static site into `dist/`,
+and verifies the public symbol count, immutable source links, project-scoped
+search URLs, context exports, and canonical project URL. Generated HTML remains
+untracked build output.
+
+The deployment workflow publishes `dist/` to the repository's GitHub Pages
+site. Repository maintainers need to select **GitHub Actions** as the Pages
+source once; subsequent merges rebuild and deploy automatically.

docs/generated/core-api.md

@@ -0,0 +1,90 @@
+---
+title: Validation, parsing, and signing
+description: The package-level functions for validating, parsing, and producing Telegram Mini Apps initialization data.
+---
+
+Source snapshot: [`b60df7aaa2b597e7647a3b851b8e552a80943015`](https://github.com/iCodeCraft/telegram-init-data/tree/b60df7aaa2b597e7647a3b851b8e552a80943015) · package version `1.1.0`.
+
+The package-level functions for validating, parsing, and producing Telegram Mini Apps initialization data.
+
+Every entry links to its immutable line-level source declaration.
+
+## `hash_token`
+
+```python
+def hash_token(token: Text) -> bytes
+```
+
+Hash token using HMAC-SHA256 with key ``WebAppData``.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/hash_token.py#L8)
+
+## `sign_data`
+
+```python
+def sign_data(data: Text, token: Text, options: ValidateOptions=None) -> str
+```
+
+Sign data using HMAC-SHA256 with hashed token.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/sign_data.py#L9)
+
+## `validate`
+
+```python
+def validate(value: ValidateValue, token: Text, options: ValidateOptions=None) -> None
+```
+
+Validate Telegram Mini App init data.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/validate.py#L17)
+
+## `is_valid`
+
+```python
+def is_valid(value: ValidateValue, token: Text, options: ValidateOptions=None) -> bool
+```
+
+Check if Telegram Mini App init data is valid without raising.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/is_valid.py#L8)
+
+## `parse`
+
+```python
+def parse(value: InitDataInput) -> InitData
+```
+
+Parse Telegram Mini App init data into a structured object.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/parse.py#L10)
+
+## `sign`
+
+```python
+def sign(data: SignData, token: Text, auth_date: datetime, options: ValidateOptions=None) -> str
+```
+
+Sign Telegram Mini App init data.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/sign.py#L11)
+
+## `validate3rd`
+
+```python
+def validate3rd(value: ValidateValue, bot_id: int, verify_fn: Callable[[str, str, str], bool], options: Validate3rdOptions=None) -> None
+```
+
+Validate Telegram Mini App init data using third-party verification.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/validate3rd.py#L17)
+
+## `is_valid3rd`
+
+```python
+def is_valid3rd(value: ValidateValue, bot_id: int, verify_fn: Callable[[str, str, str], bool], options: Validate3rdOptions=None) -> bool
+```
+
+Check third-party init data validity without raising.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/is_valid3rd.py#L10)

docs/generated/data-model.md

@@ -0,0 +1,122 @@
+---
+title: Data model and options
+description: Typed dictionaries, enums, and option objects returned or accepted by the public API.
+---
+
+Source snapshot: [`b60df7aaa2b597e7647a3b851b8e552a80943015`](https://github.com/iCodeCraft/telegram-init-data/tree/b60df7aaa2b597e7647a3b851b8e552a80943015) · package version `1.1.0`.
+
+Typed dictionaries, enums, and option objects returned or accepted by the public API.
+
+Every entry links to its immutable line-level source declaration.
+
+## `ChatType`
+
+```python
+class ChatType(str, Enum)
+```
+
+Type of chat.
+
+### Public members
+
+- `SENDER = 'sender'`
+- `PRIVATE = 'private'`
+- `GROUP = 'group'`
+- `SUPERGROUP = 'supergroup'`
+- `CHANNEL = 'channel'`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L7)
+
+## `User`
+
+```python
+class User(TypedDict)
+```
+
+Telegram user object.
+
+### Public members
+
+- `id: int`
+- `first_name: str`
+- `last_name: Optional[str]`
+- `username: Optional[str]`
+- `language_code: Optional[str]`
+- `is_bot: Optional[bool]`
+- `is_premium: Optional[bool]`
+- `added_to_attachment_menu: Optional[bool]`
+- `allows_write_to_pm: Optional[bool]`
+- `photo_url: Optional[str]`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L16)
+
+## `Chat`
+
+```python
+class Chat(TypedDict)
+```
+
+Telegram chat object.
+
+### Public members
+
+- `id: int`
+- `type: ChatType`
+- `title: Optional[str]`
+- `username: Optional[str]`
+- `photo_url: Optional[str]`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L30)
+
+## `InitData`
+
+```python
+class InitData(TypedDict)
+```
+
+Telegram Mini App initialization data.
+
+### Public members
+
+- `query_id: Optional[str]`
+- `user: Optional[User]`
+- `receiver: Optional[User]`
+- `chat: Optional[Chat]`
+- `chat_type: Optional[ChatType]`
+- `chat_instance: Optional[str]`
+- `start_param: Optional[str]`
+- `can_send_after: Optional[int]`
+- `auth_date: int`
+- `hash: str`
+- `signature: Optional[str]`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L39)
+
+## `ValidateOptions`
+
+```python
+class ValidateOptions(TypedDict)
+```
+
+Options for validation functions.
+
+### Public members
+
+- `expires_in: int`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L60)
+
+## `Validate3rdOptions`
+
+```python
+class Validate3rdOptions(TypedDict)
+```
+
+Options for third-party validation.
+
+### Public members
+
+- `expires_in: int`
+- `test: bool`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/types.py#L65)

docs/generated/errors.md

@@ -0,0 +1,76 @@
+---
+title: Exceptions
+description: The package exception hierarchy used by validation and parsing operations.
+---
+
+Source snapshot: [`b60df7aaa2b597e7647a3b851b8e552a80943015`](https://github.com/iCodeCraft/telegram-init-data/tree/b60df7aaa2b597e7647a3b851b8e552a80943015) · package version `1.1.0`.
+
+The package exception hierarchy used by validation and parsing operations.
+
+Every entry links to its immutable line-level source declaration.
+
+## `TelegramInitDataError`
+
+```python
+class TelegramInitDataError(Exception)
+```
+
+Base class for all Telegram Init Data errors.
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/exceptions.py#L7)
+
+## `AuthDateInvalidError`
+
+```python
+class AuthDateInvalidError(TelegramInitDataError)
+```
+
+Raised when auth_date is invalid or missing.
+
+### Public members
+
+- `def __init__(self, value: Optional[str]=None)`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/exceptions.py#L12)
+
+## `SignatureInvalidError`
+
+```python
+class SignatureInvalidError(TelegramInitDataError)
+```
+
+Raised when signature verification fails.
+
+### Public members
+
+- `def __init__(self, message: str='Signature is invalid')`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/exceptions.py#L21)
+
+## `SignatureMissingError`
+
+```python
+class SignatureMissingError(TelegramInitDataError)
+```
+
+Raised when required signature parameter is missing.
+
+### Public members
+
+- `def __init__(self, third_party: bool=False)`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/exceptions.py#L28)
+
+## `ExpiredError`
+
+```python
+class ExpiredError(TelegramInitDataError)
+```
+
+Raised when init data has expired.
+
+### Public members
+
+- `def __init__(self, issued_at: datetime, expires_at: datetime, now: datetime)`
+
+[View the pinned source declaration](https://github.com/iCodeCraft/telegram-init-data/blob/b60df7aaa2b597e7647a3b851b8e552a80943015/telegram_init_data/exceptions.py#L38)