mywebapi-sdk 0.3.0__tar.gz

mywebapi_sdk-0.3.0/.env.example

@@ -0,0 +1,22 @@
+# CPlugin WebAPI Python SDK — example environment.
+# Copy to `.env` (gitignored) and fill in your credentials:  cp .env.example .env
+
+# --- Environment (staging is the safe default) ---
+# The SDK selects an environment by name; for the examples/e2e you pass
+# env="staging" (or "prod") in code. These vars feed the example scripts.
+
+# --- Credentials (required) ---
+# Create and manage API keys in the Toolbox (https://toolbox.cplugin.com for prod,
+# https://pre.toolbox.cplugin.com for staging).
+WEBAPI_CLIENT_ID=your-client-id
+WEBAPI_CLIENT_SECRET=your-client-secret
+
+# --- Optional ---
+# Trade platform GUID. Created and managed in the Toolbox. Leave empty and run
+# `python examples/01_hello.py` to list the platforms your credentials can access.
+WEBAPI_TRADE_PLATFORM=
+
+# --- End-to-end tests (opt-in) ---
+# Set WEBAPI_E2E=1 together with the credentials above to run the gated e2e
+# suite against staging:  WEBAPI_E2E=1 python -m pytest e2e -q
+WEBAPI_E2E=

mywebapi_sdk-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + test deps
+        # * Editable install so the package imports as `cplugin_webapi_sdk`.
+        #   signalrcore is NOT installed: the realtime unit tests monkeypatch the
+        #   lazy import, so they run without the optional extra.
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[test]"
+
+      - name: Run tests
+        # * The e2e suite is double-gated (WEBAPI_E2E + credentials, and signalrcore
+        #   for the SignalR smoke); with neither present it skips cleanly, so unit
+        #   and contract tests run hermetically in CI with no extra setup.
+        run: python -m pytest -q
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Build distributions
+        run: python -m pip install --upgrade build && python -m build
+
+      - name: Twine check
+        run: python -m pip install --upgrade twine && python -m twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

mywebapi_sdk-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+name: Publish to PyPI
+
+# * Triggered by pushing a version tag (e.g. v0.1.0, v1.2.3).
+# * Uses PyPI Trusted Publishing (OIDC) — NO long-lived PYPI_TOKEN, nothing to rotate.
+# * Unlike npm, PyPI supports a "pending publisher": you can configure the trusted
+# *   publisher BEFORE the first release, so no bootstrap-token publish is needed.
+# *   On pypi.org: Account/Project → Publishing → Add a GitHub Actions publisher →
+# *   owner=<org>, repo=<repo>, workflow=publish.yml, environment=pypi.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  # * Release gate: a tag publishes only a commit that reached main through a merged pull
+  #   request and passed CI there. Tags are admin-only and immutable (repository rulesets);
+  #   this job refuses a tag put on any other commit, so review happens on the pull request.
+  gate:
+    name: Release gate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Tagged commit is on main and passed CI
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_REF_NAME points to $GITHUB_SHA, which is not on main. Release only commits merged into main."
+            exit 1
+          fi
+          passed=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$GITHUB_SHA&status=success&per_page=1" --jq '.total_count')
+          if [ "$passed" -lt 1 ]; then
+            echo "::error::CI has not passed on $GITHUB_SHA. Wait for it on main, then push the tag again."
+            exit 1
+          fi
+          echo "$GITHUB_REF_NAME -> $GITHUB_SHA: on main, CI passed."
+
+  build:
+    name: Build sdist + wheel
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Build distributions
+        run: python -m pip install --upgrade build && python -m build
+
+      - name: Twine check
+        run: python -m pip install --upgrade twine && python -m twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (OIDC trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    # * A GitHub Environment named "pypi" lets you add release protection rules
+    #   (required reviewers, tag restrictions) and is the conventional pairing
+    #   with a PyPI trusted publisher scoped to that environment.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mywebapi-sdk
+    permissions:
+      # ! Required for OIDC trusted publishing — mints the short-lived id-token
+      #   PyPI verifies. No API token is stored anywhere.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        # * No password/token input: the action exchanges the workflow's OIDC
+        #   id-token for a short-lived PyPI upload credential.
+        uses: pypa/gh-action-pypi-publish@release/v1

mywebapi_sdk-0.3.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env

mywebapi_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `mywebapi-sdk` (import name `cplugin_webapi_sdk`). The package follows [semver](https://semver.org/); while it is at `0.x`, a minor release may contain breaking changes.
+
+## 0.3.0
+
+First release on PyPI. The version continues the numbering of the JavaScript, .NET and PowerShell SDKs, which ship the same features as 0.3.0. Request timeouts need a server that answers with `X-Request-Outcome`; older servers ignore the new header and keep working.
+
+### Added
+
+- `request_timeout=` (seconds, 1–300) on every namespace method and on `raw()`, and client-wide on `CPluginWebApiClient` / `CPluginWebApiAsyncClient`. Sent as `X-Request-Timeout`; an out-of-range value raises `ValueError` before anything is sent. `raw()` also accepts the generated name `x_request_timeout`.
+- The HTTP timeout of every trade-platform call is stretched to at least its server deadline + 30 s — `request_timeout`, else the operation's default from the spec (60 s for an operation that documents none): the server may add up to 20 s for connecting to the trading platform, and the client must not give up before the server says whether the operation was applied. The client-wide `timeout` (still 30 s by default) is the floor and is never shortened.
+- `idempotency_key=` on `patch_user_record()` and `raw()`, sent as `Idempotency-Key` — the safe way to recover from `OutcomeUnknown`.
+- `ApiError.outcome` (`X-Request-Outcome`: `timeout`, `unknown`, `not-started`, `in-progress`), `ApiError.applied_timeout` (`X-Request-Timeout-Applied`), `ApiError.headers`, and the `outcome_unknown` / `safe_to_retry` properties.
+- `is_outcome_unknown(err)`, `is_safe_to_retry(err)`, `ErrorCode` (including the new `Timeout`, `OutcomeUnknown`, `Busy`), `RequestOutcome`, `MIN_REQUEST_TIMEOUT`, `MAX_REQUEST_TIMEOUT`.
+- Flag-field helpers `parse_flags`, `format_flags`, `has_flag`, `with_flag`.
+- README sections "Timeouts and retries" and "Flag fields".
+
+### Changed
+
+- Regenerated from the current server spec (172 paths). Every trade-platform operation, the MT4 x86 sidecar ones included (plugins, mails and news, batch snapshots and sync reads, `ExternalCommandBinary`), documents its default timeout in its docstring; the generated functions take `x_request_timeout` and send it only when set.
+- Flag fields (user rights, group permissions, symbol, order, position and deal flags) are `str` — the names of the set bits joined by `", "` — instead of single-value enums that rejected every combination. The enum modules `users_rights`, `group_rights`, the `en_*_flags` modules except `en_gateway_account_flags`, `trade_activation_flags`, `trade_modify_flags` and `tick_request_flags` under `_generated.models` are removed.
+- The six v2 `PATCH` operations (MT4 `GroupRecord`, `SymbolConfig`, `UserRecord`; MT5 `GroupRecord`, `UserRecord`, `SymbolRecord`) now take a required `body` — a JSON Merge Patch object with only the fields to change — and `ExternalCommandJSON` takes a required `body` (any JSON value). Previously the spec declared no body, so the generated functions could not send one.
+- `patch_user_record(trade_platform, login, changes)` takes the changed fields as a mapping (wire names, e.g. `{"leverage": 200}`) and sends them; before, it sent no body at all. An empty or non-mapping `changes` is rejected before sending.
+- History calls (30 s server default) and server maintenance (60 s) are no longer cut off by the 30 s client timeout before the server answers.
+- `ApiError` takes an optional fourth argument, the response headers; `unwrap()` passes them from any response that has `.headers`.
+
+### Unchanged on purpose
+
+- No request is repeated because of a timeout or an error — not on `OutcomeUnknown`, `in-progress`, `Timeout` or `Busy`, not on a transport error. `retries=` repeats only opening the connection, before any byte of the request is sent; the one re-send after a `401` (fresh token) is unchanged, the server refuses an unauthenticated request before running it.
+
+### Fixed
+
+- README: the real-time extra is `signalr`, not `realtime`; the streaming example used a handler as an iterator.

mywebapi_sdk-0.3.0/LICENSE

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

mywebapi_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.5
+Name: mywebapi-sdk
+Version: 0.3.0
+Summary: Python client for the MyWebAPI.com trading platform management API (v2). Generated endpoints + httpx ergonomic layer.
+Project-URL: Homepage, https://github.com/CPlugin/mywebapi.com-sdk-py
+Project-URL: Repository, https://github.com/CPlugin/mywebapi.com-sdk-py
+Project-URL: Issues, https://github.com/CPlugin/mywebapi.com-sdk-py/issues
+Project-URL: Changelog, https://github.com/CPlugin/mywebapi.com-sdk-py/blob/main/CHANGELOG.md
+Author: CPlugin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: broker,forex,httpx,mywebapi,sdk,signalr,trading,trading-platform,webapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: codegen
+Requires-Dist: openapi-python-client==0.29.0; extra == 'codegen'
+Provides-Extra: signalr
+Requires-Dist: signalrcore>=0.9.5; extra == 'signalr'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# CPlugin SaaS WebAPI — Python SDK
+
+Python client for the MyWebAPI.com trading platform management API (v2).
+
+## Install
+
+```bash
+pip install mywebapi-sdk            # REST client
+pip install "mywebapi-sdk[signalr]" # plus the experimental real-time client
+```
+
+The distribution is `mywebapi-sdk`; the import name is `cplugin_webapi_sdk`. Until the first release is on PyPI, install from a checkout of this repository:
+
+```bash
+pip install -e ".[test]"
+```
+
+This installs `cplugin_webapi_sdk` plus the test dependencies. Use `.[codegen]` to add the code-generation toolchain (see [Regenerate](#regenerate)).
+
+## Environment presets
+
+The client ships with two environment presets. Pass `env=` at construction time — no URL configuration needed:
+
+| `env=`       | API base URL                        | Auth URL                            |
+|--------------|-------------------------------------|-------------------------------------|
+| `"prod"`     | `https://cloud.mywebapi.com`        | `https://auth.cplugin.net`          |
+| `"staging"`  | `https://pre.mywebapi.com`          | `https://pre.auth.cplugin.net`      |
+| `"custom"`   | supply `api_base_url=` + `authority=` | —                                 |
+
+Credentials (client ID and secret) are managed through the **CPlugin Toolbox**:
+
+- Staging: <https://pre.toolbox.cplugin.com>
+- Production: <https://toolbox.cplugin.com>
+
+## Quick start
+
+```python
+import os
+from cplugin_webapi_sdk import CPluginWebApiClient, ApiError
+
+# * The client manages OAuth2 token acquisition, caching, and refresh
+# * transparently — pass credentials once, call methods on .mt4 / .mt5.
+with CPluginWebApiClient(
+    env="staging",
+    client_id=os.environ["WEBAPI_CLIENT_ID"],
+    client_secret=os.environ["WEBAPI_CLIENT_SECRET"],
+) as client:
+    # Discover configured trade platforms
+    platforms = client.list_trade_platforms()
+    tp = platforms[0]["id"]
+
+    # server time (mt4 namespace)
+    print("server time (mt4):", client.mt4.get_server_time(tp))
+
+    # server time (mt5 namespace)
+    print("server time (mt5):", client.mt5.get_server_time(tp))
+
+    # Error handling
+    try:
+        client.mt4.get_user_record(tp, 99999999)
+    except ApiError as e:
+        print(f"Error [{e.code}]: {e.description}")
+        if e.activity_id:
+            print("  Activity ID:", e.activity_id)
+```
+
+### Static token (advanced / testing)
+
+```python
+from cplugin_webapi_sdk import CPluginWebApiClient
+
+client = CPluginWebApiClient(env="staging", token="your-bearer-token")
+```
+
+### Async
+
+An `async with`-compatible counterpart is available as `CPluginWebApiAsyncClient`:
+
+```python
+import asyncio, os
+from cplugin_webapi_sdk import CPluginWebApiAsyncClient
+
+async def main():
+    async with CPluginWebApiAsyncClient(
+        env="staging",
+        client_id=os.environ["WEBAPI_CLIENT_ID"],
+        client_secret=os.environ["WEBAPI_CLIENT_SECRET"],
+    ) as client:
+        t = await client.mt4.get_server_time(tp)
+        print(t)
+
+asyncio.run(main())
+```
+
+## Timeouts and retries
+
+Every call addressed to a trade platform has a deadline on the server. When the trading platform does not answer in time, the API still answers — with an error that says whether the operation can have been applied. Default deadlines per operation: trade 5 s, read 10 s, change 15 s, history and reports 30 s, server maintenance 60 s. The API reference lists the default of each operation.
+
+Set your own deadline, in seconds from 1 to 300, for the whole client or for one call:
+
+```python
+from cplugin_webapi_sdk import CPluginWebApiClient
+
+client = CPluginWebApiClient(env="staging", client_id=..., client_secret=..., request_timeout=20)
+
+client.mt4.get_server_time(tp, request_timeout=3)  # one call
+resp = client.mt4.raw(op_module, trade_platform=tp, request_timeout=120)  # any generated operation
+```
+
+The value is sent as the `X-Request-Timeout` header; a value outside 1–300 raises `ValueError` before anything is sent. The HTTP client waits at least 30 s longer than the deadline you set: the server may add up to 20 s for connecting to the trading platform, and the rest covers the network. The server's deadline starts after it has read the request and taken the idempotency key, so on a very slow network or database the client can still give up first — raise `timeout=` for such an environment. Without `request_timeout` the same margin is added to the operation's default deadline from the API reference (60 s for an operation that documents none). The client-wide HTTP timeout (`timeout=`, default 30 s) is the floor and is never shortened.
+
+When the deadline passes, `ApiError` carries the code and the `X-Request-Outcome` header:
+
+| `e.code` | `e.outcome` | What happened | Retry? |
+|---|---|---|---|
+| `Timeout` | `timeout` | A read did not finish. Nothing was changed. | Safe |
+| `Busy` | `not-started` | Too many requests wait for this trading platform; this one was not sent. | Safe |
+| `OutcomeUnknown` | `unknown` | A trade or change did not finish and **may still be applied**. | Check first |
+| `OutcomeUnknown` | `in-progress` | A request with the same `Idempotency-Key` is still running; this one was not executed. | Same key |
+
+`e.applied_timeout` is the deadline the server used (`X-Request-Timeout-Applied`), `e.headers` all response headers. `is_safe_to_retry(e)` and `is_outcome_unknown(e)` (also `e.safe_to_retry` / `e.outcome_unknown`) classify an error; `ErrorCode` and `RequestOutcome` hold the values:
+
+```python
+import uuid
+from cplugin_webapi_sdk import ApiError, is_outcome_unknown, is_safe_to_retry
+
+key = str(uuid.uuid4())  # one key per logical operation, kept across repeats
+try:
+    client.mt4.patch_user_record(tp, login, {"leverage": 200}, idempotency_key=key)
+except ApiError as e:
+    if is_outcome_unknown(e):
+        # * Never repeat blindly — for a trade that means a second trade.
+        #   Repeat with the SAME key: while the first request still runs you get
+        #   OutcomeUnknown / in-progress again; once it has finished you get its
+        #   real result, and it is not executed a second time.
+        ...
+    elif is_safe_to_retry(e):
+        ...  # Timeout or Busy: nothing was applied, repeat when you like
+    else:
+        raise
+```
+
+After `OutcomeUnknown`, repeating with the same key returns the real result for at least one hour after the operation finished on the trading platform. (An answer that arrived in time is kept for the key for one minute.) Without an idempotency key, or when in doubt, check the result yourself (orders, positions, balance, the changed record) before repeating an `OutcomeUnknown` request. If the outcome of a timed-out operation cannot be determined, the server keeps the key taken for one hour; after that, check the outcome and use a new key.
+
+The SDK does not repeat a request because of a timeout or an error code. `retries=` (default 2) only repeats opening the connection, before any byte of the request is sent. With client-credentials auth, a request answered `401` is sent once more with a fresh token; the server refuses an unauthenticated request before running it. An `httpx` transport error (`httpx.ReadTimeout`, a dropped connection) or an `InvalidResponse` error from a proxy page leaves a trade or change just as unknown as `OutcomeUnknown` does — treat it the same way.
+
+Real-time: hub calls addressed to a trading platform, and connecting to a hub, fail after 60 s; streams are not affected.
+
+## Flag fields
+
+User rights, group permissions and symbol flags are strings with the names of the set bits: `"Enabled, Password"`, `"None"` when no bit is set. A bit the API has no name for arrives as `"Bit<n>"` — keep it when you write the value back. The helpers work on that form:
+
+```python
+from cplugin_webapi_sdk import has_flag, with_flag
+
+if not has_flag(user.rights, "Readonly"):
+    user.rights = with_flag(user.rights, "Readonly")  # other bits are kept
+```
+
+`parse_flags` / `format_flags` convert to and from a list of names. The bit values of every flag type are in the OpenAPI spec (`x-enum-varnames`, `x-enum-values`).
+
+## Pagination
+
+Paginated endpoints return `(items, meta)`. Use the built-in helpers to iterate:
+
+```python
+import os
+
+from cplugin_webapi_sdk import CPluginWebApiClient, paginate_sync, collect_all_sync
+
+with CPluginWebApiClient(
+    env="staging",
+    client_id=os.environ["WEBAPI_CLIENT_ID"],
+    client_secret=os.environ["WEBAPI_CLIENT_SECRET"],
+) as client:
+    tp = client.list_trade_platforms()[0]["id"]
+
+    # * Iterate page by page — no full dataset loaded into memory at once.
+    for page in paginate_sync(
+        lambda cur: client.mt4.users_request(tp, cursor=cur, limit=100)
+    ):
+        for user in page:
+            print(user.get("login"), user.get("balance"))
+
+    # * Or collect everything into a single flat list.
+    all_trades = collect_all_sync(
+        lambda cur: client.mt4.trades_request(tp, cursor=cur, limit=200)
+    )
+    print(f"Total open trades: {len(all_trades)}")
+```
+
+Async equivalents: `paginate_async` / `collect_all_async`.
+
+## Real-time / SignalR
+
+Real-time streaming is available via the optional `signalr` extra, which installs the community `signalrcore` library (`pip install "mywebapi-sdk[signalr]"`). The `.realtime` accessor is **EXPERIMENTAL**:
+
+```python
+rt = client.realtime.mt4(trade_platform)   # or client.realtime.mt5(trade_platform)
+rt.start()
+rt.stream_ticks("EURUSD").subscribe({
+    "next": lambda tick: print(tick),
+    "complete": lambda: print("done"),
+    "error": lambda err: print("error:", err),
+})
+...
+rt.stop()
+```
+
+The `mt4` hubs stream ticks, trades, margin-call events, user updates, and symbol config changes; the `mt5` hubs stream connection status and margin-call updates.
+
+> **Note:** The `realtime` namespace requires `signalrcore` to be installed. The REST surface (`mt4`, `mt5`, `list_trade_platforms`) works without it.
+
+## Regenerate
+
+The endpoint layer is generated from the vendored OpenAPI spec `src/cplugin_webapi_sdk/spec/v2.json`:
+
+```bash
+# Install codegen dependencies
+pip install -e ".[codegen]"
+
+# Refresh the vendored spec from staging (main service and x86 sidecar, merged)
+python scripts/fetch_spec.py
+
+# Regenerate the generated client layer
+python scripts/generate_client.py
+```
+
+The regenerated output lands in `src/cplugin_webapi_sdk/_generated/` and is never edited by hand. `generate_client.py` drops the documented default of the `X-Request-Timeout` header before generating, so a generated call sends the header only when a timeout is set, and writes those defaults to `_generated/operation_timeouts.py`, from which the client sizes its HTTP timeout.
+
+## Develop
+
+```bash
+# Run the hermetic unit/contract suite (fast, no network)
+python -m pytest -q
+
+# Run the gated staging E2E (requires live credentials)
+WEBAPI_E2E=1 \
+  WEBAPI_CLIENT_ID=your-id \
+  WEBAPI_CLIENT_SECRET=your-secret \
+  WEBAPI_TRADE_PLATFORM=your-tp-uuid \
+  python -m pytest e2e -q
+```
+
+## Layout
+
+```
+.
+├── src/cplugin_webapi_sdk/
+│   ├── _generated/        # auto-generated endpoint modules and DTOs
+│   ├── spec/v2.json       # vendored OpenAPI spec the generated layer is built from
+│   ├── auth.py            # OAuth2 client credentials + static bearer auth
+│   ├── client.py          # CPluginWebApiClient / CPluginWebApiAsyncClient
+│   ├── discovery.py       # OIDC discovery for the token endpoint
+│   ├── envelope.py        # response envelope Pydantic models
+│   ├── environments.py    # env presets (prod / staging / custom)
+│   ├── errors.py          # ApiError exception type
+│   ├── flags.py           # flag-field helpers
+│   ├── pagination.py      # paginate_sync/async, collect_all_sync/async
+│   ├── realtime.py        # experimental SignalR clients
+│   ├── timeouts.py        # request timeouts, error codes, retry classification
+│   └── unwrap.py          # envelope unwrap helpers
+├── examples/
+│   └── 01_hello.py        # runnable quickstart
+├── e2e/
+│   └── test_e2e.py        # gated staging E2E test
+├── tests/                 # hermetic unit and contract tests
+└── scripts/               # fetch_spec.py, generate_client.py
+```
+
+---
+
+MetaTrader, MT4, MT5, and MetaQuotes are trademarks or registered trademarks of MetaQuotes Ltd. This project is not affiliated with, endorsed by, or sponsored by MetaQuotes Ltd.

mywebapi_sdk-0.3.0/PUBLISHING.md

@@ -0,0 +1,62 @@
+# Publishing
+
+## Before the first release
+
+1. **Distribution name** — `mywebapi-sdk` (final). PyPI names are a global,
+   first-come namespace, so verify it is still free
+   (https://pypi.org/project/mywebapi-sdk/) just before the first release.
+   The import name stays `cplugin_webapi_sdk` regardless.
+2. **Repository** — `CPlugin/mywebapi.com-sdk-py` (final, mirrors the JS SDK
+   `CPlugin/mywebapi.com-sdk-js`). The URLs are set in `pyproject.toml`
+   (`[project.urls]`) and `.github/workflows/publish.yml` (`environment.url`).
+3. **Authentication: PyPI Trusted Publishing (OIDC) — no token to store or rotate.**
+   - Unlike npm, PyPI supports a **pending publisher**, so you do NOT need a
+     bootstrap-token first publish. On https://pypi.org, go to your account
+     (or the project, once it exists) → _Publishing → Add a new pending publisher_
+     and set: PyPI project name = `mywebapi-sdk`, Owner = `<github-org>`,
+     Repository = `<repo>`, Workflow = `publish.yml`, Environment = `pypi`.
+   - Create a GitHub **Environment** named `pypi` (Settings → Environments) and,
+     optionally, add protection rules (required reviewers, restrict to tags).
+   - Every release then publishes via the workflow's OIDC id-token — **no
+     `PYPI_TOKEN` secret, nothing to rotate.**
+   - (TestPyPI: mirror the same setup at https://test.pypi.org and point the
+     publish action at it with `repository-url` to rehearse before going live.)
+
+## Releasing a version
+
+1. Bump `version` in `pyproject.toml` following [semver](https://semver.org/)
+   and add a section for it to `CHANGELOG.md`.
+2. Open a pull request to `main` with the change and the version bump, and merge it once CI is green — `main` accepts changes only through a pull request with passing CI.
+3. Tag the commit and push the tag — the tag must equal `v` + the `pyproject.toml` version:
+   ```sh
+   git tag v0.3.0
+   git push origin v0.3.0
+   ```
+4. The `publish.yml` workflow triggers automatically, builds the sdist + wheel,
+   runs `twine check`, and publishes to PyPI via OIDC trusted publishing.
+
+## Building locally (sanity check)
+
+```sh
+python -m pip install --upgrade build twine
+python -m build          # writes dist/*.whl + dist/*.tar.gz
+python -m twine check dist/*
+```
+
+## Regenerating the client from a new spec
+
+The endpoint layer under `src/cplugin_webapi_sdk/_generated/` is generated from the
+canonical OpenAPI spec. To regenerate:
+
+```sh
+python -m pip install -e ".[codegen]"
+python scripts/fetch_spec.py        # refresh the vendored src/cplugin_webapi_sdk/spec/v2.json
+python scripts/generate_client.py   # rewrite _generated/ from the vendored spec
+python -m pytest -q                 # verify nothing broke
+```
+
+## Release gate
+
+- Only repository admins can create `v*` tags; nobody can move or delete one (repository rulesets), so a published version always points at the commit it was built from.
+- `main` accepts changes only through a pull request whose CI passed. Merging that pull request is the review of what will be released.
+- The first job of `publish.yml` (`Release gate`) refuses a tag whose commit is not on `main` or has no successful CI run; nothing is built or published then. Fix it by merging the commit into `main` and tagging the merged commit — a refused tag cannot be moved, so the next version number is used.