narwhalapi 0.1.0__tar.gz

narwhalapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — 2026-10-09
+
+- Initial typed synchronous and asynchronous clients for the stable API: economics,
+  FX, calendars, physical palm oil, spot prices (`commodities.spot_price`), events,
+  webhook destinations and calendar subscriptions.
+- `nw.unstable` holds operations not yet in the live API; it is empty in this release.
+- Exact decimals, typed errors, bounded retries, page iterators, response metadata,
+  and local webhook signature verification.
+- `codes.PLAN_UPGRADE_REQUIRED` for the 403 returned when a request reaches before the
+  plan's history window.
+- The release also covers prediction market reads, FX and commodity bar history, and physical commodity reference price series.
+- Spot `bid` and `ask` are optional because the API may omit them.

narwhalapi-0.1.0/LICENSE

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

narwhalapi-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: narwhalapi
+Version: 0.1.0
+Summary: Typed clients for the Narwhal API
+Project-URL: Homepage, https://narwhalapi.com
+Author-email: Narwhal API Team <support@narwhalapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,decimal,economics,exchange-rates,fx,holidays,inflation,palm-oil,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# Narwhal API for Python
+
+Typed synchronous and asynchronous clients for economics, foreign exchange, calendars,
+physical palm oil, physical commodity reference prices, spot gold and silver, prediction markets, FX and commodity bar history, and webhook delivery. Python 3.10 or newer. Install with `pip install narwhalapi`.
+
+Set `NARWHAL_API_KEY` in the environment. Keep keys on the server. The default base URL is
+`https://api.narwhalapi.com`; override it with `NARWHAL_BASE_URL` or `base_url=`.
+
+## Quickstart
+
+```pycon
+>>> from decimal import Decimal
+>>> from narwhalapi import Narwhal
+>>> with Narwhal() as nw:
+...     cpi = nw.economics.cpi("USA")
+...     rates = nw.fx.rates("USD", currencies=["EUR", "JPY"])
+...     days = list(nw.fx.rate_history_iter(
+...         "USD", currencies=["EUR"], start_date="2026-08-20", end_date="2026-08-24"
+...     ))
+>>> isinstance(cpi.value, Decimal)
+True
+>>> isinstance(rates.rates[0].rate, Decimal)
+True
+>>> all(isinstance(rate.rate, Decimal) for day in days for rate in day.rates)
+True
+
+```
+
+Decimals remain exact `Decimal` values. Use `format(value, "f")` to display fixed-point
+wire text, including very small values. Decimal inputs accept `Decimal` or `str`;
+other numeric types raise `TypeError`. Responses accept only decimal strings matching
+`^-?\d+(\.\d+)?$` with ASCII digits. Dates and timestamps remain strings.
+
+```python
+from narwhalapi import AsyncNarwhal, errors
+
+async def load_rates():
+    async with AsyncNarwhal() as nw:
+        try:
+            return await nw.fx.rates("USD", currencies=["IDR", "SGD"])
+        except errors.RateLimited as error:
+            if error.is_quota_exhausted:
+                return None
+            raise
+```
+
+Share a synchronous client across threads. Use one async client per event loop.
+Context managers close connections; explicit `close()` and `await aclose()` also work.
+
+## Operations and types
+
+Namespaces are `economics`, `fx`, `calendars`, `commodities`, `events`, `webhooks`, and
+`calendar_subscriptions`. Operations not yet in the live API appear under `nw.unstable`;
+there are none today.
+Models and known string constants are available through `narwhalapi.models`,
+for example `from narwhalapi.models import Cpi`.
+Unknown enum strings are retained. Union variants are frozen dataclasses with a `kind`;
+its `kind` is the variant model name (for example `PalmoilSchedulePrice`).
+An unknown variant has `kind="unknown"` and keeps its JSON in `raw`.
+New response fields are ignored.
+
+Required path arguments may be positional. Query and body arguments are keyword-only:
+
+```python
+nw.fx.convert_currency(from_="USD", to="IDR", amount="100.00")
+nw.fx.rate_history("USD", currencies=["IDR"], start_date="2026-01-01", end_date="2026-01-31")
+spot = nw.commodities.spot_price("XAU", "USD")
+nw.webhooks.update_destination(
+    "destination-id", url="https://example.test/webhook",
+    countries=["IDN"], families=["prices"], enabled=False,
+)
+feed_url = nw.calendar_subscriptions.feed_url("subscription-token")
+```
+
+Updates require `enabled` explicitly. Creation sends only supplied fields; omitted fields
+and explicit `None` remain distinct in request bodies. `feed_url()` makes no request.
+Lists use the documented repeated or comma-joined encoding. Scalar strings, empty list
+items and items containing commas are rejected for list query parameters.
+
+Every paginated operation has an `_iter` method, yielding items lazily (use `async for`
+with an async client). Filters persist across pages; `limit` is the page size. Cursor expiry
+raises `errors.CursorExpired`, including after earlier items were yielded.
+
+Top-level `meta` contains optional `request_id`, `quota`, and `short` values from response
+headers. Each rate limit has optional `limit`, `remaining`, and `reset` fields.
+
+## Failures and retries
+
+All client failures inherit `errors.NarwhalError`. `errors.ApiError` exposes `status`,
+`code`, `title`, `detail`, `request_id`, `instance`, `retry_after`, and `raw_body` bytes.
+Typed subclasses cover common statuses and cursor expiry. Known codes are exported as
+uppercase constants in `narwhalapi.codes`; codes also accept future strings.
+`TransportError.cause` preserves the underlying error. `DecodeError.raw_body` keeps an
+invalid success response as the original bytes. Import exceptions directly, for example
+`from narwhalapi.errors import RateLimited`. API errors display server fields as
+`HTTP <status> <code>: <title> (request_id <id>)`. All SDK errors support pickling.
+Client representations exclude credentials.
+
+Defaults are a 30-second attempt timeout, a 10-second connect timeout, two retries, and a
+30-second maximum retry wait. Only short-window 429s retry on any method. A 503 retries
+on GET; a transport failure retries on GET only before any response. Monthly quota
+exhaustion never retries. Redirects are not followed.
+Use `max_retries=0` to disable retries. Both clients honor standard proxy and certificate
+environment variables, including `HTTPS_PROXY` and `SSL_CERT_FILE`; supply `proxy=`
+to select an explicit proxy. `extra_headers` cannot replace Authorization.
+The `transport`, `clock`, `sleep`, and `random_fraction` constructor options support tests;
+async `sleep` must be awaitable.
+
+## Webhooks
+
+`from narwhalapi.webhooks import verify` verifies **exact raw bytes** before decoding.
+It accepts a nonempty secret string or a nonempty list of nonempty secrets during
+rotation. Empty secrets raise `ValueError` before verification. Timestamp tolerance is
+300 seconds by default. Use the returned `event_id` as the idempotency key and store it
+before applying the event. Future schema versions still decode.
+
+FastAPI:
+
+```python
+raw_body = await request.body()
+event = verify(raw_body, request.headers, webhook_secret)
+```
+
+Flask:
+
+```python
+raw_body = request.get_data(cache=True)
+event = verify(raw_body, request.headers, webhook_secret)
+```
+
+Do not parse and re-serialize the body before verification. A verification failure raises
+`errors.WebhookVerificationError` with a `reason`. Neither framework is a package dependency.

narwhalapi-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Narwhal API for Python
+
+Typed synchronous and asynchronous clients for economics, foreign exchange, calendars,
+physical palm oil, physical commodity reference prices, spot gold and silver, prediction markets, FX and commodity bar history, and webhook delivery. Python 3.10 or newer. Install with `pip install narwhalapi`.
+
+Set `NARWHAL_API_KEY` in the environment. Keep keys on the server. The default base URL is
+`https://api.narwhalapi.com`; override it with `NARWHAL_BASE_URL` or `base_url=`.
+
+## Quickstart
+
+```pycon
+>>> from decimal import Decimal
+>>> from narwhalapi import Narwhal
+>>> with Narwhal() as nw:
+...     cpi = nw.economics.cpi("USA")
+...     rates = nw.fx.rates("USD", currencies=["EUR", "JPY"])
+...     days = list(nw.fx.rate_history_iter(
+...         "USD", currencies=["EUR"], start_date="2026-08-20", end_date="2026-08-24"
+...     ))
+>>> isinstance(cpi.value, Decimal)
+True
+>>> isinstance(rates.rates[0].rate, Decimal)
+True
+>>> all(isinstance(rate.rate, Decimal) for day in days for rate in day.rates)
+True
+
+```
+
+Decimals remain exact `Decimal` values. Use `format(value, "f")` to display fixed-point
+wire text, including very small values. Decimal inputs accept `Decimal` or `str`;
+other numeric types raise `TypeError`. Responses accept only decimal strings matching
+`^-?\d+(\.\d+)?$` with ASCII digits. Dates and timestamps remain strings.
+
+```python
+from narwhalapi import AsyncNarwhal, errors
+
+async def load_rates():
+    async with AsyncNarwhal() as nw:
+        try:
+            return await nw.fx.rates("USD", currencies=["IDR", "SGD"])
+        except errors.RateLimited as error:
+            if error.is_quota_exhausted:
+                return None
+            raise
+```
+
+Share a synchronous client across threads. Use one async client per event loop.
+Context managers close connections; explicit `close()` and `await aclose()` also work.
+
+## Operations and types
+
+Namespaces are `economics`, `fx`, `calendars`, `commodities`, `events`, `webhooks`, and
+`calendar_subscriptions`. Operations not yet in the live API appear under `nw.unstable`;
+there are none today.
+Models and known string constants are available through `narwhalapi.models`,
+for example `from narwhalapi.models import Cpi`.
+Unknown enum strings are retained. Union variants are frozen dataclasses with a `kind`;
+its `kind` is the variant model name (for example `PalmoilSchedulePrice`).
+An unknown variant has `kind="unknown"` and keeps its JSON in `raw`.
+New response fields are ignored.
+
+Required path arguments may be positional. Query and body arguments are keyword-only:
+
+```python
+nw.fx.convert_currency(from_="USD", to="IDR", amount="100.00")
+nw.fx.rate_history("USD", currencies=["IDR"], start_date="2026-01-01", end_date="2026-01-31")
+spot = nw.commodities.spot_price("XAU", "USD")
+nw.webhooks.update_destination(
+    "destination-id", url="https://example.test/webhook",
+    countries=["IDN"], families=["prices"], enabled=False,
+)
+feed_url = nw.calendar_subscriptions.feed_url("subscription-token")
+```
+
+Updates require `enabled` explicitly. Creation sends only supplied fields; omitted fields
+and explicit `None` remain distinct in request bodies. `feed_url()` makes no request.
+Lists use the documented repeated or comma-joined encoding. Scalar strings, empty list
+items and items containing commas are rejected for list query parameters.
+
+Every paginated operation has an `_iter` method, yielding items lazily (use `async for`
+with an async client). Filters persist across pages; `limit` is the page size. Cursor expiry
+raises `errors.CursorExpired`, including after earlier items were yielded.
+
+Top-level `meta` contains optional `request_id`, `quota`, and `short` values from response
+headers. Each rate limit has optional `limit`, `remaining`, and `reset` fields.
+
+## Failures and retries
+
+All client failures inherit `errors.NarwhalError`. `errors.ApiError` exposes `status`,
+`code`, `title`, `detail`, `request_id`, `instance`, `retry_after`, and `raw_body` bytes.
+Typed subclasses cover common statuses and cursor expiry. Known codes are exported as
+uppercase constants in `narwhalapi.codes`; codes also accept future strings.
+`TransportError.cause` preserves the underlying error. `DecodeError.raw_body` keeps an
+invalid success response as the original bytes. Import exceptions directly, for example
+`from narwhalapi.errors import RateLimited`. API errors display server fields as
+`HTTP <status> <code>: <title> (request_id <id>)`. All SDK errors support pickling.
+Client representations exclude credentials.
+
+Defaults are a 30-second attempt timeout, a 10-second connect timeout, two retries, and a
+30-second maximum retry wait. Only short-window 429s retry on any method. A 503 retries
+on GET; a transport failure retries on GET only before any response. Monthly quota
+exhaustion never retries. Redirects are not followed.
+Use `max_retries=0` to disable retries. Both clients honor standard proxy and certificate
+environment variables, including `HTTPS_PROXY` and `SSL_CERT_FILE`; supply `proxy=`
+to select an explicit proxy. `extra_headers` cannot replace Authorization.
+The `transport`, `clock`, `sleep`, and `random_fraction` constructor options support tests;
+async `sleep` must be awaitable.
+
+## Webhooks
+
+`from narwhalapi.webhooks import verify` verifies **exact raw bytes** before decoding.
+It accepts a nonempty secret string or a nonempty list of nonempty secrets during
+rotation. Empty secrets raise `ValueError` before verification. Timestamp tolerance is
+300 seconds by default. Use the returned `event_id` as the idempotency key and store it
+before applying the event. Future schema versions still decode.
+
+FastAPI:
+
+```python
+raw_body = await request.body()
+event = verify(raw_body, request.headers, webhook_secret)
+```
+
+Flask:
+
+```python
+raw_body = request.get_data(cache=True)
+event = verify(raw_body, request.headers, webhook_secret)
+```
+
+Do not parse and re-serialize the body before verification. A verification failure raises
+`errors.WebhookVerificationError` with a `reason`. Neither framework is a package dependency.

narwhalapi-0.1.0/hatch_build.py

@@ -0,0 +1,14 @@
+"""Keep repository ignore files out of the source distribution."""
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        if self.target_name == "sdist":
+            forced = build_data["force_include"]
+            for path in list(forced):
+                if Path(path).name in {".gitignore", ".hgignore"}:
+                    del forced[path]

narwhalapi-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "narwhalapi"
+version = "0.1.0"
+description = "Typed clients for the Narwhal API"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Narwhal API Team", email = "support@narwhalapi.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.27,<1"]
+keywords = [
+    "api", "sdk", "economics", "fx", "exchange-rates", "inflation", "holidays",
+    "palm-oil", "decimal",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://narwhalapi.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/narwhalapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/narwhalapi", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.hooks.custom]

narwhalapi-0.1.0/src/narwhalapi/__init__.py

@@ -0,0 +1,17 @@
+"""Typed clients for the Narwhal API."""
+
+from . import codes, errors, models
+from ._client import AsyncNarwhal, Narwhal
+from ._meta import RateLimit, ResponseMeta
+from ._version import __version__
+
+__all__ = [
+    "AsyncNarwhal",
+    "Narwhal",
+    "RateLimit",
+    "ResponseMeta",
+    "__version__",
+    "codes",
+    "errors",
+    "models",
+]

narwhalapi-0.1.0/src/narwhalapi/_client.py

@@ -0,0 +1,122 @@
+"""Connection-owning synchronous and asynchronous clients."""
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+
+from ._generated.operations import (
+    LIVE_SPEC_SHA,
+    AsyncStableOperations,
+    StableOperations,
+)
+from ._transport import AsyncTransport, Settings, SyncTransport
+
+SyncClient = TypeVar("SyncClient", bound="Narwhal")
+AsyncClient = TypeVar("AsyncClient", bound="AsyncNarwhal")
+
+
+class Narwhal(StableOperations):
+    """Share one client across threads and close it when finished."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = SyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "Narwhal(api_key=<redacted>)"
+
+    def close(self) -> None:
+        self._transport.http.close()
+
+    def __enter__(self: SyncClient) -> SyncClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncNarwhal(AsyncStableOperations):
+    """Use one client per event loop and close it with async with."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = AsyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "AsyncNarwhal(api_key=<redacted>)"
+
+    async def aclose(self) -> None:
+        await self._transport.http.aclose()
+
+    async def __aenter__(self: AsyncClient) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()