byebouncer-sdk 0.2.0__tar.gz

byebouncer_sdk-0.2.0/.gitignore

@@ -0,0 +1,71 @@
+# Binaries
+/bin/
+/dist/
+/server
+server.exe
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Test binaries
+*.test
+*.out
+
+# Go
+vendor/
+coverage.out
+coverage.html
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+.env.example
+*.pem
+*.key
+
+# IDE
+.claude/
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Node / Next.js (web/)
+web/node_modules/
+sdks/node/node_modules/
+sdks/node/dist/
+sdks/node/dist-cjs/
+web/.next/
+web/out/
+web/.turbo/
+web/.vercel/
+
+# Logs
+*.log
+logs/
+
+# Data files that are downloaded at build/run time
+data/disposable_domains_downloaded.txt
+# IP Validator datasets (IPtoASN, GeoLite2, Tor) — bajados por scripts/update_ipdata.sh.
+# GeoLite2 además NO puede versionarse por licencia MaxMind.
+data/ipdata/
+sdks/python/.venv/
+sdks/python/**/__pycache__/
+sdks/python/**/*.egg-info/
+sdks/python/.pytest_cache/
+sdks/python/dist/
+
+# Docs internas locales; contratos públicos versionados
+# La documentación interna sigue siendo local, pero los contratos públicos de
+# la API deben viajar con el repositorio para que SDKs y consumidores puedan
+# validarlos de forma reproducible.
+docs/*
+!docs/api/
+docs/api/*
+!docs/api/openapi.yaml
+!docs/api/postman/
+docs/api/postman/*
+!docs/api/postman/byebouncer.postman_collection.json

byebouncer_sdk-0.2.0/LICENSE

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

byebouncer_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: byebouncer-sdk
+Version: 0.2.0
+Summary: Official Python SDK for the ByeBouncer email verification API.
+Project-URL: Homepage, https://byebouncer.com
+Project-URL: Documentation, https://byebouncer.com/docs
+Project-URL: Repository, https://github.com/fidelp27/byebouncer
+Project-URL: Issues, https://github.com/fidelp27/byebouncer/issues
+Author-email: byebouncer-sdk <hello@byebouncer.com>
+License: MIT License
+        
+        Copyright (c) 2026 ByeBouncer
+        
+        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.
+License-File: LICENSE
+Keywords: bounce,email,email-validation,smtp,verification
+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
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# byebouncer
+
+Official Python SDK for the [ByeBouncer](https://byebouncer.com) email verification API.
+
+Sync and async clients, real-time single-email verification, bulk CSV verification (up to 50k emails per job), HMAC-signed webhooks.
+
+## Install
+
+```bash
+pip install byebouncer
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from byebouncer import ByeBouncer
+
+with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+    result = client.verify("user@gmail.com")
+    print(result.status)             # "deliverable" | "undeliverable" | "risky" | "unknown"
+    print(result.action)             # "allow" | "review" | "block"
+    print(result.signals)            # ["valid_syntax", "mx_found", ...]
+    print(result.credits_remaining)
+```
+
+Get your `BB_API_KEY` from https://byebouncer.com/dashboard (format `bb_live_...`).
+
+## Async
+
+```python
+import asyncio
+from byebouncer import AsyncByeBouncer
+
+async def main():
+    async with AsyncByeBouncer(api_key="bb_live_...") as client:
+        result = await client.verify("user@gmail.com")
+        print(result.status)
+
+asyncio.run(main())
+```
+
+## Bulk verification
+
+```python
+created = client.bulk(
+    emails=["a@gmail.com", "b@outlook.com"],  # up to 5.000
+    filename="my_list.csv",
+    webhook_url="https://api.myapp.com/hooks/byebouncer",  # optional
+)
+job = created.job
+print(f"Job {job.id}, {job.total_emails} emails")
+print(f"Estimated duration: {created.estimated_seconds}s")
+
+# Present when webhook_url is supplied (generated or supplied).
+# Store it now: it is never returned by later job reads.
+webhook_secret = created.webhook_secret
+```
+
+### Polling for completion
+
+```python
+final = client.bulk_wait_for_completion(
+    job.id,
+    interval_seconds=3,
+    on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
+)
+
+if final.status == "completed":
+    download = client.bulk_download_url(final.id)
+    csv = httpx.get(download.url).text
+    open("results.csv", "w").write(csv)
+```
+
+### Webhooks (recommended for large jobs)
+
+Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:
+
+```
+X-ByeBouncer-Event: bulk.completed
+X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
+```
+
+Attach or rotate the webhook after creating the job:
+
+```python
+result = client.bulk_set_webhook(
+    job.id,
+    webhook_url="https://api.myapp.com/hooks/byebouncer",
+)
+webhook_secret = result.webhook_secret  # store it NOW, returned only once
+```
+
+### Cancel
+
+```python
+cancelled = client.bulk_cancel(job.id)
+print(f"Refunded {cancelled.credits_refunded} credits")
+```
+
+## Error handling
+
+Non-2xx responses raise `ByeBouncerError` or a subclass with `code`, `status`, `detail`.
+
+```python
+from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer
+
+with ByeBouncer(api_key="bb_live_...") as client:
+    try:
+        client.verify("user@gmail.com")
+    except InsufficientCreditsError as e:
+        print(f"Out of credits (remaining: {e.credits_remaining})")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after_seconds}s")
+```
+
+## API reference
+
+Every method mirrors the [OpenAPI spec](https://github.com/fidelp27/byebouncer/blob/master/docs/api/openapi.yaml).
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `verify(email)` | `POST /verify` | Verify a single email |
+| `credits()` | `GET /credits` | Get balance |
+| `bulk(emails, ...)` | `POST /bulk` | Enqueue a bulk job |
+| `bulk_status(job_id)` | `GET /bulk/{id}` | Fetch job |
+| `bulk_cancel(job_id)` | `DELETE /bulk/{id}` | Cancel |
+| `bulk_download_url(job_id)` | `GET /bulk/{id}/download` | Signed CSV URL |
+| `bulk_set_webhook(job_id, ...)` | `POST /bulk/{id}/webhook` | Attach/rotate webhook |
+| `bulk_wait_for_completion(job_id, ...)` | polls | Convenience helper |
+| `bulk_and_wait(emails, ...)` | create+poll+download | Available in sync and async clients |
+
+## Support
+
+- Docs: https://byebouncer.com/docs
+- Email: hello@byebouncer.com
+- Issues: https://github.com/fidelp27/byebouncer/issues
+
+## License
+
+MIT © ByeBouncer

byebouncer_sdk-0.2.0/README.md

@@ -0,0 +1,143 @@
+# byebouncer
+
+Official Python SDK for the [ByeBouncer](https://byebouncer.com) email verification API.
+
+Sync and async clients, real-time single-email verification, bulk CSV verification (up to 50k emails per job), HMAC-signed webhooks.
+
+## Install
+
+```bash
+pip install byebouncer
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from byebouncer import ByeBouncer
+
+with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+    result = client.verify("user@gmail.com")
+    print(result.status)             # "deliverable" | "undeliverable" | "risky" | "unknown"
+    print(result.action)             # "allow" | "review" | "block"
+    print(result.signals)            # ["valid_syntax", "mx_found", ...]
+    print(result.credits_remaining)
+```
+
+Get your `BB_API_KEY` from https://byebouncer.com/dashboard (format `bb_live_...`).
+
+## Async
+
+```python
+import asyncio
+from byebouncer import AsyncByeBouncer
+
+async def main():
+    async with AsyncByeBouncer(api_key="bb_live_...") as client:
+        result = await client.verify("user@gmail.com")
+        print(result.status)
+
+asyncio.run(main())
+```
+
+## Bulk verification
+
+```python
+created = client.bulk(
+    emails=["a@gmail.com", "b@outlook.com"],  # up to 5.000
+    filename="my_list.csv",
+    webhook_url="https://api.myapp.com/hooks/byebouncer",  # optional
+)
+job = created.job
+print(f"Job {job.id}, {job.total_emails} emails")
+print(f"Estimated duration: {created.estimated_seconds}s")
+
+# Present when webhook_url is supplied (generated or supplied).
+# Store it now: it is never returned by later job reads.
+webhook_secret = created.webhook_secret
+```
+
+### Polling for completion
+
+```python
+final = client.bulk_wait_for_completion(
+    job.id,
+    interval_seconds=3,
+    on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
+)
+
+if final.status == "completed":
+    download = client.bulk_download_url(final.id)
+    csv = httpx.get(download.url).text
+    open("results.csv", "w").write(csv)
+```
+
+### Webhooks (recommended for large jobs)
+
+Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:
+
+```
+X-ByeBouncer-Event: bulk.completed
+X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
+```
+
+Attach or rotate the webhook after creating the job:
+
+```python
+result = client.bulk_set_webhook(
+    job.id,
+    webhook_url="https://api.myapp.com/hooks/byebouncer",
+)
+webhook_secret = result.webhook_secret  # store it NOW, returned only once
+```
+
+### Cancel
+
+```python
+cancelled = client.bulk_cancel(job.id)
+print(f"Refunded {cancelled.credits_refunded} credits")
+```
+
+## Error handling
+
+Non-2xx responses raise `ByeBouncerError` or a subclass with `code`, `status`, `detail`.
+
+```python
+from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer
+
+with ByeBouncer(api_key="bb_live_...") as client:
+    try:
+        client.verify("user@gmail.com")
+    except InsufficientCreditsError as e:
+        print(f"Out of credits (remaining: {e.credits_remaining})")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after_seconds}s")
+```
+
+## API reference
+
+Every method mirrors the [OpenAPI spec](https://github.com/fidelp27/byebouncer/blob/master/docs/api/openapi.yaml).
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `verify(email)` | `POST /verify` | Verify a single email |
+| `credits()` | `GET /credits` | Get balance |
+| `bulk(emails, ...)` | `POST /bulk` | Enqueue a bulk job |
+| `bulk_status(job_id)` | `GET /bulk/{id}` | Fetch job |
+| `bulk_cancel(job_id)` | `DELETE /bulk/{id}` | Cancel |
+| `bulk_download_url(job_id)` | `GET /bulk/{id}/download` | Signed CSV URL |
+| `bulk_set_webhook(job_id, ...)` | `POST /bulk/{id}/webhook` | Attach/rotate webhook |
+| `bulk_wait_for_completion(job_id, ...)` | polls | Convenience helper |
+| `bulk_and_wait(emails, ...)` | create+poll+download | Available in sync and async clients |
+
+## Support
+
+- Docs: https://byebouncer.com/docs
+- Email: hello@byebouncer.com
+- Issues: https://github.com/fidelp27/byebouncer/issues
+
+## License
+
+MIT © ByeBouncer

byebouncer_sdk-0.2.0/byebouncer/__init__.py

@@ -0,0 +1,44 @@
+"""Official Python SDK for the ByeBouncer email verification API."""
+
+from .client import AsyncByeBouncer, ByeBouncer
+from .errors import (
+    ByeBouncerError,
+    InsufficientCreditsError,
+    RateLimitError,
+    UnauthorizedError,
+)
+from .models import (
+    BulkJob,
+    BulkJobStatus,
+    CreateBulkResponse,
+    CreditsInfo,
+    DomainInfo,
+    DownloadResponse,
+    IPSignal,
+    IPVerifyResult,
+    PhoneVerifyResult,
+    SetWebhookResponse,
+    VerifyResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncByeBouncer",
+    "BulkJob",
+    "BulkJobStatus",
+    "ByeBouncer",
+    "ByeBouncerError",
+    "CreateBulkResponse",
+    "CreditsInfo",
+    "DomainInfo",
+    "DownloadResponse",
+    "IPSignal",
+    "IPVerifyResult",
+    "PhoneVerifyResult",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "SetWebhookResponse",
+    "UnauthorizedError",
+    "VerifyResult",
+]