finatic-server-python 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

finatic_server_python/__init__.py

@@ -6,20 +6,21 @@ Import::
 
     from finatic_server_python import FinaticServer
 
-    finatic = FinaticServer(api_key="...")
-    await finatic.v1.create_session()
-    await finatic.v1.create_portal_link()
+    finatic = FinaticServer(
+        api_key="fntc_sandbox_your_key",
+        sdk_config={"environment": "sandbox"},
+    )
+    token = await finatic.v1.get_token()  # 90 seconds; send to the browser only
 
 Package layout:
 
 - ``finatic_server_python`` — stable public import name (this shim re-exports ``src``).
 - ``src`` — hand-written SDK: ``FinaticServer``, ``FinaticServerCore``, ``v1.V1Client``.
 - ``finatic_server`` — generated OpenAPI transport client (``src/openapi/finatic_server``).
-  Use ``finatic_server`` only for low-level generated APIs; prefer ``FinaticServer.v1``.
+  Prefer ``FinaticServer.v1``.
 
-Portal auth flows (institutions, auth-attempts, discovered accounts, grant consent UI)
-run in **FinaticConnect**, not the server SDK. The server SDK exposes session +
-``portal-links`` creation and post-consent account/grant/webhook APIs.
+Portal auth UX runs in **FinaticConnect**. This SDK mints one-time tokens and portal URLs
+and exposes post-grant account, order, grant, and webhook APIs.
 """
 
 from __future__ import annotations

finatic_server_python-1.0.4.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: finatic-server-python
+Version: 1.0.4
+Summary: Python SDK for Finatic Server API
+Project-URL: Homepage, https://github.com/FinaticORG/FinaticServerSDK-Python
+Project-URL: Documentation, https://docs.finatic.com/python
+Project-URL: Repository, https://github.com/FinaticORG/FinaticServerSDK-Python
+Project-URL: Issues, https://github.com/FinaticORG/FinaticServerSDK-Python/issues
+Author-email: Finatic <support@finatic.dev>
+License: PROPRIETARY
+License-File: LICENSE
+Keywords: api,finance,finatic,sdk,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiohttp-retry>=2.9.1
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: cachetools>=7.1.7
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: typing-extensions>=4.16.0
+Requires-Dist: urllib3>=2.7.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: build>=1.5.0; extra == 'dev'
+Requires-Dist: flake8>=7.3.0; extra == 'dev'
+Requires-Dist: isort>=8.0.1; extra == 'dev'
+Requires-Dist: mypy>=2.3.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-cachetools>=5.3.0; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.9.0.20260716; extra == 'dev'
+Provides-Extra: integration
+Requires-Dist: psycopg[binary]>=3.3.4; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# Finatic Server SDK (Python)
+
+Python SDK for embedding Finatic in **your backend**. Keep the company API key on the server. Mint a 90-second one-time token for the browser Client SDK, or start a session and redirect to Connect.
+
+## Install
+
+```bash
+pip install finatic-server-python
+```
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from finatic_server_python import FinaticServer
+
+
+async def main() -> None:
+    finatic = FinaticServer(
+        api_key=os.environ["FINATIC_API_KEY"],
+        sdk_config={"environment": "sandbox"},
+    )
+
+    # Client iframe: 90-second token. Never send the API key to the browser.
+    one_time_token = await finatic.v1.get_token()
+
+    # Redirect flow: start a session first (get_portal_url requires it).
+    session = await finatic.v1.start_session()
+    if not session.get("session_id"):
+        raise RuntimeError(session.get("error") or "Session start failed")
+    portal_url = await finatic.v1.get_portal_url(mode="dark")
+
+    # After account.grant.created, start a session for that portal user, then read.
+    portal_user_id = "user-from-connect-onSuccess"
+    authed = await finatic.v1.start_session(user_id=portal_user_id)
+    if not authed.get("session_id"):
+        raise RuntimeError(authed.get("error") or "Authenticated session start failed")
+    accounts = await finatic.v1.list_accounts(include_sync_status=True)
+    if accounts.get("errors"):
+        raise RuntimeError(accounts["errors"])
+    if not accounts.get("data"):
+        raise RuntimeError("No granted accounts yet")
+    account_id = accounts["data"][0]["accountId"]
+    positions = await finatic.v1.list_positions(account_id)
+
+
+asyncio.run(main())
+```
+
+Server `v1` data methods return `{ "traceId", "data", "warnings", "errors" }`. Check `errors` before using `data`.
+
+Use `sdk_config={"environment": "sandbox"}` for Finatic synthetic data (`fntc_sandbox_` keys). Broker paper/sim accounts stay `live`.
+
+`FinaticServer.init(...)` is a shortcut that calls `start_session`. Use the constructor + `get_token()` when you only need to hand a token to the browser.
+
+## Embed Connect
+
+Connect UI lives in **FinaticConnect**. This SDK does not open an iframe.
+
+1. `v1.get_token()` → pass the token to `@finatic/client` `FinaticConnect.init(token)` in the browser (token TTL is 90 seconds).
+2. Or `v1.start_session()` then `v1.get_portal_url(...)` → redirect. Treat the full URL as secret.
+
+Wait for HTTPS webhook `account.grant.created` (or poll `list_accounts` on an ACTIVE session) before account-scoped reads.
+
+## Trading
+
+Fetch the broker schema, then send an idempotent command:
+
+```python
+schema = await finatic.v1.get_account_order_schema(account_id, "place")
+created = await finatic.v1.create_account_order(
+    account_id,
+    {"symbol": "AAPL", "quantity": 1, "side": "BUY", "type": "MARKET"},
+    idempotency_key="partner-order-123",
+)
+```
+
+Python wraps the dict as `{"order": ...}` on the wire. `idempotency_key` is required.
+
+## Package layout
+
+| Name | Role |
+|------|------|
+| `finatic-server-python` | PyPI package |
+| `finatic_server_python` | Public import |
+| `src` | Hand-written `FinaticServer` and `v1.V1Client` |
+| `finatic_server` | Generated OpenAPI transport — prefer `FinaticServer.v1` |
+
+## Common commands
+
+| Task | Command |
+|------|---------|
+| Test | `pytest` |
+| Type check | `mypy` |
+
+## Documentation
+
+This README is the Python SDK contract. Fetch the rest before writing a full integration:
+
+- Quick start: [https://finatic.dev/docs/quick-start/quick-start](https://finatic.dev/docs/quick-start/quick-start)
+- Client SDK README: [https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md](https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md)
+- Node SDK README: [https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md](https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md)
+- Embed Connect: [https://finatic.dev/docs/quick-start/account-grants](https://finatic.dev/docs/quick-start/account-grants)
+- Demo apps: [https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md](https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md)
+- API reference: [https://finatic.dev/docs/api-reference](https://finatic.dev/docs/api-reference)
+- OpenAPI: [https://finatic.dev/openapi.json](https://finatic.dev/openapi.json)
+- Agent index: [https://finatic.dev/llms.txt](https://finatic.dev/llms.txt)
+- Agent notes: [https://finatic.dev/AGENTS.md](https://finatic.dev/AGENTS.md)

{finatic_server_python-1.0.2.dist-info → finatic_server_python-1.0.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 finatic_server/__init__.py,sha256=4kk4SVN6YPa8g371MGc7jWoypOAn9YGwBDvJqLvQeqM,955
-finatic_server_python/__init__.py,sha256=jV_HoyqvvficeZ7qnRmbYUUM4WQdj_Z0PAqT70kA1M4,1143
+finatic_server_python/__init__.py,sha256=LB4GcHvm7rEvldM1iqzVqYrJ4WDSQR5-AEd5Kj3uDLw,1082
 src/.openapi-generator-ignore,sha256=46FEmqRTpNMVA_uwwYPyCJXI7qufXp0A7sk0ZUY6OEQ,714
 src/FinaticServer.py,sha256=5FqaZEm21BNZeos-QMCTPDv3rWq4XWr9DGUU7K7M53k,238
 src/FinaticServerCore.py,sha256=hsunqG9ligZGEdqnkma1mki7TwHiEY7JRaQ0qJCwtaI,2704
@@ -7,7 +7,7 @@ src/__init__.py,sha256=IVXwcOfwSGqWIXnEl8c0s6LX7FOBqAIeqAA8wZKifqM,363
 src/config.py,sha256=X10rF_jr-VlwiTAaHNIJZJ97q4932PoRKZW-P90j44M,2412
 src/finatic_fdx_types.py,sha256=RyM3v9Y48VwhKhAtgtZilGErwF2jNRT9YAPBEJ3tin0,664
 src/types.py,sha256=Ze4isFaWuwm6b6zrCmAhkt8tmGuBZ2XX-9oPYeMwI6s,639
-src/v1.py,sha256=YWJjosjdJQirplRxoc7kXKcW-JZjv_3SVkaZLjx68vE,25779
+src/v1.py,sha256=8KUGwTZ2XjZBR0HRm_tcldWKMqV9WjTDhWzVIFAKvmI,26739
 src/internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 src/openapi/.openapi-generator-ignore,sha256=46FEmqRTpNMVA_uwwYPyCJXI7qufXp0A7sk0ZUY6OEQ,714
 src/openapi/path_bootstrap.py,sha256=ywVDEDRhAEs9aqmchRETHPOONaGg5lV4U05CDsaMyxY,622
@@ -379,7 +379,7 @@ src/utils/request_id.py,sha256=R_Gcyc5rih7_keAruJHW0bg0Y0MCqQNsUgkZ4C_9sRc,200
 src/utils/url_utils.py,sha256=dtxaFEF6Li_lQ7ft0BEDsbyYUDcNXUN4WO_yVAG5MJ8,5051
 src/utils/validation.py,sha256=ODt5raui4KVH1Iz_-Tt8-VKEw-yUzIZg6o93iWLwRj0,1263
 src/wrappers/__init__.py,sha256=8puRg8uOrUR42gCwCtW5zkOtCDbgyMpZSMi2iz2bPcU,123
-finatic_server_python-1.0.2.dist-info/METADATA,sha256=IKxDjqCgRYyv-SlxRJjp33XRYELGxyFFNLJHGlwTMe4,6483
-finatic_server_python-1.0.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-finatic_server_python-1.0.2.dist-info/licenses/LICENSE,sha256=hE35tOCe7uZCeYglYc-sjRSjad4jPyB3i53-QW1YfLk,3590
-finatic_server_python-1.0.2.dist-info/RECORD,,
+finatic_server_python-1.0.4.dist-info/METADATA,sha256=t40vIw1VPjy-1XZPjMxBvslBErL-WYUSODcxn_ZWEUM,6532
+finatic_server_python-1.0.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+finatic_server_python-1.0.4.dist-info/licenses/LICENSE,sha256=hE35tOCe7uZCeYglYc-sjRSjad4jPyB3i53-QW1YfLk,3590
+finatic_server_python-1.0.4.dist-info/RECORD,,

{finatic_server_python-1.0.2.dist-info → finatic_server_python-1.0.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any

src/v1.py

@@ -130,6 +130,16 @@ class V1Client:
         )
 
     async def get_token(self, api_key: str | None = None) -> str:
+        """Mint a 90-second one-time token for the browser Client SDK.
+
+        Does not start a session. For redirect, call ``start_session()`` then
+        ``get_portal_url()``.
+
+        @example
+        ```python
+        token = await finatic.v1.get_token()
+        ```
+        """
         response = await self.init_session(api_key)
         if response.get("errors"):
             errors = response["errors"]
@@ -222,6 +232,14 @@ class V1Client:
         email: str | None = None,
         mode: Literal["light", "dark"] | None = None,
     ) -> str:
+        """Return a Connect redirect URL. Does not open a browser iframe.
+
+        @example
+        ```python
+        session = await finatic.v1.start_session()
+        portal_url = await finatic.v1.get_portal_url(mode='dark')
+        ```
+        """
         if not self.session_id:
             raise ValueError("Session not initialized. Call v1.start_session() first.")
 
@@ -289,6 +307,14 @@ class V1Client:
         offset: int | None = None,
         include_sync_status: bool | None = None,
     ) -> FinaticResponse:
+        """List granted financial accounts. Server envelope uses ``data`` / ``errors``.
+
+        @example
+        ```python
+        result = await finatic.v1.list_accounts()
+        print(result.get('data'), result.get('traceId'))
+        ```
+        """
         return await self._request(
             "GET",
             "/api/v1/accounts",
@@ -329,6 +355,13 @@ class V1Client:
     async def list_positions(
         self, account_id: str, *, limit: int | None = None, offset: int | None = None
     ) -> FinaticResponse:
+        """Positions for one financial account.
+
+        @example
+        ```python
+        result = await finatic.v1.list_positions('acct_123')
+        ```
+        """
         return await self.list_account_resource(
             account_id, "positions", limit=limit, offset=offset
         )

finatic_server_python-1.0.2.dist-info/METADATA

@@ -1,168 +0,0 @@
-Metadata-Version: 2.4
-Name: finatic-server-python
-Version: 1.0.2
-Summary: Python SDK for Finatic Server API
-Project-URL: Homepage, https://github.com/FinaticORG/FinaticServerSDK-Python
-Project-URL: Documentation, https://docs.finatic.com/python
-Project-URL: Repository, https://github.com/FinaticORG/FinaticServerSDK-Python
-Project-URL: Issues, https://github.com/FinaticORG/FinaticServerSDK-Python/issues
-Author-email: Finatic <support@finatic.dev>
-License: PROPRIETARY
-License-File: LICENSE
-Keywords: api,finance,finatic,sdk,trading
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Office/Business :: Financial
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
-Requires-Dist: aiohttp-retry>=2.9.1
-Requires-Dist: aiohttp>=3.13.2
-Requires-Dist: cachetools>=6.2.2
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-dateutil>=2.9.0.post0
-Requires-Dist: structlog>=25.5.0
-Requires-Dist: tenacity>=9.1.2
-Requires-Dist: typing-extensions>=4.15.0
-Requires-Dist: urllib3>=2.6.1
-Provides-Extra: dev
-Requires-Dist: black>=23.0.0; extra == 'dev'
-Requires-Dist: build>=1.2.2; extra == 'dev'
-Requires-Dist: flake8>=6.0.0; extra == 'dev'
-Requires-Dist: isort>=5.12.0; extra == 'dev'
-Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
-Requires-Dist: pytest>=7.0.0; extra == 'dev'
-Requires-Dist: types-cachetools>=5.3.0; extra == 'dev'
-Requires-Dist: types-python-dateutil>=2.8.0; extra == 'dev'
-Provides-Extra: integration
-Requires-Dist: psycopg[binary]>=3.2.0; extra == 'integration'
-Description-Content-Type: text/markdown
-
-# Finatic Server SDK (Python)
-
-Python SDK for server-side Finatic integrations.
-
-Use this package to authenticate with Finatic from Python services, generate client tokens, and retrieve standardized broker-domain data.
-
-## Version lines (FDX v1)
-
-| Version | API surface | Use when |
-|---------|-------------|----------|
-| **1.0.0** | `/api/v1/*` via `FinaticServer.v1` | New account-grant integrations |
-
-The 1.0 line does not ship generated beta broker/company clients, connection-first models, or
-inactive position-lot types. The generated transport source is maintained for the account-first
-v1/session surface used by the public facade.
-
-## Install
-
-```bash
-pip install finatic-server-python
-```
-
-## Quick Start
-
-```python
-from finatic_server_python import FinaticServer
-
-finatic = await FinaticServer.init(api_key="your-api-key")
-token = await finatic.get_token()
-positions = await finatic.get_all_positions()
-```
-
-## Package layout
-
-| Name | Role |
-|------|------|
-| `finatic-server-python` | PyPI package (`pip install finatic-server-python`) |
-| `finatic_server_python` | Public import path (`from finatic_server_python import FinaticServer`) |
-| `src` | Hand-written SDK (`FinaticServer`, `v1.V1Client`) |
-| `finatic_server` | Generated OpenAPI transport client (`src/openapi/finatic_server`) |
-
-Portal connect flows (institutions, auth-attempts, discovered accounts, grant UI)
-run in **FinaticConnect**, not the server SDK. The server SDK exposes session
-management, `portal-links` creation, and post-consent account/grant/webhook APIs.
-
-## Account-First v1 Preview
-
-The v1 facade targets the SDK OpenAPI contract (`spec-sdk.yaml`) and sends
-`X-Finatic-Environment` on every request.
-
-```python
-from finatic_server_python import FinaticServer
-
-finatic = FinaticServer(
-    api_key="fntc_live_your_key",
-    sdk_config={"environment": "live"},
-)
-
-session = await finatic.v1.create_session()
-portal_link = await finatic.v1.create_portal_link()
-# Open portal_link URL in FinaticConnect for user auth + grant consent
-
-accounts = await finatic.v1.list_accounts()
-orders = await finatic.v1.list_account_orders("broker-account-id")
-created = await finatic.v1.create_account_order(
-    "broker-account-id",
-    {"symbol": "AAPL", "quantity": 1, "side": "BUY", "type": "MARKET"},
-    idempotency_key="partner-order-123",
-)
-```
-
-Use `sdk_config={"environment": "sandbox"}` for Finatic synthetic sandbox data.
-Broker paper or simulated accounts remain `live` environment accounts.
-
-### OpenAPI Contract Artifact
-
-The v1 facade is validated against `artifacts/openapi/finaticapi-v1.json`, which
-is exported from the FinaticAPI account-first branch. Refresh it with:
-
-```bash
-env PYTHONPATH=/home/claw/.openclaw/workspace/worktrees/FinaticAPI-pr174-openapi/src:/home/claw/.openclaw/workspace/worktrees/FinaticCore-pr171-openapi/src /home/claw/.openclaw/workspace/repos/FinaticAPI/.venv/bin/python /home/claw/.openclaw/workspace/worktrees/FinaticAPI-pr174-openapi/scripts/export_openapi.py --output /home/claw/.openclaw/workspace/repos/FinaticServerSDK-Python/artifacts/openapi/finaticapi-v1.json
-```
-
-PR #25 currently uses FinaticAPI PR #174 head `4ca17320` and finaticCore PR
-#171 head `0a126bed` as branch-ready dependency inputs. The package version is
-prepared as `1.0.0` for the API v1 semver lane, but the coordinated FDX
-account-consent operator hold still controls merge and release timing.
-
-## Common Commands
-
-| Task | Command |
-|---|---|
-| Install in editable mode | `uv pip install -e .` |
-| Run tests | `pytest` |
-| Build package | `python -m build` |
-| Lint | `ruff check .` |
-| Format | `ruff format .` |
-
-## Core Capabilities
-
-- API-key initialization and session management.
-- Portal URL generation for end-user authentication.
-- One-time token generation for client SDK sessions.
-- Typed access to orders, positions, accounts, and balances.
-- Consistent response/error structures across endpoints.
-
-## Documentation
-
-- Product docs: [https://finatic.dev/docs](https://finatic.dev/docs)
-- API reference: [https://finatic.dev/docs/api-reference](https://finatic.dev/docs/api-reference)
-- LLM context doc: [https://finatic.dev/llms.txt](https://finatic.dev/llms.txt)
-
-## Using Finatic with AI
-
-Use this SDK in Python AI/data systems to:
-
-- query balances, positions, and orders across connected brokers
-- normalize broker interactions behind one SDK surface
-- feed structured brokerage data into analytics or model workflows
-
-MCP support is coming soon.