refactor: restructure as installable PyPI package

- Rename app/ → fragmentapi/ for proper package naming
- Add FragmentClient class with gift_premium, gift_stars, topup_ton methods
- Restructure core/ → types/ (exceptions, results, constants)
- Merge utils/hash.py into utils/client.py
- Replace _version.py with importlib.metadata
- Add input validation with min/max bounds
- Add unit tests: decode, client init/cookies
- Rename 002_test_hash → 003_test_hash
- Clean up pyproject.toml: pin deps, production classifiers

fragmentapi/types/exceptions.py

@@ -0,0 +1,106 @@
+class FragmentError(Exception):
+    """Base exception for all fragmentapi library errors."""
+
+
+class ClientError(FragmentError):
+    """Raised for client configuration and setup issues (bad params, invalid cookies)."""
+
+
+class ConfigError(ClientError):
+    """Raised when required client parameters are missing or invalid."""
+
+    MISSING_VARS = "Missing required parameter(s): {keys}."
+    UNSUPPORTED_VERSION = "Unsupported wallet_version '{version}'. Must be one of: {supported}."
+    INVALID_MONTHS = "Invalid duration. Choose 3, 6, or 12 months."
+    INVALID_STARS_AMOUNT = "Amount must be an integer between 50 and 1 000 000 stars."
+    INVALID_TON_AMOUNT = "Amount must be an integer between 1 and 1 000 000 000 TON."
+
+
+class CookiesError(ClientError):
+    """Raised when cookies are unreadable or missing required fields."""
+
+    READ_FAILED = "Failed to parse cookies: {exc}"
+    MISSING_KEYS = (
+        "Cookies are missing or have empty values for: {keys}. " "Open Fragment.com in your browser and copy fresh cookies."
+    )
+
+
+class FragmentAPIError(FragmentError):
+    """Raised for errors returned by Fragment's API responses."""
+
+    NO_REQUEST_ID = (
+        "Fragment did not return a request ID for '{context}'. " "The session may have expired — refresh your cookies."
+    )
+
+
+class HashFetchError(FragmentAPIError):
+    """Raised when the Fragment API hash cannot be fetched from the page."""
+
+    BAD_STATUS = "Fragment returned HTTP {status} for {url}. " "Check that your cookies are valid and not expired."
+    NOT_FOUND = (
+        "Fragment hash not found in the page source of {url}. " "The page structure may have changed or you are not logged in."
+    )
+
+
+class UserNotFoundError(FragmentAPIError):
+    """Raised when the target Telegram user is not found on Fragment."""
+
+    NOT_FOUND = (
+        "Telegram user '{username}' was not found on Fragment. " "Make sure the username is correct and the account exists."
+    )
+
+
+class TransactionError(FragmentAPIError):
+    """Raised when a TON transaction fails to build or broadcast."""
+
+    INVALID_PAYLOAD = (
+        "Fragment returned an invalid transaction payload. " "The API response is missing expected 'transaction.messages' data."
+    )
+    BROADCAST_FAILED = "Transaction broadcast failed: {exc}"
+
+
+class RequestError(FragmentAPIError):
+    """Raised when a Fragment API response cannot be parsed."""
+
+    UNPARSEABLE = "Fragment API returned an unparseable response for '{context}': {exc}"
+
+
+class VerificationError(FragmentAPIError):
+    """Raised when Fragment requires KYC verification before proceeding."""
+
+    KYC_REQUIRED = "Fragment requires identity (KYC) verification. " "Complete it at https://fragment.com/my/profile and retry."
+
+
+class OperationError(FragmentError):
+    """Raised for runtime operation failures unrelated to Fragment's API."""
+
+
+class WalletError(OperationError):
+    """Raised for TON wallet issues (connection, balance, account info)."""
+
+    LOW_BALANCE = "TON wallet balance is too low: {balance:.2f} TON. Minimum required is 0.056 TON."
+    BALANCE_CHECK_FAILED = "Wallet balance check failed: {exc}"
+    ACCOUNT_INFO_FAILED = "Failed to retrieve wallet account info: {exc}"
+
+
+class UnexpectedError(OperationError):
+    """Raised when an unexpected error occurs during an API call."""
+
+    UNEXPECTED = "An unexpected error occurred: {exc}"
+
+
+__all__ = [
+    "FragmentError",
+    "ClientError",
+    "ConfigError",
+    "CookiesError",
+    "FragmentAPIError",
+    "HashFetchError",
+    "UserNotFoundError",
+    "TransactionError",
+    "RequestError",
+    "VerificationError",
+    "OperationError",
+    "WalletError",
+    "UnexpectedError",
+]