og-pilot 0.1.0__py3-none-any.whl

og_pilot/__init__.py

@@ -0,0 +1,136 @@
+"""
+OG Pilot Python SDK
+
+A Python client for generating OG Pilot Open Graph images via signed JWTs.
+"""
+
+from og_pilot.client import Client
+from og_pilot.config import Configuration
+from og_pilot.exceptions import ConfigurationError, OgPilotError, RequestError
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "Configuration",
+    "OgPilotError",
+    "ConfigurationError",
+    "RequestError",
+    "configure",
+    "reset_config",
+    "get_config",
+    "client",
+    "create_client",
+    "create_image",
+]
+
+# Global configuration instance
+_config: Configuration | None = None
+
+
+def get_config() -> Configuration:
+    """Get the global configuration, creating it if necessary."""
+    global _config
+    if _config is None:
+        _config = Configuration()
+    return _config
+
+
+def configure(**kwargs) -> Configuration:
+    """
+    Configure the global OG Pilot client.
+
+    Args:
+        api_key: Your OG Pilot API key
+        domain: Your domain registered with OG Pilot
+        base_url: OG Pilot API base URL (default: https://ogpilot.com)
+        open_timeout: Connection timeout in seconds (default: 5)
+        read_timeout: Read timeout in seconds (default: 10)
+
+    Returns:
+        The updated Configuration instance
+
+    Example:
+        >>> import og_pilot
+        >>> og_pilot.configure(
+        ...     api_key="your-api-key",
+        ...     domain="example.com"
+        ... )
+    """
+    global _config
+    if _config is None:
+        _config = Configuration(**kwargs)
+    else:
+        for key, value in kwargs.items():
+            if hasattr(_config, key):
+                setattr(_config, key, value)
+    return _config
+
+
+def reset_config() -> None:
+    """Reset the global configuration to defaults."""
+    global _config
+    _config = None
+
+
+def client() -> Client:
+    """Get a client instance using the global configuration."""
+    return Client(get_config())
+
+
+def create_client(**kwargs) -> Client:
+    """
+    Create a new client with custom configuration.
+
+    Args:
+        api_key: Your OG Pilot API key
+        domain: Your domain registered with OG Pilot
+        base_url: OG Pilot API base URL
+        open_timeout: Connection timeout in seconds
+        read_timeout: Read timeout in seconds
+
+    Returns:
+        A new Client instance
+
+    Example:
+        >>> from og_pilot import create_client
+        >>> client = create_client(
+        ...     api_key="your-api-key",
+        ...     domain="example.com"
+        ... )
+    """
+    config = Configuration(**kwargs)
+    return Client(config)
+
+
+def create_image(
+    params: dict | None = None,
+    *,
+    json: bool = False,
+    iat: int | float | None = None,
+    headers: dict[str, str] | None = None,
+    **kwargs,
+) -> str | dict:
+    """
+    Generate an OG Pilot image URL using the global configuration.
+
+    Args:
+        params: Dictionary of template parameters
+        json: If True, return JSON metadata instead of URL
+        iat: Issue time for cache busting (Unix timestamp or datetime)
+        headers: Additional HTTP headers
+        **kwargs: Additional template parameters (merged with params)
+
+    Returns:
+        Image URL string or JSON metadata dict if json=True
+
+    Example:
+        >>> import og_pilot
+        >>> og_pilot.configure(api_key="...", domain="example.com")
+        >>> url = og_pilot.create_image(
+        ...     template="blog_post",
+        ...     title="My Blog Post",
+        ...     description="A great article"
+        ... )
+    """
+    merged_params = {**(params or {}), **kwargs}
+    return client().create_image(merged_params, json=json, iat=iat, headers=headers)

og_pilot/client.py

@@ -0,0 +1,191 @@
+"""
+OG Pilot Client
+
+HTTP client for the OG Pilot API.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING
+from urllib.parse import urlencode, urljoin
+
+import requests
+
+from og_pilot import jwt_encoder
+from og_pilot.exceptions import ConfigurationError, RequestError
+
+if TYPE_CHECKING:
+    from og_pilot.config import Configuration
+
+
+ENDPOINT_PATH = "/api/v1/images"
+
+
+class Client:
+    """
+    OG Pilot API client.
+
+    Example:
+        >>> from og_pilot import Client, Configuration
+        >>> config = Configuration(api_key="...", domain="example.com")
+        >>> client = Client(config)
+        >>> url = client.create_image({"template": "default", "title": "Hello"})
+    """
+
+    def __init__(self, config: Configuration):
+        """
+        Initialize the client with configuration.
+
+        Args:
+            config: Configuration instance
+        """
+        self.config = config
+
+    def create_image(
+        self,
+        params: dict | None = None,
+        *,
+        json_response: bool = False,
+        iat: int | float | datetime | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> str | dict:
+        """
+        Generate an OG Pilot image URL or fetch JSON metadata.
+
+        Args:
+            params: Dictionary of template parameters (must include 'title')
+            json_response: If True, return JSON metadata instead of URL
+            iat: Issue time for cache busting. Can be Unix timestamp (int/float)
+                 or datetime object. If omitted, image is cached indefinitely.
+            headers: Additional HTTP headers to send with the request
+
+        Returns:
+            Image URL string, or JSON metadata dict if json_response=True
+
+        Raises:
+            ConfigurationError: If API key or domain is missing
+            RequestError: If the API request fails
+            ValueError: If required parameters are missing
+        """
+        url = self._build_url(params or {}, iat)
+        response = self._request(url, json_response=json_response, headers=headers or {})
+
+        if json_response:
+            return json.loads(response.text)
+
+        # Return the redirect location or the final URL
+        return response.headers.get("Location") or response.url or str(url)
+
+    def _request(
+        self,
+        url: str,
+        *,
+        json_response: bool,
+        headers: dict[str, str],
+    ) -> requests.Response:
+        """Make an HTTP request to the OG Pilot API."""
+        request_headers = {}
+        if json_response:
+            request_headers["Accept"] = "application/json"
+        request_headers.update(headers)
+
+        timeout = (self.config.open_timeout, self.config.read_timeout)
+
+        try:
+            response = requests.get(
+                url,
+                headers=request_headers,
+                timeout=timeout,
+                allow_redirects=False,
+            )
+
+            if response.status_code >= 400:
+                raise RequestError(
+                    f"OG Pilot request failed with status {response.status_code}: {response.text}",
+                    status_code=response.status_code,
+                )
+
+            return response
+
+        except requests.exceptions.SSLError as e:
+            raise RequestError(f"OG Pilot request failed with SSL error: {e}")
+        except requests.exceptions.ConnectTimeout as e:
+            raise RequestError(f"OG Pilot request timed out during connection: {e}")
+        except requests.exceptions.ReadTimeout as e:
+            raise RequestError(f"OG Pilot request timed out during read: {e}")
+        except requests.exceptions.RequestException as e:
+            raise RequestError(f"OG Pilot request failed: {e}")
+
+    def _build_url(self, params: dict, iat: int | float | datetime | None) -> str:
+        """Build the signed URL for the image request."""
+        payload = self._build_payload(params, iat)
+        token = jwt_encoder.encode(payload, self._api_key)
+        base_url = urljoin(self.config.base_url, ENDPOINT_PATH)
+        return f"{base_url}?{urlencode({'token': token})}"
+
+    def _build_payload(self, params: dict, iat: int | float | datetime | None) -> dict:
+        """Build the JWT payload with required claims."""
+        payload = dict(params)
+
+        if iat is not None:
+            payload["iat"] = _normalize_iat(iat)
+
+        if "iss" not in payload or not payload["iss"]:
+            payload["iss"] = self._domain
+
+        if "sub" not in payload or not payload["sub"]:
+            payload["sub"] = self._api_key_prefix
+
+        self._validate_payload(payload)
+        return payload
+
+    def _validate_payload(self, payload: dict) -> None:
+        """Validate required payload fields."""
+        if not payload.get("iss"):
+            raise ConfigurationError("OG Pilot domain is missing")
+
+        if not payload.get("sub"):
+            raise ConfigurationError("OG Pilot API key prefix is missing")
+
+        if not payload.get("title"):
+            raise ValueError("OG Pilot title is required")
+
+    @property
+    def _api_key(self) -> str:
+        """Get the API key, raising an error if not configured."""
+        if self.config.api_key:
+            return self.config.api_key
+        raise ConfigurationError("OG Pilot API key is missing")
+
+    @property
+    def _domain(self) -> str:
+        """Get the domain, raising an error if not configured."""
+        if self.config.domain:
+            return self.config.domain
+        raise ConfigurationError("OG Pilot domain is missing")
+
+    @property
+    def _api_key_prefix(self) -> str:
+        """Get the first 8 characters of the API key."""
+        return self._api_key[:8]
+
+
+def _normalize_iat(iat: int | float | datetime) -> int:
+    """
+    Normalize the iat (issued at) value to Unix timestamp seconds.
+
+    Handles:
+    - datetime objects
+    - Unix timestamps in milliseconds (> 100000000000)
+    - Unix timestamps in seconds
+    """
+    if isinstance(iat, datetime):
+        return int(iat.timestamp())
+
+    # If it looks like milliseconds, convert to seconds
+    if iat > 100_000_000_000:
+        return int(iat / 1000)
+
+    return int(iat)

og_pilot/config.py

@@ -0,0 +1,31 @@
+"""
+OG Pilot Configuration
+
+Configuration management for the OG Pilot SDK.
+"""
+
+import os
+from dataclasses import dataclass, field
+
+
+DEFAULT_BASE_URL = "https://ogpilot.com"
+
+
+@dataclass
+class Configuration:
+    """
+    Configuration for the OG Pilot client.
+
+    Attributes:
+        api_key: Your OG Pilot API key. Defaults to OG_PILOT_API_KEY env var.
+        domain: Your domain registered with OG Pilot. Defaults to OG_PILOT_DOMAIN env var.
+        base_url: OG Pilot API base URL. Defaults to https://ogpilot.com.
+        open_timeout: Connection timeout in seconds. Defaults to 5.
+        read_timeout: Read timeout in seconds. Defaults to 10.
+    """
+
+    api_key: str | None = field(default_factory=lambda: os.environ.get("OG_PILOT_API_KEY"))
+    domain: str | None = field(default_factory=lambda: os.environ.get("OG_PILOT_DOMAIN"))
+    base_url: str = DEFAULT_BASE_URL
+    open_timeout: float = 5.0
+    read_timeout: float = 10.0

og_pilot/django/__init__.py

@@ -0,0 +1,21 @@
+"""
+OG Pilot Django Integration
+
+Django app for easy OG Pilot integration.
+
+Add 'og_pilot.django' to your INSTALLED_APPS to use template tags and
+management commands.
+
+Example settings.py:
+    INSTALLED_APPS = [
+        ...
+        'og_pilot.django',
+    ]
+
+    OG_PILOT = {
+        'API_KEY': 'your-api-key',  # or use OG_PILOT_API_KEY env var
+        'DOMAIN': 'example.com',     # or use OG_PILOT_DOMAIN env var
+    }
+"""
+
+default_app_config = "og_pilot.django.apps.OgPilotConfig"

og_pilot/django/apps.py

@@ -0,0 +1,37 @@
+"""
+OG Pilot Django App Configuration
+"""
+
+from django.apps import AppConfig
+from django.conf import settings
+
+
+class OgPilotConfig(AppConfig):
+    """Django app configuration for OG Pilot."""
+
+    name = "og_pilot.django"
+    verbose_name = "OG Pilot"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        """Configure OG Pilot from Django settings when the app is ready."""
+        import og_pilot
+
+        # Get OG_PILOT settings dict, defaulting to empty dict
+        og_pilot_settings = getattr(settings, "OG_PILOT", {})
+
+        config_mapping = {
+            "API_KEY": "api_key",
+            "DOMAIN": "domain",
+            "BASE_URL": "base_url",
+            "OPEN_TIMEOUT": "open_timeout",
+            "READ_TIMEOUT": "read_timeout",
+        }
+
+        config_kwargs = {}
+        for settings_key, config_key in config_mapping.items():
+            if settings_key in og_pilot_settings:
+                config_kwargs[config_key] = og_pilot_settings[settings_key]
+
+        if config_kwargs:
+            og_pilot.configure(**config_kwargs)

og_pilot/django/management/__init__.py

@@ -0,0 +1 @@
+# Django management commands

og_pilot/django/management/commands/__init__.py

@@ -0,0 +1 @@
+# OG Pilot management commands

og_pilot/django/management/commands/og_pilot_check.py

@@ -0,0 +1,66 @@
+"""
+OG Pilot Configuration Check Command
+
+Management command to verify OG Pilot configuration.
+"""
+
+from django.core.management.base import BaseCommand
+
+import og_pilot
+from og_pilot.exceptions import ConfigurationError
+
+
+class Command(BaseCommand):
+    """Check OG Pilot configuration and test connectivity."""
+
+    help = "Check OG Pilot configuration and optionally test with a sample request"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--test",
+            action="store_true",
+            help="Send a test request to verify API connectivity",
+        )
+
+    def handle(self, *args, **options):
+        self.stdout.write("Checking OG Pilot configuration...\n")
+
+        config = og_pilot.get_config()
+
+        # Check API key
+        if config.api_key:
+            masked_key = config.api_key[:4] + "*" * (len(config.api_key) - 8) + config.api_key[-4:]
+            self.stdout.write(self.style.SUCCESS(f"  API Key: {masked_key}"))
+        else:
+            self.stdout.write(self.style.ERROR("  API Key: NOT SET"))
+            self.stdout.write(
+                "    Set OG_PILOT_API_KEY env var or OG_PILOT['API_KEY'] in settings"
+            )
+
+        # Check domain
+        if config.domain:
+            self.stdout.write(self.style.SUCCESS(f"  Domain: {config.domain}"))
+        else:
+            self.stdout.write(self.style.ERROR("  Domain: NOT SET"))
+            self.stdout.write(
+                "    Set OG_PILOT_DOMAIN env var or OG_PILOT['DOMAIN'] in settings"
+            )
+
+        # Show other settings
+        self.stdout.write(f"  Base URL: {config.base_url}")
+        self.stdout.write(f"  Open Timeout: {config.open_timeout}s")
+        self.stdout.write(f"  Read Timeout: {config.read_timeout}s")
+
+        if options["test"]:
+            self.stdout.write("\nTesting API connectivity...")
+            try:
+                url = og_pilot.create_image(
+                    template="default",
+                    title="OG Pilot Test Image",
+                )
+                self.stdout.write(self.style.SUCCESS(f"  Success! Generated URL:"))
+                self.stdout.write(f"  {url}")
+            except ConfigurationError as e:
+                self.stdout.write(self.style.ERROR(f"  Configuration Error: {e}"))
+            except Exception as e:
+                self.stdout.write(self.style.ERROR(f"  Error: {e}"))

og_pilot/django/templates/og_pilot/meta_tags.html

@@ -0,0 +1,12 @@
+<!-- Open Graph meta tags generated by OG Pilot -->
+<meta property="og:title" content="{{ title }}" />
+{% if description %}<meta property="og:description" content="{{ description }}" />{% endif %}
+<meta property="og:image" content="{{ image_url }}" />
+<meta property="og:type" content="website" />
+{% if site_name %}<meta property="og:site_name" content="{{ site_name }}" />{% endif %}
+
+<!-- Twitter Card meta tags -->
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content="{{ title }}" />
+{% if description %}<meta name="twitter:description" content="{{ description }}" />{% endif %}
+<meta name="twitter:image" content="{{ image_url }}" />

og_pilot/django/templatetags/__init__.py

@@ -0,0 +1 @@
+# Django template tags for OG Pilot

og_pilot/django/templatetags/og_pilot_tags.py

@@ -0,0 +1,109 @@
+"""
+OG Pilot Template Tags
+
+Django template tags for generating OG Pilot images.
+
+Usage in templates:
+    {% load og_pilot_tags %}
+
+    <!-- Generate image URL -->
+    {% og_pilot_image template="blog_post" title="My Post" as og_url %}
+    <meta property="og:image" content="{{ og_url }}" />
+
+    <!-- Or use the simple tag directly -->
+    <meta property="og:image" content="{% og_pilot_url template='default' title='Hello' %}" />
+"""
+
+import time
+
+from django import template
+
+import og_pilot
+
+register = template.Library()
+
+
+@register.simple_tag
+def og_pilot_url(
+    title: str,
+    template: str = "default",
+    iat: int | None = None,
+    **kwargs,
+) -> str:
+    """
+    Generate an OG Pilot image URL.
+
+    Args:
+        title: The title for the OG image (required)
+        template: Template name to use (default: "default")
+        iat: Issue time for cache busting. If not provided, uses current day.
+        **kwargs: Additional template parameters
+
+    Returns:
+        The generated image URL
+
+    Example:
+        {% og_pilot_url title="My Page Title" template="blog_post" author="John" %}
+    """
+    params = {
+        "template": template,
+        "title": title,
+        **kwargs,
+    }
+
+    # Use current day for cache busting if not provided
+    if iat is None:
+        # Round to start of day for daily cache busting
+        iat = int(time.time()) // 86400 * 86400
+
+    return og_pilot.create_image(params, iat=iat)
+
+
+@register.simple_tag
+def og_pilot_image(
+    title: str,
+    template: str = "default",
+    iat: int | None = None,
+    **kwargs,
+) -> str:
+    """
+    Alias for og_pilot_url for semantic clarity.
+
+    Example:
+        {% og_pilot_image title="My Blog Post" template="blog" as og_url %}
+    """
+    return og_pilot_url(title=title, template=template, iat=iat, **kwargs)
+
+
+@register.inclusion_tag("og_pilot/meta_tags.html")
+def og_pilot_meta_tags(
+    title: str,
+    description: str = "",
+    template: str = "default",
+    site_name: str = "",
+    **kwargs,
+) -> dict:
+    """
+    Render complete Open Graph meta tags with OG Pilot image.
+
+    Args:
+        title: Page title
+        description: Page description
+        template: OG Pilot template name
+        site_name: Site name for og:site_name
+        **kwargs: Additional template parameters
+
+    Returns:
+        Context dict for the template
+
+    Example:
+        {% og_pilot_meta_tags title="My Page" description="Description" %}
+    """
+    image_url = og_pilot_url(title=title, template=template, **kwargs)
+
+    return {
+        "title": title,
+        "description": description,
+        "image_url": image_url,
+        "site_name": site_name,
+    }

og_pilot/exceptions.py

@@ -0,0 +1,25 @@
+"""
+OG Pilot Exceptions
+
+Custom exceptions for the OG Pilot SDK.
+"""
+
+
+class OgPilotError(Exception):
+    """Base exception for all OG Pilot errors."""
+
+    pass
+
+
+class ConfigurationError(OgPilotError):
+    """Raised when there's a configuration problem."""
+
+    pass
+
+
+class RequestError(OgPilotError):
+    """Raised when an API request fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code

og_pilot/jwt_encoder.py

@@ -0,0 +1,24 @@
+"""
+OG Pilot JWT Encoder
+
+JWT encoding utilities using HS256 algorithm.
+"""
+
+import jwt
+
+
+ALGORITHM = "HS256"
+
+
+def encode(payload: dict, secret: str) -> str:
+    """
+    Encode a payload as a JWT token using HS256 algorithm.
+
+    Args:
+        payload: Dictionary containing the JWT claims
+        secret: Secret key for signing
+
+    Returns:
+        Encoded JWT token string
+    """
+    return jwt.encode(payload, secret, algorithm=ALGORITHM)

og_pilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,502 @@
+Metadata-Version: 2.4
+Name: og-pilot
+Version: 0.1.0
+Summary: Python client for the OG Pilot Open Graph image generator with Django integration
+Project-URL: Homepage, https://ogpilot.com
+Project-URL: Documentation, https://ogpilot.com/docs
+Project-URL: Repository, https://github.com/sunergos-ro/og-pilot-python
+Project-URL: Issues, https://github.com/sunergos-ro/og-pilot-python/issues
+Project-URL: Changelog, https://github.com/sunergos-ro/og-pilot-python/commits/main
+Author-email: Sunergos IT LLC <office@sunergos.ro>, Raul Popadineti <raul@sunergos.ro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,meta-tags,og-image,og-pilot,open-graph,seo,social-media
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-requests>=2.31.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Description-Content-Type: text/markdown
+
+# OG Pilot Python
+
+A Python client for generating OG Pilot Open Graph images via signed JWTs, with first-class Django integration.
+
+## Installation
+
+```bash
+pip install og-pilot
+```
+
+For Django integration:
+
+```bash
+pip install og-pilot[django]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import og_pilot
+
+# Configure globally (reads from OG_PILOT_API_KEY and OG_PILOT_DOMAIN env vars by default)
+og_pilot.configure(
+    api_key="your-api-key",
+    domain="example.com"
+)
+
+# Generate an image URL
+image_url = og_pilot.create_image(
+    template="blog_post",
+    title="How to Build Amazing OG Images",
+    description="A complete guide to social media previews",
+    author_name="Jane Smith",
+)
+
+print(image_url)
+# https://ogpilot.com/api/v1/images?token=eyJ...
+```
+
+### Using Environment Variables
+
+The SDK automatically reads from environment variables:
+
+```bash
+export OG_PILOT_API_KEY="your-api-key"
+export OG_PILOT_DOMAIN="example.com"
+```
+
+```python
+import og_pilot
+
+# No configuration needed - uses env vars
+url = og_pilot.create_image(title="My Page", template="default")
+```
+
+### Cache Busting with `iat`
+
+By default, OG Pilot caches images indefinitely. Use `iat` (issued at) to refresh the cache:
+
+```python
+import time
+from datetime import datetime
+
+# Using Unix timestamp
+url = og_pilot.create_image(
+    title="My Post",
+    template="blog",
+    iat=int(time.time())  # Changes daily
+)
+
+# Using datetime
+url = og_pilot.create_image(
+    title="My Post",
+    template="blog",
+    iat=datetime.now()
+)
+```
+
+### Get JSON Metadata
+
+```python
+data = og_pilot.create_image(
+    title="Hello OG Pilot",
+    template="page",
+    json=True
+)
+print(data)  # {"url": "...", "width": 1200, "height": 630, ...}
+```
+
+### Custom Client Instance
+
+For multiple configurations or dependency injection:
+
+```python
+from og_pilot import create_client
+
+client = create_client(
+    api_key="your-api-key",
+    domain="example.com",
+    open_timeout=10,
+    read_timeout=30,
+)
+
+url = client.create_image({"template": "default", "title": "Hello"})
+```
+
+## Django Integration
+
+### 1. Add to Installed Apps
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    'og_pilot.django',
+]
+```
+
+### 2. Configure Settings
+
+```python
+# settings.py
+
+# Option 1: Using settings dict
+OG_PILOT = {
+    'API_KEY': 'your-api-key',  # or use OG_PILOT_API_KEY env var
+    'DOMAIN': 'example.com',     # or use OG_PILOT_DOMAIN env var
+    # Optional:
+    # 'BASE_URL': 'https://ogpilot.com',
+    # 'OPEN_TIMEOUT': 5,
+    # 'READ_TIMEOUT': 10,
+}
+
+# Option 2: Using environment variables (no settings needed)
+# Just set OG_PILOT_API_KEY and OG_PILOT_DOMAIN
+```
+
+### 3. Verify Configuration
+
+```bash
+python manage.py og_pilot_check
+python manage.py og_pilot_check --test  # Also sends a test request
+```
+
+### 4. Use in Templates
+
+```html
+{% load og_pilot_tags %}
+
+<!DOCTYPE html>
+<html>
+<head>
+    <!-- Option 1: Generate URL and use manually -->
+    {% og_pilot_image title=page.title template="blog_post" as og_image_url %}
+    <meta property="og:image" content="{{ og_image_url }}" />
+    <meta property="og:title" content="{{ page.title }}" />
+
+    <!-- Option 2: Simple tag (outputs URL directly) -->
+    <meta property="og:image" content="{% og_pilot_url title=page.title template='default' %}" />
+
+    <!-- Option 3: Complete meta tags (requires template) -->
+    {% og_pilot_meta_tags title=page.title description=page.description template="blog" %}
+</head>
+<body>
+    ...
+</body>
+</html>
+```
+
+### 5. Use in Views
+
+```python
+from django.shortcuts import render
+import og_pilot
+
+def blog_post(request, slug):
+    post = get_object_or_404(Post, slug=slug)
+    
+    og_image_url = og_pilot.create_image(
+        template="blog_post",
+        title=post.title,
+        description=post.excerpt,
+        author_name=post.author.name,
+        publish_date=post.published_at.strftime("%Y-%m-%d"),
+    )
+    
+    return render(request, 'blog/post.html', {
+        'post': post,
+        'og_image_url': og_image_url,
+    })
+```
+
+### Custom Meta Tags Template
+
+Create `templates/og_pilot/meta_tags.html` in your project to customize the output of `{% og_pilot_meta_tags %}`:
+
+```html
+<!-- templates/og_pilot/meta_tags.html -->
+<meta property="og:title" content="{{ title }}" />
+<meta property="og:description" content="{{ description }}" />
+<meta property="og:image" content="{{ image_url }}" />
+<meta property="og:type" content="article" />
+<meta property="og:site_name" content="{{ site_name }}" />
+
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content="{{ title }}" />
+<meta name="twitter:description" content="{{ description }}" />
+<meta name="twitter:image" content="{{ image_url }}" />
+```
+
+## Configuration Options
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `api_key` | `OG_PILOT_API_KEY` | None | Your OG Pilot API key (required) |
+| `domain` | `OG_PILOT_DOMAIN` | None | Your registered domain (required) |
+| `base_url` | - | `https://ogpilot.com` | OG Pilot API URL |
+| `open_timeout` | - | `5` | Connection timeout (seconds) |
+| `read_timeout` | - | `10` | Read timeout (seconds) |
+
+## Error Handling
+
+```python
+from og_pilot import create_image
+from og_pilot.exceptions import ConfigurationError, RequestError
+
+try:
+    url = create_image(title="My Post", template="blog")
+except ConfigurationError as e:
+    # Missing API key or domain
+    print(f"Configuration error: {e}")
+except RequestError as e:
+    # API request failed
+    print(f"Request error: {e}")
+    if e.status_code:
+        print(f"Status code: {e.status_code}")
+except ValueError as e:
+    # Missing required parameter (e.g., title)
+    print(f"Validation error: {e}")
+```
+
+## API Reference
+
+### Module-level Functions
+
+- `og_pilot.configure(**kwargs)` - Configure the global client
+- `og_pilot.reset_config()` - Reset to default configuration
+- `og_pilot.get_config()` - Get the current configuration
+- `og_pilot.client()` - Get a client using global config
+- `og_pilot.create_client(**kwargs)` - Create a new client with custom config
+- `og_pilot.create_image(params, *, json=False, iat=None, headers=None, **kwargs)` - Generate image URL
+
+### Client Class
+
+```python
+from og_pilot import Client, Configuration
+
+config = Configuration(api_key="...", domain="...")
+client = Client(config)
+
+# Generate URL
+url = client.create_image(
+    params={"template": "default", "title": "Hello"},
+    json_response=False,  # Set True for JSON metadata
+    iat=None,             # Optional cache busting timestamp
+    headers={},           # Optional additional headers
+)
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/sunergos-ro/og-pilot-python.git
+cd og-pilot-python
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linter
+ruff check .
+
+# Run type checker
+mypy og_pilot
+```
+
+---
+
+# Publishing to PyPI
+
+This section explains how to publish the package to PyPI so users can install it with `pip install og-pilot`.
+
+## Prerequisites
+
+1. **Create PyPI Account**: Register at https://pypi.org/account/register/
+
+2. **Create API Token**: Go to https://pypi.org/manage/account/token/ and create a token with "Upload packages" scope.
+
+3. **Install Build Tools**:
+   ```bash
+   pip install build twine
+   ```
+
+## Publishing Steps
+
+### 1. Update Version
+
+Edit `pyproject.toml` and `og_pilot/__init__.py` to update the version number:
+
+```python
+# og_pilot/__init__.py
+__version__ = "0.2.0"  # New version
+```
+
+```toml
+# pyproject.toml
+[project]
+version = "0.2.0"
+```
+
+### 2. Build the Package
+
+```bash
+# Clean previous builds
+rm -rf dist/ build/ *.egg-info
+
+# Build source distribution and wheel
+python -m build
+```
+
+This creates:
+- `dist/og_pilot-0.1.0.tar.gz` (source distribution)
+- `dist/og_pilot-0.1.0-py3-none-any.whl` (wheel)
+
+### 3. Test on TestPyPI (Optional but Recommended)
+
+```bash
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Test installation from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ og-pilot
+```
+
+### 4. Upload to PyPI
+
+```bash
+# Upload to production PyPI
+twine upload dist/*
+```
+
+You'll be prompted for credentials:
+- Username: `__token__`
+- Password: Your PyPI API token (starts with `pypi-`)
+
+### 5. Configure Credentials (Optional)
+
+To avoid entering credentials each time, create `~/.pypirc`:
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-YOUR-TOKEN-HERE
+
+[testpypi]
+username = __token__
+password = pypi-YOUR-TESTPYPI-TOKEN-HERE
+```
+
+Then secure it:
+```bash
+chmod 600 ~/.pypirc
+```
+
+## Automated Publishing with GitHub Actions
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      
+      - name: Install build dependencies
+        run: pip install build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing - configure at pypi.org
+```
+
+### Setting Up Trusted Publishing
+
+1. Go to your PyPI project: https://pypi.org/manage/project/og-pilot/settings/publishing/
+2. Add a new publisher:
+   - Owner: `sunergos-ro`
+   - Repository: `og-pilot-python`
+   - Workflow: `publish.yml`
+   - Environment: `release`
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+- `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
+- MAJOR: Breaking changes
+- MINOR: New features (backward compatible)
+- PATCH: Bug fixes (backward compatible)
+
+## Release Checklist
+
+- [ ] Update version in `pyproject.toml` and `og_pilot/__init__.py`
+- [ ] Update CHANGELOG (if you have one)
+- [ ] Run tests: `pytest`
+- [ ] Run linter: `ruff check .`
+- [ ] Run type checker: `mypy og_pilot`
+- [ ] Build: `python -m build`
+- [ ] Test locally: `pip install dist/*.whl`
+- [ ] Upload to TestPyPI (optional)
+- [ ] Upload to PyPI
+- [ ] Create GitHub release with tag `v0.1.0`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

og_pilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+og_pilot/__init__.py,sha256=u-SYq0BdlQbchvCHrD5LCllAFCFj5540mija6b0gXlI,3601
+og_pilot/client.py,sha256=f7IpBwPLgHrmXlRNa2DocV2px1Uf3-DDOOGuiwc5d64,6166
+og_pilot/config.py,sha256=oiGorISJ2TyYg_P9OmFDLg2CCnP-Z2WVZTGSaXymhyw,939
+og_pilot/exceptions.py,sha256=MVoG2d8zHZds2HeTHMxIkFzBSBDfcRGl3sVWGGxqP80,493
+og_pilot/jwt_encoder.py,sha256=ZA9NCedRMKmN8NBm4Z-8iQGhFMw-0C1gKbhHfIUrHP0,445
+og_pilot/django/__init__.py,sha256=GNOD10fPV5Nof1zEo81sOPfisyFEH7_qlUTto0j2Yrs,484
+og_pilot/django/apps.py,sha256=9v1HxlzgXA-rCvyDLbRc1UAfN_ZMRsUDlZkFP-RHLbI,1080
+og_pilot/django/management/__init__.py,sha256=wc5DFEklUo-wB-6VAAmsV5UTbo5s3t936Lu61z4lojs,29
+og_pilot/django/management/commands/__init__.py,sha256=EDBTRj1R3MOkHoQl8JNGEc6RGcr4nXwQfUn-EpE2QVU,31
+og_pilot/django/management/commands/og_pilot_check.py,sha256=rK5gmCO4vIwK60tEkKWP0JjVmv1_1s2OOL6uPaL2mDg,2381
+og_pilot/django/templates/og_pilot/meta_tags.html,sha256=aTgbnMK_nPKeFheoigabGGVkqXlInjawL3tuXW7tggQ,681
+og_pilot/django/templatetags/__init__.py,sha256=VvpRwKhOltVZqavfw8J4GY6Mx6QT0_RY4rSVNlQcmaA,36
+og_pilot/django/templatetags/og_pilot_tags.py,sha256=cVzrSSFh0OIQXyr52tsk3PerReT-ltrSmtBs7IF_RZ0,2656
+og_pilot-0.1.0.dist-info/METADATA,sha256=drIjLG6dKNDvTnHuHjC9QQvFFxiZAW-XlLEBLQO8V1E,12385
+og_pilot-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+og_pilot-0.1.0.dist-info/licenses/LICENSE,sha256=PhtdYW0pdQpFJhyX9F2KyaYgbeu0zhADaEsy2UJUL2k,1072
+og_pilot-0.1.0.dist-info/RECORD,,

og_pilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

og_pilot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sunergos IT LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.