asa-api-client 0.1.0__tar.gz

asa_api_client-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,80 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["type: bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the form below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Create a client with...
+        2. Call method...
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Package Version
+      description: What version of search-ads-api are you using?
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: What version of Python are you using?
+      placeholder: "3.13.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem (logs, screenshots, etc.)

asa_api_client-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or Discussion
+    url: https://github.com/SamPetherbridge/asa-api-client/discussions
+    about: Ask questions or start a discussion

asa_api_client-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+labels: ["type: feature"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please fill out the form below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem would this feature solve? Is it related to a frustration?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like to see.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or examples.

asa_api_client-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "⬆️"
+    labels:
+      - "dependencies"
+    groups:
+      python-packages:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "👷"
+    labels:
+      - "dependencies"
+      - "github-actions"

asa_api_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run formatting check
+        run: uv run ruff format --check .
+
+      - name: Run type checking
+        run: uv run mypy asa_api_client
+
+      - name: Run tests
+        run: uv run pytest --cov=asa_api_client --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

asa_api_client-0.1.0/.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

asa_api_client-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

asa_api_client-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# Documentation
+site/
+
+# Environment
+.env
+.env.local
+*.pem
+
+# OS
+.DS_Store
+Thumbs.db

asa_api_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peth Pty Ltd
+
+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.

asa_api_client-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: asa-api-client
+Version: 0.1.0
+Summary: A modern Python client for the Apple Search Ads API with full type safety and async support
+Project-URL: Homepage, https://github.com/SamPetherbridge/asa-api-client
+Project-URL: Documentation, https://asa-api-client.peth.au
+Project-URL: Repository, https://github.com/SamPetherbridge/asa-api-client
+Project-URL: Issues, https://github.com/SamPetherbridge/asa-api-client/issues
+Author-email: Peth Pty Ltd <hello@peth.com.au>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: advertising,api,apple,asa,async,pydantic,search-ads
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pydantic :: 2
+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.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyjwt[crypto]>=2.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.2.0; extra == 'dev'
+Requires-Dist: pandas>=2.2.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# ASA API Client
+
+[![PyPI version](https://img.shields.io/pypi/v/asa-api-client.svg)](https://pypi.org/project/asa-api-client/)
+[![Python](https://img.shields.io/pypi/pyversions/asa-api-client.svg)](https://pypi.org/project/asa-api-client/)
+[![License](https://img.shields.io/github/license/SamPetherbridge/asa-api-client.svg)](https://github.com/SamPetherbridge/asa-api-client/blob/main/LICENSE)
+[![CI](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml)
+
+A modern, fully-typed Python client for the Apple Search Ads API with async support and Pydantic models.
+
+## Features
+
+- **Full Type Safety** - Complete type hints with strict mypy compliance
+- **Async Support** - Both sync and async methods in a unified client
+- **Pydantic Models** - Validated request/response models
+- **Resource-based API** - Intuitive `client.campaigns.list()` pattern
+- **Automatic Pagination** - `iter_all()` and `iter_all_async()` helpers
+- **Reports with Pandas** - Optional DataFrame export
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv add asa-api-client
+```
+
+Using pip:
+
+```bash
+pip install asa-api-client
+```
+
+With pandas support:
+
+```bash
+uv add "asa-api-client[pandas]"
+# or
+pip install "asa-api-client[pandas]"
+```
+
+## Quick Start
+
+```python
+from asa_api_client import AppleSearchAdsClient
+
+# From environment variables
+client = AppleSearchAdsClient.from_env()
+
+# Or explicit configuration
+client = AppleSearchAdsClient(
+    client_id="SEARCHADS.xxx",
+    team_id="SEARCHADS.xxx",
+    key_id="xxx",
+    org_id=123456,
+    private_key_path="private-key.pem",
+)
+
+# List campaigns
+with client:
+    campaigns = client.campaigns.list()
+    for campaign in campaigns:
+        print(f"{campaign.name}: {campaign.status}")
+```
+
+## 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"
+```
+
+Or use a `.env` file:
+
+```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
+```
+
+## Resources
+
+### Campaigns
+
+```python
+# List all campaigns
+campaigns = client.campaigns.list()
+
+# Get a specific campaign
+campaign = client.campaigns.get(campaign_id)
+
+# Find with filters
+from asa_api_client.models import Selector
+enabled = client.campaigns.find(
+    Selector().where("status", "==", "ENABLED")
+)
+
+# Create a campaign
+from asa_api_client.models import CampaignCreate, Money, CampaignSupplySource
+campaign = client.campaigns.create(
+    CampaignCreate(
+        name="My Campaign",
+        adam_id=123456789,
+        countries_or_regions=["US"],
+        daily_budget_amount=Money(amount="100", currency="USD"),
+        supply_sources=[CampaignSupplySource.APPSTORE_SEARCH_RESULTS],
+    )
+)
+```
+
+### Ad Groups
+
+```python
+# Access ad groups through campaign
+ad_groups = client.campaigns(campaign_id).ad_groups.list()
+
+# Create an ad group
+from asa_api_client.models import AdGroupCreate
+ad_group = client.campaigns(campaign_id).ad_groups.create(
+    AdGroupCreate(
+        name="My Ad Group",
+        default_bid_amount=Money(amount="1.00", currency="USD"),
+    )
+)
+```
+
+### Keywords
+
+```python
+# List keywords in an ad group
+keywords = client.campaigns(campaign_id).ad_groups(ad_group_id).keywords.list()
+
+# Create keywords (bulk only)
+from asa_api_client.models import KeywordCreate, KeywordMatchType
+result = client.campaigns(campaign_id).ad_groups(ad_group_id).keywords.create_bulk([
+    KeywordCreate(
+        text="my keyword",
+        match_type=KeywordMatchType.EXACT,
+        bid_amount=Money(amount="1.50", currency="USD"),
+    )
+])
+```
+
+### Reports
+
+```python
+from datetime import date
+
+# Campaign report
+report = client.reports.campaigns(
+    start_date=date(2024, 1, 1),
+    end_date=date(2024, 1, 31),
+)
+
+# Convert to DataFrame (requires pandas)
+df = report.to_dataframe()
+```
+
+## Async Usage
+
+```python
+import asyncio
+
+async def main():
+    client = AppleSearchAdsClient.from_env()
+
+    async with client:
+        campaigns = await client.campaigns.list_async()
+
+        # Async iteration
+        async for campaign in client.campaigns.iter_all_async():
+            print(campaign.name)
+
+asyncio.run(main())
+```
+
+## CLI
+
+For a command-line interface, install [search-ads-cli](https://github.com/SamPetherbridge/search-ads-cli):
+
+```bash
+uv add search-ads-cli
+# or
+pip install search-ads-cli
+```
+
+## License
+
+MIT License - Copyright (c) 2025 Peth Pty Ltd