Metadata-Version: 2.4
Name: astral_token_encoder
Version: 4.0
Summary: A versatile Python token generation and formatting library supporting custom schemas, hashing for Telegram/Discord IDs, multiple security versions, and SQLite/JSON export utilities.
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary

# TokenLib: Versatile Token Generation and Formatting

TokenLib is a powerful and flexible Python library designed for generating, formatting, and managing various types of tokens. It supports custom schema definitions, advanced security features like multiple security versions, and includes utilities for hashing sensitive IDs (e.g., Telegram/Discord) and exporting token data to common formats like SQLite and JSON.

Whether you need to create secure access tokens, unique identifiers, or session keys, TokenLib provides the tools to define your token structure, embed dynamic data, and manage your generated tokens efficiently.

## Features

*   **Custom Token Schemas**: Define the exact structure and fields of your tokens.
*   **Dynamic Data Embedding**: Easily embed user IDs, timestamps, event types, and any other relevant data.
*   **ID Hashing Utilities**: Securely hash Telegram, Discord, or other sensitive IDs within your tokens.
*   **Multiple Security Versions**: Implement different token security algorithms or formats for backward compatibility or progressive updates.
*   **Data Export**: Conveniently export generated token data to SQLite databases or JSON files.
*   **Extensible Design**: Designed to be easily extendable for custom encoding, encryption, or formatting needs.

## Installation

You can install TokenLib using pip:

bash
pip install tokenlib


## Basic Usage

### Generating Tokens with Custom Schemas

Define your token structure and generate tokens based on your specified data.

python
from tokenlib import TokenGenerator

# Initialize a token generator with a custom schema and security version
# The schema defines the fields that will be included in the token's payload.
generator_v1 = TokenGenerator(
    schema=["user_id", "session_id", "timestamp"],
    security_version=1,
    secret_key="your_super_secret_key_v1" # A real secret key is crucial for security
)

# Generate a token by providing data matching the schema
token_str_v1 = generator_v1.generate(
    user_id="alice",
    session_id="abc-123",
    timestamp=1678886400 # Example Unix timestamp
)
print(f"Generated Token (v1): {token_str_v1}")

# You can define a different schema and security version for other token types
generator_v2 = TokenGenerator(
    schema=["event_type", "entity_id", "initiator_ip"],
    security_version=2,
    secret_key="another_secret_key_for_v2" # Different secret key for different version
)

token_str_v2 = generator_v2.generate(
    event_type="login_success",
    entity_id="product_456",
    initiator_ip="192.168.1.1"
)
print(f"Generated Token (v2): {token_str_v2}")


### Hashing Telegram/Discord IDs

TokenLib provides utility functions to hash sensitive IDs before embedding them into tokens, enhancing privacy and security.

python
from tokenlib import hash_id

# Example Telegram ID hashing
telegram_id = 123456789
hashed_telegram_id = hash_id(telegram_id, service="telegram", salt="your_unique_salt")
print(f"Original Telegram ID: {telegram_id}")
print(f"Hashed Telegram ID: {hashed_telegram_id}")

# Example Discord ID hashing
discord_id = 987654321012345678
hashed_discord_id = hash_id(discord_id, service="discord", salt="another_unique_salt")
print(f"Original Discord ID: {discord_id}")
print(f"Hashed Discord ID: {hashed_discord_id}")

# You can integrate these hashed IDs into your token generation:
generator_secure = TokenGenerator(
    schema=["user_hash", "action"],
    security_version=1,
    secret_key="my_secure_secret"
)
token_with_hashed_id = generator_secure.generate(
    user_hash=hashed_telegram_id,
    action="view_profile"
)
print(f"Token with Hashed ID: {token_with_hashed_id}")


### Exporting Token Data

Generated token data can be easily exported to JSON files or SQLite databases for storage, analysis, or integration with other systems.

python
from tokenlib import TokenGenerator, export_to_json, export_to_sqlite
import os

generator = TokenGenerator(
    schema=["token_id", "item_name", "price", "generated_at"],
    security_version=1,
    secret_key="export_key"
)

# To export, it's often useful to store the data that generated the token
# along with the token string itself.
generated_tokens_data = []

# Generate several tokens and store their data
for i in range(3):
    data = {
        "token_id": f"TXN-{i+1:03d}",
        "item_name": f"Product-X{i}",
        "price": 10.99 + i,
        "generated_at": 1678886400 + i * 3600 # Increment timestamp
    }
    token_string = generator.generate(**data)
    generated_tokens_data.append({"token_string": token_string, **data})

# Export to JSON
json_filename = "tokens_export.json"
export_to_json(generated_tokens_data, json_filename)
print(f"Tokens exported to {json_filename}")

# Clean up for demonstration
# os.remove(json_filename)

# Export to SQLite
sqlite_filename = "tokens_export.db"
export_to_sqlite(generated_tokens_data, sqlite_filename, table_name="transaction_tokens")
print(f"Tokens exported to {sqlite_filename} in table 'transaction_tokens'")

# Clean up for demonstration
# os.remove(sqlite_filename)
