📝 Add MkDocs documentation with GitHub Pages deployment

Author: SamPetherbridge

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    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@v4

docs/api/client.md

@@ -0,0 +1,10 @@
+# Client Reference
+
+::: search_ads_api.AppleSearchAdsClient
+    options:
+      show_root_heading: true
+      show_source: false
+      members:
+        - from_env
+        - campaigns
+        - reports

docs/api/exceptions.md

@@ -0,0 +1,90 @@
+# Exceptions Reference
+
+## Exception Hierarchy
+
+```
+AppleSearchAdsError
+├── AuthenticationError
+├── ConfigurationError
+├── NotFoundError
+├── RateLimitError
+└── ValidationError
+```
+
+## AppleSearchAdsError
+
+Base exception for all API errors.
+
+```python
+from search_ads_api import AppleSearchAdsError
+
+try:
+    client.campaigns.list()
+except AppleSearchAdsError as e:
+    print(f"API error: {e}")
+```
+
+## AuthenticationError
+
+Raised when authentication fails.
+
+```python
+from search_ads_api import AuthenticationError
+
+try:
+    client.campaigns.list()
+except AuthenticationError:
+    print("Invalid credentials or expired token")
+```
+
+## ConfigurationError
+
+Raised when client configuration is invalid.
+
+```python
+from search_ads_api import ConfigurationError
+
+try:
+    client = AppleSearchAdsClient(...)
+except ConfigurationError as e:
+    print(f"Configuration error: {e}")
+```
+
+## NotFoundError
+
+Raised when a resource is not found.
+
+```python
+from search_ads_api import NotFoundError
+
+try:
+    campaign = client.campaigns.get(123)
+except NotFoundError:
+    print("Campaign not found")
+```
+
+## RateLimitError
+
+Raised when API rate limit is exceeded.
+
+```python
+from search_ads_api import RateLimitError
+
+try:
+    client.campaigns.list()
+except RateLimitError as e:
+    print(f"Rate limited, retry after: {e.retry_after}")
+```
+
+## ValidationError
+
+Raised when request validation fails.
+
+```python
+from search_ads_api import ValidationError
+
+try:
+    client.campaigns.create(invalid_data)
+except ValidationError as e:
+    print(f"Validation error: {e}")
+```

docs/api/models.md

@@ -0,0 +1,54 @@
+# Models Reference
+
+## Campaigns
+
+::: search_ads_api.models.Campaign
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: search_ads_api.models.CampaignCreate
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: search_ads_api.models.CampaignUpdate
+    options:
+      show_root_heading: true
+      show_source: false
+
+## Ad Groups
+
+::: search_ads_api.models.AdGroup
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: search_ads_api.models.AdGroupCreate
+    options:
+      show_root_heading: true
+      show_source: false
+
+## Keywords
+
+::: search_ads_api.models.Keyword
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: search_ads_api.models.KeywordCreate
+    options:
+      show_root_heading: true
+      show_source: false
+
+## Common
+
+::: search_ads_api.models.Money
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: search_ads_api.models.Selector
+    options:
+      show_root_heading: true
+      show_source: false

docs/getting-started/authentication.md

@@ -0,0 +1,75 @@
+# Authentication
+
+The Apple Search Ads API uses OAuth 2.0 with JWT tokens signed using ES256 (ECDSA).
+
+## Getting API Credentials
+
+1. Go to [Apple Search Ads](https://searchads.apple.com)
+2. Navigate to **Settings** > **API**
+3. Create a new API key
+4. Download your private key (`.pem` file)
+5. Note your Client ID, Team ID, and Key ID
+
+## Configuration
+
+### Environment Variables
+
+Set the following environment variables:
+
+```bash
+export ASA_CLIENT_ID="SEARCHADS.your-client-id"
+export ASA_TEAM_ID="SEARCHADS.your-team-id"
+export ASA_KEY_ID="your-key-id"
+export ASA_ORG_ID="123456"
+export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
+```
+
+### Using a .env File
+
+Create a `.env` file in your project:
+
+```bash
+ASA_CLIENT_ID=SEARCHADS.your-client-id
+ASA_TEAM_ID=SEARCHADS.your-team-id
+ASA_KEY_ID=your-key-id
+ASA_ORG_ID=123456
+ASA_PRIVATE_KEY_PATH=private-key.pem
+```
+
+### Direct Configuration
+
+You can also pass credentials directly:
+
+```python
+from search_ads_api import AppleSearchAdsClient
+
+client = AppleSearchAdsClient(
+    client_id="SEARCHADS.xxx",
+    team_id="SEARCHADS.xxx",
+    key_id="xxx",
+    org_id=123456,
+    private_key_path="private-key.pem",
+)
+```
+
+Or with the private key content:
+
+```python
+client = AppleSearchAdsClient(
+    client_id="SEARCHADS.xxx",
+    team_id="SEARCHADS.xxx",
+    key_id="xxx",
+    org_id=123456,
+    private_key="-----BEGIN EC PRIVATE KEY-----\n...",
+)
+```
+
+## Token Management
+
+The client automatically handles:
+
+- JWT creation and signing
+- Token refresh when expired
+- Request authentication headers
+
+You don't need to manage tokens manually.

docs/getting-started/installation.md

@@ -0,0 +1,45 @@
+# Installation
+
+## Using uv (Recommended)
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package manager:
+
+```bash
+uv add search-ads-api
+```
+
+With pandas support for DataFrame exports:
+
+```bash
+uv add "search-ads-api[pandas]"
+```
+
+## Using pip
+
+```bash
+pip install search-ads-api
+```
+
+With pandas support:
+
+```bash
+pip install "search-ads-api[pandas]"
+```
+
+## Requirements
+
+- Python 3.13+
+- Valid Apple Search Ads API credentials
+
+## Dependencies
+
+The package has minimal dependencies:
+
+- `httpx` - HTTP client with async support
+- `pydantic` - Data validation
+- `pydantic-settings` - Settings management
+- `pyjwt[crypto]` - JWT authentication
+
+Optional:
+
+- `pandas` - DataFrame export support