foxreach 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

foxreach-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/

foxreach-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoxReach
+
+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.

foxreach-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: foxreach
+Version: 0.1.0
+Summary: Official Python SDK for the FoxReach cold email outreach API
+Project-URL: Homepage, https://foxreach.io
+Project-URL: Documentation, https://docs.foxreach.io/sdks/python
+Project-URL: Repository, https://github.com/foxreach/foxreach-python-sdk
+Project-URL: Changelog, https://docs.foxreach.io/changelog
+Author-email: FoxReach <dev@foxreach.io>
+License: MIT
+License-File: LICENSE
+Keywords: api,cold-email,email,foxreach,outreach,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FoxReach Python SDK
+
+Official Python SDK for the [FoxReach](https://foxreach.io) cold email outreach API.
+
+## Installation
+
+```bash
+pip install foxreach
+```
+
+## Quick Start
+
+```python
+from foxreach import FoxReach, LeadCreate
+
+client = FoxReach(api_key="otr_your_api_key")
+
+# Create a lead
+lead = client.leads.create(LeadCreate(
+    email="jane@example.com",
+    first_name="Jane",
+    last_name="Smith",
+    company="Acme Corp",
+))
+
+# List leads with pagination
+page = client.leads.list(search="jane", page_size=25)
+for lead in page:
+    print(lead.email)
+
+# Auto-paginate through all results
+for lead in client.leads.list().auto_paging_iter():
+    print(lead.email)
+```
+
+## Async Support
+
+```python
+from foxreach import AsyncFoxReach, LeadCreate
+
+async with AsyncFoxReach(api_key="otr_your_api_key") as client:
+    lead = await client.leads.create(LeadCreate(email="jane@example.com"))
+
+    async for lead in (await client.leads.list()).auto_paging_iter():
+        print(lead.email)
+```
+
+## Resources
+
+### Leads
+
+```python
+client.leads.list(page=1, page_size=50, search="...", status="active", tags="...")
+client.leads.get("cld_...")
+client.leads.create(LeadCreate(email="..."))
+client.leads.update("cld_...", LeadUpdate(company="New Co"))
+client.leads.delete("cld_...")
+```
+
+### Campaigns
+
+```python
+client.campaigns.list(status="active")
+client.campaigns.get("cmp_...")
+client.campaigns.create(CampaignCreate(name="Q1 Outreach"))
+client.campaigns.update("cmp_...", CampaignUpdate(daily_limit=100))
+client.campaigns.delete("cmp_...")
+client.campaigns.start("cmp_...")
+client.campaigns.pause("cmp_...")
+client.campaigns.add_leads("cmp_...", ["cld_1", "cld_2"])
+client.campaigns.add_accounts("cmp_...", ["acc_1"])
+```
+
+### Sequences
+
+```python
+client.campaigns.sequences.list("cmp_...")
+client.campaigns.sequences.create("cmp_...", SequenceCreate(body="Hi {{firstName}}"))
+client.campaigns.sequences.update("cmp_...", "seq_...", SequenceUpdate(delay_days=3))
+client.campaigns.sequences.delete("cmp_...", "seq_...")
+```
+
+### Templates
+
+```python
+client.templates.list()
+client.templates.get("tpl_...")
+client.templates.create(TemplateCreate(name="Follow-up", body="Hi {{firstName}}"))
+client.templates.update("tpl_...", TemplateUpdate(name="New name"))
+client.templates.delete("tpl_...")
+```
+
+### Email Accounts
+
+```python
+client.email_accounts.list()
+client.email_accounts.get("acc_...")
+client.email_accounts.delete("acc_...")
+```
+
+### Inbox
+
+```python
+client.inbox.list_threads(category="interested", is_read=False)
+client.inbox.get("rpl_...")
+client.inbox.update("rpl_...", ThreadUpdate(is_read=True))
+```
+
+### Analytics
+
+```python
+overview = client.analytics.overview()
+print(f"Reply rate: {overview.reply_rate}%")
+
+stats = client.analytics.campaign("cmp_...")
+print(f"Sent: {stats.sent}, Replied: {stats.replied}")
+```
+
+## Error Handling
+
+```python
+from foxreach import FoxReach, NotFoundError, RateLimitError, AuthenticationError
+
+client = FoxReach(api_key="otr_...")
+
+try:
+    lead = client.leads.get("cld_nonexistent")
+except NotFoundError:
+    print("Lead not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Configuration
+
+```python
+client = FoxReach(
+    api_key="otr_...",
+    base_url="https://api.foxreach.io/api/v1",  # default
+    timeout=30.0,       # seconds
+    max_retries=3,       # retries on 429
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx

foxreach-0.1.0/README.md

@@ -0,0 +1,150 @@
+# FoxReach Python SDK
+
+Official Python SDK for the [FoxReach](https://foxreach.io) cold email outreach API.
+
+## Installation
+
+```bash
+pip install foxreach
+```
+
+## Quick Start
+
+```python
+from foxreach import FoxReach, LeadCreate
+
+client = FoxReach(api_key="otr_your_api_key")
+
+# Create a lead
+lead = client.leads.create(LeadCreate(
+    email="jane@example.com",
+    first_name="Jane",
+    last_name="Smith",
+    company="Acme Corp",
+))
+
+# List leads with pagination
+page = client.leads.list(search="jane", page_size=25)
+for lead in page:
+    print(lead.email)
+
+# Auto-paginate through all results
+for lead in client.leads.list().auto_paging_iter():
+    print(lead.email)
+```
+
+## Async Support
+
+```python
+from foxreach import AsyncFoxReach, LeadCreate
+
+async with AsyncFoxReach(api_key="otr_your_api_key") as client:
+    lead = await client.leads.create(LeadCreate(email="jane@example.com"))
+
+    async for lead in (await client.leads.list()).auto_paging_iter():
+        print(lead.email)
+```
+
+## Resources
+
+### Leads
+
+```python
+client.leads.list(page=1, page_size=50, search="...", status="active", tags="...")
+client.leads.get("cld_...")
+client.leads.create(LeadCreate(email="..."))
+client.leads.update("cld_...", LeadUpdate(company="New Co"))
+client.leads.delete("cld_...")
+```
+
+### Campaigns
+
+```python
+client.campaigns.list(status="active")
+client.campaigns.get("cmp_...")
+client.campaigns.create(CampaignCreate(name="Q1 Outreach"))
+client.campaigns.update("cmp_...", CampaignUpdate(daily_limit=100))
+client.campaigns.delete("cmp_...")
+client.campaigns.start("cmp_...")
+client.campaigns.pause("cmp_...")
+client.campaigns.add_leads("cmp_...", ["cld_1", "cld_2"])
+client.campaigns.add_accounts("cmp_...", ["acc_1"])
+```
+
+### Sequences
+
+```python
+client.campaigns.sequences.list("cmp_...")
+client.campaigns.sequences.create("cmp_...", SequenceCreate(body="Hi {{firstName}}"))
+client.campaigns.sequences.update("cmp_...", "seq_...", SequenceUpdate(delay_days=3))
+client.campaigns.sequences.delete("cmp_...", "seq_...")
+```
+
+### Templates
+
+```python
+client.templates.list()
+client.templates.get("tpl_...")
+client.templates.create(TemplateCreate(name="Follow-up", body="Hi {{firstName}}"))
+client.templates.update("tpl_...", TemplateUpdate(name="New name"))
+client.templates.delete("tpl_...")
+```
+
+### Email Accounts
+
+```python
+client.email_accounts.list()
+client.email_accounts.get("acc_...")
+client.email_accounts.delete("acc_...")
+```
+
+### Inbox
+
+```python
+client.inbox.list_threads(category="interested", is_read=False)
+client.inbox.get("rpl_...")
+client.inbox.update("rpl_...", ThreadUpdate(is_read=True))
+```
+
+### Analytics
+
+```python
+overview = client.analytics.overview()
+print(f"Reply rate: {overview.reply_rate}%")
+
+stats = client.analytics.campaign("cmp_...")
+print(f"Sent: {stats.sent}, Replied: {stats.replied}")
+```
+
+## Error Handling
+
+```python
+from foxreach import FoxReach, NotFoundError, RateLimitError, AuthenticationError
+
+client = FoxReach(api_key="otr_...")
+
+try:
+    lead = client.leads.get("cld_nonexistent")
+except NotFoundError:
+    print("Lead not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Configuration
+
+```python
+client = FoxReach(
+    api_key="otr_...",
+    base_url="https://api.foxreach.io/api/v1",  # default
+    timeout=30.0,       # seconds
+    max_retries=3,       # retries on 429
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx

foxreach-0.1.0/foxreach/__init__.py

@@ -0,0 +1,79 @@
+"""FoxReach — Official Python SDK for the FoxReach cold email outreach API."""
+
+from .client import AsyncFoxReach, FoxReach
+from ._exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    FoxReachError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    Campaign,
+    CampaignAnalytics,
+    CampaignCreate,
+    CampaignUpdate,
+    DailyStat,
+    EmailAccount,
+    Lead,
+    LeadCreate,
+    LeadListParams,
+    LeadUpdate,
+    OverviewStats,
+    PaginationMeta,
+    Sequence,
+    SequenceCreate,
+    SequenceUpdate,
+    Template,
+    TemplateCreate,
+    TemplateUpdate,
+    Thread,
+    ThreadListParams,
+    ThreadUpdate,
+    WebhookEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "FoxReach",
+    "AsyncFoxReach",
+    # Exceptions
+    "FoxReachError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConnectionError",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Types
+    "Campaign",
+    "CampaignAnalytics",
+    "CampaignCreate",
+    "CampaignUpdate",
+    "DailyStat",
+    "EmailAccount",
+    "Lead",
+    "LeadCreate",
+    "LeadListParams",
+    "LeadUpdate",
+    "OverviewStats",
+    "PaginationMeta",
+    "Sequence",
+    "SequenceCreate",
+    "SequenceUpdate",
+    "Template",
+    "TemplateCreate",
+    "TemplateUpdate",
+    "Thread",
+    "ThreadListParams",
+    "ThreadUpdate",
+    "WebhookEvent",
+]

foxreach-0.1.0/foxreach/_exceptions.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class FoxReachError(Exception):
+    """Base exception for all FoxReach SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class AuthenticationError(FoxReachError):
+    """Raised on 401 Unauthorized responses."""
+
+
+class PermissionError(FoxReachError):
+    """Raised on 403 Forbidden responses."""
+
+
+class NotFoundError(FoxReachError):
+    """Raised on 404 Not Found responses."""
+
+
+class BadRequestError(FoxReachError):
+    """Raised on 400 Bad Request responses."""
+
+
+class ValidationError(FoxReachError):
+    """Raised on 422 Unprocessable Entity responses."""
+
+
+class RateLimitError(FoxReachError):
+    """Raised on 429 Too Many Requests after retries are exhausted."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(FoxReachError):
+    """Raised on 5xx server errors."""
+
+
+class ConnectionError(FoxReachError):
+    """Raised on network / connection errors."""