finatic-server-python 1.0.3__tar.gz → 1.0.5__tar.gz

{finatic_server_python-1.0.3 → finatic_server_python-1.0.5}/.github/dependabot.yml

@@ -3,9 +3,9 @@ updates:
   - package-ecosystem: pip
     directory: /
     schedule:
-      interval: weekly
+      interval: monthly
     target-branch: develop
-    open-pull-requests-limit: 5
+    open-pull-requests-limit: 2
     reviewers:
       - founders
     assignees:
@@ -26,11 +26,10 @@ updates:
         update-types:
           - minor
           - patch
-
   - package-ecosystem: github-actions
     directory: /
     schedule:
-      interval: weekly
+      interval: monthly
     target-branch: develop
     reviewers:
       - founders
@@ -43,3 +42,4 @@ updates:
       ci-dependencies:
         patterns:
           - "*"
+    open-pull-requests-limit: 2

finatic_server_python-1.0.5/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, develop, staging, fdx-account-consent-v1]
+
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Skip heavy CI for Dependabot / release PRs
+        if: github.actor == 'dependabot[bot]' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.event.pull_request.title, 'chore(release):'))
+        run: echo "Skipping heavy product CI for Dependabot or chore(release) PRs (Actions cost control)."
+      - uses: actions/checkout@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        with:
+          # The generated-tree gate verifies legacy files against a pinned
+          # develop commit, so that object must be present in the CI clone.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        with:
+          enable-cache: true
+
+      - name: Install package with dev dependencies
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Compile package
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: uv run python -m compileall finatic_server_python src tests
+
+      - name: Verify generated OpenAPI account surface
+        if: matrix.python-version == '3.12' && github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: uv run python scripts/regenerate_openapi.py
+
+      - name: Run unit tests with coverage gate
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: >
+          uv run pytest -q -m "not integration"
+          --cov=src
+          --cov=finatic_server_python
+          --cov-report=term-missing:skip-covered
+          --cov-fail-under=50
+
+      - name: Build package
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: uv run python -m build

finatic_server_python-1.0.5/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,30 @@
+name: Dependabot auto-merge
+
+on:
+  pull_request:
+
+concurrency:
+  group: dependabot-auto-merge-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Enable auto-merge for minor and patch updates
+        if: contains(fromJSON('["version-update:semver-minor","version-update:semver-patch"]'), steps.metadata.outputs.update-type)
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{finatic_server_python-1.0.3 → finatic_server_python-1.0.5}/.github/workflows/release.yml

@@ -1,8 +1,7 @@
 name: Release
 
 on:
-  push:
-    branches: [main]
+  # Manual only: auto-publish on every main push re-bumps after version-sync PRs.
   workflow_dispatch:
     inputs:
       dry_run:
@@ -33,12 +32,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -129,7 +128,7 @@ jobs:
         run: uv run python -m build
 
       - name: Upload release artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: finatic-server-python-${{ steps.version.outputs.version }}
           path: dist/*

finatic_server_python-1.0.5/.github/workflows/security.yml

@@ -0,0 +1,63 @@
+name: Security
+
+# Cost controls:
+# - PR: actionlint + gitleaks only (cheap)
+# - schedule / workflow_dispatch only: + osv, licenses, codeql
+# - PR cheap jobs run for Dependabot; heavy jobs still skip Dependabot
+# - cancel superseded runs on the same ref
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  actionlint:
+    uses: FinaticORG/.github/.github/workflows/reusable-actionlint.yml@main
+    with:
+      strict: true
+
+  gitleaks:
+    uses: FinaticORG/.github/.github/workflows/reusable-gitleaks.yml@main
+    with:
+      strict: true
+      scan-mode: no-git
+
+  osv:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-osv.yml@main
+    with:
+      strict: true
+
+  licenses:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-licenses-pip.yml@main
+    with:
+      strict: true
+
+  codeql:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-codeql.yml@main
+    with:
+      languages: '["python"]'

{finatic_server_python-1.0.3 → finatic_server_python-1.0.5}/CHANGELOG.md

@@ -1,8 +1,25 @@
 # Changelog
 
+## 1.0.5
+
+- Release from d4277ef3e830b95a4d337992784833d864d679f1.
+
+## Unreleased
+
+- Regenerate the account-resource client from FinaticAPI PR #748 and expose
+  typed instrument descriptors for orders, fills, events, positions, lots, and
+  lot fills.
+- Add typed canonical `finaticInstrumentId` placement while preserving the
+  provider-native `instrumentId`, arbitrary provider fields, raw dictionaries,
+  account scoping, and idempotency behavior.
+
+## 1.0.4
+
+- Release from 1f12f4e6b4f0eba77d315913d338d90aef8adfd9.
+
 ## 1.0.3
 
-- Release from bdc237bcfc54837c641e52e28b7883f7c51ec4b6.
+- Release sync after PyPI publish.
 
 ## 1.0.2
 

finatic_server_python-1.0.5/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: finatic-server-python
+Version: 1.0.5
+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.
+
+### Exact instrument identity
+
+Order, fill, event, position, lot, and lot-fill responses expose the generated
+`FDXInstrumentDescriptor` contract. `future.identityQuality` distinguishes an
+exact contract such as `MGCZ6` from a root-only identity such as `MGC`; optional
+month, expiry, MIC, and provenance fields remain absent when the API did not
+prove them.
+
+```python
+from finatic_server_python import AccountOrderPayload, FDXInstrumentDescriptor
+
+order = AccountOrderPayload.from_dict(
+    {
+        "finaticInstrumentId": "finatic:future:MGCZ6",
+        "instrumentId": 611092087,  # provider-native identity remains supported
+        "symbol": "MGCZ6",
+    }
+)
+result = await finatic.v1.create_account_order(
+    account_id, order, idempotency_key="unique-command-key"
+)
+```
+
+The server authorizes and resolves identities in account/provider scope. The
+SDK preserves both identifiers and never infers an exact contract from a root.
+The v1 facade continues to return dictionaries; its generated `TypedDict`
+annotations make descriptor keys discoverable without changing existing
+mapping access. Generated model classes remain available when explicit
+validation or construction is desired.
+
+## 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.5/README.md

@@ -0,0 +1,140 @@
+# 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.
+
+### Exact instrument identity
+
+Order, fill, event, position, lot, and lot-fill responses expose the generated
+`FDXInstrumentDescriptor` contract. `future.identityQuality` distinguishes an
+exact contract such as `MGCZ6` from a root-only identity such as `MGC`; optional
+month, expiry, MIC, and provenance fields remain absent when the API did not
+prove them.
+
+```python
+from finatic_server_python import AccountOrderPayload, FDXInstrumentDescriptor
+
+order = AccountOrderPayload.from_dict(
+    {
+        "finaticInstrumentId": "finatic:future:MGCZ6",
+        "instrumentId": 611092087,  # provider-native identity remains supported
+        "symbol": "MGCZ6",
+    }
+)
+result = await finatic.v1.create_account_order(
+    account_id, order, idempotency_key="unique-command-key"
+)
+```
+
+The server authorizes and resolves identities in account/provider scope. The
+SDK preserves both identifiers and never infers an exact contract from a root.
+The v1 facade continues to return dictionaries; its generated `TypedDict`
+annotations make descriptor keys discoverable without changing existing
+mapping access. Generated model classes remain available when explicit
+validation or construction is desired.
+
+## 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)