earlyforge 0.1.0__tar.gz

earlyforge-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: earlyforge
+Version: 0.1.0
+Summary: Python client for the EarlyForge Pulse API (free trend data, authenticated)
+Author: EarlyForge
+License: MIT
+Project-URL: Homepage, https://earlyforge.ai
+Project-URL: Documentation, https://docs.earlyforge.ai/guides/api/trends-api
+Project-URL: Source, https://github.com/Earlyforge-official/earlyforge
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# earlyforge (Python)
+
+Python client for the **EarlyForge Trends API**, with two tiers under the
+same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** — free on every account, no plan required. An
+  authenticated mirror of the free, anonymous trend data already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai): same daily snapshot,
+  same trend count, same fields, no extra filters.
+- **Full trends feed** — paid plans only, and **not "all trends
+  unlocked."** Every plan reveals a bigger, but still limited, daily,
+  random, category-diversified budget of trend names — exactly what your
+  organization's dashboard Trends page shows unlocked today, no more, no
+  less. See `full_trends()` below.
+
+This is **not** a client for articles, briefs, or alerts — the public API
+never exposes those on any plan.
+
+Full reference: [docs.earlyforge.ai/guides/api/python-sdk](https://docs.earlyforge.ai/guides/api/python-sdk). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/sdk-python-earlyforge).
+
+## Install
+
+Not published to PyPI yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Quickstart
+
+```python
+from earlyforge import PulseClient
+
+client = PulseClient(api_key="ef_live_xxxxxxxxxxxxxxxx")
+
+snapshot = client.top_trends(locale="fr")
+print(snapshot["trends"][0]["display_name"])
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console — any
+account works, Pulse access is free.
+
+## Methods
+
+### `top_trends(date=None, locale=None)`
+
+Global top trends — same snapshot as the Pulse homepage.
+
+```python
+client.top_trends()
+# {
+#   "trends": [
+#     {
+#       "trend_id": "tr_a1b2c3",
+#       "display_name": "AI regulation",
+#       "region": "US",
+#       "language": "en",
+#       "categories": ["politics"],
+#       "global_score": 87.5,
+#       "lifecycle_stage": "growing",
+#       "detected_at": "2026-11-04T08:00:00Z",
+#       "hours_since_detection": 6.2,
+#       "velocity_zscore": 2.1,
+#       "acceleration": 0.4,
+#       "n_sources": 12,
+#       "source_diversity": 0.8,
+#       "cross_lingual_root": false,
+#       "google_trends_lead_hours": null,
+#       "topic_class": null,
+#       "entities": [],
+#       "description": None
+#     }
+#   ],
+#   "total": 20,
+#   "cached_at": "2026-11-04T06:00:00Z",
+#   "cache_ttl_seconds": 3600
+# }
+```
+
+### `trends_by_region(region, date=None, locale=None)`
+
+Top trends for an ISO 3166-1 alpha-2 region code (e.g. `"US"`, `"FR"`).
+Same `TrendList` shape as `top_trends`.
+
+### `trends_by_category(category, date=None, locale=None)`
+
+Top trends for a category (e.g. `"politics"`, `"tech"`). Same `TrendList`
+shape as `top_trends`.
+
+### `get_trend(trend_id)`
+
+Detail for one trend. Same fields as a `Trend`, plus `canonical_name`,
+`sources`, a full `description`, and a `timeline` of `{ts, score,
+sources_count}` points.
+
+```python
+client.get_trend("tr_a1b2c3")
+```
+
+### `full_trends(region=None, category=None, page=1, limit=20)`
+
+**Paid plans only.** A bigger, paginated slice of the trend corpus than
+the fixed Pulse snapshot — gated by the same daily random name-visibility
+budget as the dashboard. Items outside today's budget stay in the list
+with their name fields redacted (`name_locked: true`), not removed.
+
+```python
+client.full_trends(limit=50)
+# {
+#   "items": [
+#     {"trend_id": "tr_a1b2c3", "display_name": "Ransomware wave", ...},
+#     {"trend_id": "tr_d4e5f6", "display_name": "••••••••••", "name_locked": True, ...}
+#   ],
+#   "total": 2,
+#   "page": 1,
+#   "per_page": 50
+# }
+```
+
+A free-plan key raises `PulseApiError` with `status_code=402` and
+`detail={"error": "upgrade_required", ...}` before this even runs.
+
+### `get_full_trend(trend_id)`
+
+**Paid plans only.** Full detail for one trend — same TD-sourced fields
+as the dashboard's detail panel (`topsis_score`, `editorial_title`, etc.).
+Raises `PulseApiError` with `status_code=402` and
+`detail={"code": "trend_locked", ...}` if the trend is outside today's
+visible-name budget.
+
+```python
+client.get_full_trend("tr_a1b2c3")
+```
+
+## Errors
+
+Every non-2xx response raises `earlyforge.PulseApiError` with
+`status_code` and `detail` attributes (mirroring the OpenAPI spec's `401`
+missing/invalid/revoked key, `404` unknown trend, and `502` upstream
+unavailable responses). Network failures (DNS, timeout, connection
+refused) also raise `PulseApiError`.
+
+```python
+from earlyforge import PulseApiError
+
+try:
+    client.get_trend("does-not-exist")
+except PulseApiError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## Rate limits
+
+No monthly call quota on this surface, for any plan — only the shared
+60 requests/60s burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge-0.1.0/README.md

@@ -0,0 +1,158 @@
+# earlyforge (Python)
+
+Python client for the **EarlyForge Trends API**, with two tiers under the
+same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** — free on every account, no plan required. An
+  authenticated mirror of the free, anonymous trend data already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai): same daily snapshot,
+  same trend count, same fields, no extra filters.
+- **Full trends feed** — paid plans only, and **not "all trends
+  unlocked."** Every plan reveals a bigger, but still limited, daily,
+  random, category-diversified budget of trend names — exactly what your
+  organization's dashboard Trends page shows unlocked today, no more, no
+  less. See `full_trends()` below.
+
+This is **not** a client for articles, briefs, or alerts — the public API
+never exposes those on any plan.
+
+Full reference: [docs.earlyforge.ai/guides/api/python-sdk](https://docs.earlyforge.ai/guides/api/python-sdk). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/sdk-python-earlyforge).
+
+## Install
+
+Not published to PyPI yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Quickstart
+
+```python
+from earlyforge import PulseClient
+
+client = PulseClient(api_key="ef_live_xxxxxxxxxxxxxxxx")
+
+snapshot = client.top_trends(locale="fr")
+print(snapshot["trends"][0]["display_name"])
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console — any
+account works, Pulse access is free.
+
+## Methods
+
+### `top_trends(date=None, locale=None)`
+
+Global top trends — same snapshot as the Pulse homepage.
+
+```python
+client.top_trends()
+# {
+#   "trends": [
+#     {
+#       "trend_id": "tr_a1b2c3",
+#       "display_name": "AI regulation",
+#       "region": "US",
+#       "language": "en",
+#       "categories": ["politics"],
+#       "global_score": 87.5,
+#       "lifecycle_stage": "growing",
+#       "detected_at": "2026-11-04T08:00:00Z",
+#       "hours_since_detection": 6.2,
+#       "velocity_zscore": 2.1,
+#       "acceleration": 0.4,
+#       "n_sources": 12,
+#       "source_diversity": 0.8,
+#       "cross_lingual_root": false,
+#       "google_trends_lead_hours": null,
+#       "topic_class": null,
+#       "entities": [],
+#       "description": None
+#     }
+#   ],
+#   "total": 20,
+#   "cached_at": "2026-11-04T06:00:00Z",
+#   "cache_ttl_seconds": 3600
+# }
+```
+
+### `trends_by_region(region, date=None, locale=None)`
+
+Top trends for an ISO 3166-1 alpha-2 region code (e.g. `"US"`, `"FR"`).
+Same `TrendList` shape as `top_trends`.
+
+### `trends_by_category(category, date=None, locale=None)`
+
+Top trends for a category (e.g. `"politics"`, `"tech"`). Same `TrendList`
+shape as `top_trends`.
+
+### `get_trend(trend_id)`
+
+Detail for one trend. Same fields as a `Trend`, plus `canonical_name`,
+`sources`, a full `description`, and a `timeline` of `{ts, score,
+sources_count}` points.
+
+```python
+client.get_trend("tr_a1b2c3")
+```
+
+### `full_trends(region=None, category=None, page=1, limit=20)`
+
+**Paid plans only.** A bigger, paginated slice of the trend corpus than
+the fixed Pulse snapshot — gated by the same daily random name-visibility
+budget as the dashboard. Items outside today's budget stay in the list
+with their name fields redacted (`name_locked: true`), not removed.
+
+```python
+client.full_trends(limit=50)
+# {
+#   "items": [
+#     {"trend_id": "tr_a1b2c3", "display_name": "Ransomware wave", ...},
+#     {"trend_id": "tr_d4e5f6", "display_name": "••••••••••", "name_locked": True, ...}
+#   ],
+#   "total": 2,
+#   "page": 1,
+#   "per_page": 50
+# }
+```
+
+A free-plan key raises `PulseApiError` with `status_code=402` and
+`detail={"error": "upgrade_required", ...}` before this even runs.
+
+### `get_full_trend(trend_id)`
+
+**Paid plans only.** Full detail for one trend — same TD-sourced fields
+as the dashboard's detail panel (`topsis_score`, `editorial_title`, etc.).
+Raises `PulseApiError` with `status_code=402` and
+`detail={"code": "trend_locked", ...}` if the trend is outside today's
+visible-name budget.
+
+```python
+client.get_full_trend("tr_a1b2c3")
+```
+
+## Errors
+
+Every non-2xx response raises `earlyforge.PulseApiError` with
+`status_code` and `detail` attributes (mirroring the OpenAPI spec's `401`
+missing/invalid/revoked key, `404` unknown trend, and `502` upstream
+unavailable responses). Network failures (DNS, timeout, connection
+refused) also raise `PulseApiError`.
+
+```python
+from earlyforge import PulseApiError
+
+try:
+    client.get_trend("does-not-exist")
+except PulseApiError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## Rate limits
+
+No monthly call quota on this surface, for any plan — only the shared
+60 requests/60s burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge-0.1.0/earlyforge/__init__.py

@@ -0,0 +1,6 @@
+"""Python client for the EarlyForge Pulse API."""
+
+from .client import PulseApiError, PulseClient
+
+__all__ = ["PulseClient", "PulseApiError"]
+__version__ = "0.1.0"

earlyforge-0.1.0/earlyforge/client.py

@@ -0,0 +1,181 @@
+"""Client for the EarlyForge Trends API.
+
+Covers 2 tiers under the same /v1/api/trends/* prefix:
+
+  - Pulse mirror (free, any plan):
+      GET /v1/api/trends/top
+      GET /v1/api/trends/region/{region}
+      GET /v1/api/trends/category/{category}
+      GET /v1/api/trends/{trend_id}
+  - Full trends feed (paid plans only — NOT "all trends unlocked", see
+    full_trends()):
+      GET /v1/api/trends/full
+      GET /v1/api/trends/full/{trend_id}
+
+Contract: docs/api/public-api-v1/openapi.yaml (repo root). This client
+never sends a parameter the OpenAPI spec doesn't document.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.earlyforge.ai"
+DEFAULT_TIMEOUT_SECONDS = 15.0
+
+
+class PulseApiError(Exception):
+    """Raised when the Pulse API returns a non-2xx response.
+
+    Attributes:
+        status_code: The HTTP status code, when available.
+        detail: The error detail returned by the API, when available.
+    """
+
+    def __init__(self, message: str, *, status_code: Optional[int] = None, detail: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class PulseClient:
+    """A thin, synchronous HTTP client for the EarlyForge Pulse API.
+
+    Example:
+        >>> client = PulseClient(api_key="ef_live_xxxxxxxxxxxxxxxx")
+        >>> snapshot = client.top_trends(locale="fr")
+        >>> snapshot["trends"][0]["display_name"]
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        url = f"{self.base_url}{path}"
+        try:
+            response = httpx.get(
+                url,
+                params=clean_params,
+                headers=self._headers(),
+                timeout=self.timeout,
+            )
+        except httpx.RequestError as exc:
+            raise PulseApiError(f"Could not reach EarlyForge API at {url}: {exc}") from exc
+
+        if response.status_code >= 400:
+            detail = None
+            try:
+                detail = response.json().get("detail")
+            except Exception:
+                detail = response.text[:300] or None
+            raise PulseApiError(
+                f"EarlyForge API returned HTTP {response.status_code} for {url}",
+                status_code=response.status_code,
+                detail=detail,
+            )
+
+        return response.json()
+
+    def top_trends(self, *, date: Optional[str] = None, locale: Optional[str] = None) -> Any:
+        """Global top trends — same daily snapshot as the Pulse homepage.
+
+        Args:
+            date: Pick a past daily snapshot (YYYY-MM-DD). Omit for the latest.
+            locale: Locale for translated fields (e.g. "fr").
+
+        Returns:
+            {"trends": [...], "total": int, "cached_at": str, "cache_ttl_seconds": int}
+        """
+        return self._get("/v1/api/trends/top", {"date": date, "locale": locale})
+
+    def trends_by_region(
+        self, region: str, *, date: Optional[str] = None, locale: Optional[str] = None
+    ) -> Any:
+        """Top trends for a region — same snapshot as the Pulse region view.
+
+        Args:
+            region: ISO 3166-1 alpha-2 region code (e.g. "US", "FR").
+            date: Pick a past daily snapshot (YYYY-MM-DD). Omit for the latest.
+            locale: Locale for translated fields (e.g. "fr").
+        """
+        return self._get(f"/v1/api/trends/region/{quote(region, safe='')}", {"date": date, "locale": locale})
+
+    def trends_by_category(
+        self, category: str, *, date: Optional[str] = None, locale: Optional[str] = None
+    ) -> Any:
+        """Top trends for a category — same snapshot as the Pulse category view.
+
+        Args:
+            category: Category filter (e.g. "politics", "tech").
+            date: Pick a past daily snapshot (YYYY-MM-DD). Omit for the latest.
+            locale: Locale for translated fields (e.g. "fr").
+        """
+        return self._get(f"/v1/api/trends/category/{quote(category, safe='')}", {"date": date, "locale": locale})
+
+    def get_trend(self, trend_id: str) -> Any:
+        """Trend detail — same payload as the public trend detail page.
+
+        Args:
+            trend_id: The trend's id, e.g. "tr_a1b2c3" (from top_trends()).
+        """
+        return self._get(f"/v1/api/trends/{quote(trend_id, safe='')}")
+
+    def full_trends(
+        self,
+        *,
+        region: Optional[str] = None,
+        category: Optional[str] = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> Any:
+        """Full trends feed — paid plans only, and NOT "all trends unlocked".
+
+        Every plan still reveals only a daily, random, category-diversified
+        budget of trend names (same budget the dashboard's Trends page shows
+        for this org today). Items outside that budget stay in the list but
+        with their name fields redacted (``name_locked: true``). A free-plan
+        key gets ``PulseApiError`` with ``status_code=402`` before this even
+        runs.
+
+        Args:
+            region: Filter by region.
+            category: Filter by category.
+            page: Page number, default 1.
+            limit: Items per page, default 20, max 100.
+
+        Returns:
+            {"items": [...], "total": int, "page": int, "per_page": int}
+        """
+        return self._get(
+            "/v1/api/trends/full",
+            {"region": region, "category": category, "page": page, "limit": limit},
+        )
+
+    def get_full_trend(self, trend_id: str) -> Any:
+        """Full detail for one trend — paid plans only.
+
+        Returns ``PulseApiError`` with ``status_code=402`` if the trend is
+        outside today's visible-name budget — same restriction the
+        dashboard's own detail panel enforces.
+
+        Args:
+            trend_id: The trend's id, e.g. "tr_a1b2c3" (from full_trends()).
+        """
+        return self._get(f"/v1/api/trends/full/{quote(trend_id, safe='')}")

earlyforge-0.1.0/earlyforge.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: earlyforge
+Version: 0.1.0
+Summary: Python client for the EarlyForge Pulse API (free trend data, authenticated)
+Author: EarlyForge
+License: MIT
+Project-URL: Homepage, https://earlyforge.ai
+Project-URL: Documentation, https://docs.earlyforge.ai/guides/api/trends-api
+Project-URL: Source, https://github.com/Earlyforge-official/earlyforge
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# earlyforge (Python)
+
+Python client for the **EarlyForge Trends API**, with two tiers under the
+same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** — free on every account, no plan required. An
+  authenticated mirror of the free, anonymous trend data already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai): same daily snapshot,
+  same trend count, same fields, no extra filters.
+- **Full trends feed** — paid plans only, and **not "all trends
+  unlocked."** Every plan reveals a bigger, but still limited, daily,
+  random, category-diversified budget of trend names — exactly what your
+  organization's dashboard Trends page shows unlocked today, no more, no
+  less. See `full_trends()` below.
+
+This is **not** a client for articles, briefs, or alerts — the public API
+never exposes those on any plan.
+
+Full reference: [docs.earlyforge.ai/guides/api/python-sdk](https://docs.earlyforge.ai/guides/api/python-sdk). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/sdk-python-earlyforge).
+
+## Install
+
+Not published to PyPI yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Quickstart
+
+```python
+from earlyforge import PulseClient
+
+client = PulseClient(api_key="ef_live_xxxxxxxxxxxxxxxx")
+
+snapshot = client.top_trends(locale="fr")
+print(snapshot["trends"][0]["display_name"])
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console — any
+account works, Pulse access is free.
+
+## Methods
+
+### `top_trends(date=None, locale=None)`
+
+Global top trends — same snapshot as the Pulse homepage.
+
+```python
+client.top_trends()
+# {
+#   "trends": [
+#     {
+#       "trend_id": "tr_a1b2c3",
+#       "display_name": "AI regulation",
+#       "region": "US",
+#       "language": "en",
+#       "categories": ["politics"],
+#       "global_score": 87.5,
+#       "lifecycle_stage": "growing",
+#       "detected_at": "2026-11-04T08:00:00Z",
+#       "hours_since_detection": 6.2,
+#       "velocity_zscore": 2.1,
+#       "acceleration": 0.4,
+#       "n_sources": 12,
+#       "source_diversity": 0.8,
+#       "cross_lingual_root": false,
+#       "google_trends_lead_hours": null,
+#       "topic_class": null,
+#       "entities": [],
+#       "description": None
+#     }
+#   ],
+#   "total": 20,
+#   "cached_at": "2026-11-04T06:00:00Z",
+#   "cache_ttl_seconds": 3600
+# }
+```
+
+### `trends_by_region(region, date=None, locale=None)`
+
+Top trends for an ISO 3166-1 alpha-2 region code (e.g. `"US"`, `"FR"`).
+Same `TrendList` shape as `top_trends`.
+
+### `trends_by_category(category, date=None, locale=None)`
+
+Top trends for a category (e.g. `"politics"`, `"tech"`). Same `TrendList`
+shape as `top_trends`.
+
+### `get_trend(trend_id)`
+
+Detail for one trend. Same fields as a `Trend`, plus `canonical_name`,
+`sources`, a full `description`, and a `timeline` of `{ts, score,
+sources_count}` points.
+
+```python
+client.get_trend("tr_a1b2c3")
+```
+
+### `full_trends(region=None, category=None, page=1, limit=20)`
+
+**Paid plans only.** A bigger, paginated slice of the trend corpus than
+the fixed Pulse snapshot — gated by the same daily random name-visibility
+budget as the dashboard. Items outside today's budget stay in the list
+with their name fields redacted (`name_locked: true`), not removed.
+
+```python
+client.full_trends(limit=50)
+# {
+#   "items": [
+#     {"trend_id": "tr_a1b2c3", "display_name": "Ransomware wave", ...},
+#     {"trend_id": "tr_d4e5f6", "display_name": "••••••••••", "name_locked": True, ...}
+#   ],
+#   "total": 2,
+#   "page": 1,
+#   "per_page": 50
+# }
+```
+
+A free-plan key raises `PulseApiError` with `status_code=402` and
+`detail={"error": "upgrade_required", ...}` before this even runs.
+
+### `get_full_trend(trend_id)`
+
+**Paid plans only.** Full detail for one trend — same TD-sourced fields
+as the dashboard's detail panel (`topsis_score`, `editorial_title`, etc.).
+Raises `PulseApiError` with `status_code=402` and
+`detail={"code": "trend_locked", ...}` if the trend is outside today's
+visible-name budget.
+
+```python
+client.get_full_trend("tr_a1b2c3")
+```
+
+## Errors
+
+Every non-2xx response raises `earlyforge.PulseApiError` with
+`status_code` and `detail` attributes (mirroring the OpenAPI spec's `401`
+missing/invalid/revoked key, `404` unknown trend, and `502` upstream
+unavailable responses). Network failures (DNS, timeout, connection
+refused) also raise `PulseApiError`.
+
+```python
+from earlyforge import PulseApiError
+
+try:
+    client.get_trend("does-not-exist")
+except PulseApiError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## Rate limits
+
+No monthly call quota on this surface, for any plan — only the shared
+60 requests/60s burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge-0.1.0/earlyforge.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+earlyforge/__init__.py
+earlyforge/client.py
+earlyforge.egg-info/PKG-INFO
+earlyforge.egg-info/SOURCES.txt
+earlyforge.egg-info/dependency_links.txt
+earlyforge.egg-info/requires.txt
+earlyforge.egg-info/top_level.txt
+tests/test_client.py

earlyforge-0.1.0/earlyforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

earlyforge-0.1.0/earlyforge.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27.0

earlyforge-0.1.0/earlyforge.egg-info/top_level.txt

@@ -0,0 +1 @@
+earlyforge

earlyforge-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "earlyforge"
+version = "0.1.0"
+description = "Python client for the EarlyForge Pulse API (free trend data, authenticated)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "EarlyForge" }]
+dependencies = ["httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://earlyforge.ai"
+Documentation = "https://docs.earlyforge.ai/guides/api/trends-api"
+Source = "https://github.com/Earlyforge-official/earlyforge"
+
+[tool.setuptools.packages.find]
+include = ["earlyforge*"]

earlyforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

earlyforge-0.1.0/tests/test_client.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from earlyforge import PulseApiError, PulseClient
+
+
+def _handler(request: httpx.Request) -> httpx.Response:
+    assert request.headers["authorization"] == "Bearer ef_live_test"
+    if request.url.path == "/v1/api/trends/top":
+        return httpx.Response(200, json={"trends": [], "total": 0})
+    if request.url.path == "/v1/api/trends/region/US":
+        return httpx.Response(200, json={"trends": [{"trend_id": "tr_1"}], "total": 1})
+    if request.url.path == "/v1/api/trends/tr_missing":
+        return httpx.Response(404, json={"detail": "Not found"})
+    if request.url.path == "/v1/api/trends/full":
+        if request.url.params.get("region") == "locked-org":
+            return httpx.Response(
+                402,
+                json={"detail": {"error": "upgrade_required", "upgrade_url": "/settings/billing"}},
+            )
+        return httpx.Response(
+            200,
+            json={"items": [{"trend_id": "tr_1"}], "total": 1, "page": 1, "per_page": 20},
+        )
+    if request.url.path == "/v1/api/trends/full/tr_locked":
+        return httpx.Response(
+            402, json={"detail": {"error": "This trend is locked on your plan", "code": "trend_locked"}}
+        )
+    return httpx.Response(500, json={"detail": "unexpected"})
+
+
+@pytest.fixture(autouse=True)
+def _patch_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+    transport = httpx.MockTransport(_handler)
+
+    def fake_get(url, *, params=None, headers=None, timeout=None):
+        with httpx.Client(transport=transport) as client:
+            return client.get(url, params=params, headers=headers, timeout=timeout)
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+
+
+def test_top_trends_sends_bearer_token_and_builds_url() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    result = client.top_trends(locale="fr")
+    assert result == {"trends": [], "total": 0}
+
+
+def test_trends_by_region_builds_path_param() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    result = client.trends_by_region("US")
+    assert result["total"] == 1
+
+
+def test_get_trend_raises_pulse_api_error_on_404() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    with pytest.raises(PulseApiError) as excinfo:
+        client.get_trend("tr_missing")
+    assert excinfo.value.status_code == 404
+
+
+def test_requires_api_key() -> None:
+    with pytest.raises(ValueError):
+        PulseClient(api_key="")
+
+
+def test_full_trends_returns_items_with_total() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    result = client.full_trends(limit=20)
+    assert result["total"] == 1
+    assert result["items"][0]["trend_id"] == "tr_1"
+
+
+def test_full_trends_raises_402_on_free_plan() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    with pytest.raises(PulseApiError) as excinfo:
+        client.full_trends(region="locked-org")
+    assert excinfo.value.status_code == 402
+    assert excinfo.value.detail["error"] == "upgrade_required"
+
+
+def test_get_full_trend_raises_402_trend_locked() -> None:
+    client = PulseClient(api_key="ef_live_test", base_url="https://api.test")
+    with pytest.raises(PulseApiError) as excinfo:
+        client.get_full_trend("tr_locked")
+    assert excinfo.value.status_code == 402
+    assert excinfo.value.detail["code"] == "trend_locked"