feat: SDK gap-fill — mirror of TS PR #21 (order history + USD valuation + combined transfers + get_deployment filters + error preservation)

[hsyndeniz]

Python parity port of dexalot-sdk-typescript#21. 7 commits, 954 unit tests pass, 100% coverage, mypy strict + ruff clean.

[ngurmen]

Implementation spec: reconcile feat/sdk-gap-fill (Python ↔ TypeScript)

Background & canonical decisions

The 5 gap-fill methods are net-new on both feat/sdk-gap-fill branches and absent
from both mains. The two SDKs implemented the same endpoints with different public
shapes. Align both to the canonical shapes below. Do this before either branch
merges/releases — post-release these become breaking changes.

Decision	Canonical
getCombinedTransfers params	symbol, fromTs/from_ts & toTs/to_ts (unix-seconds int), limit/offset; translate to backend itemsperpage/pageno/periodfrom/periodto internally
Transfer timestamps	sourceTs/source_ts: unix-seconds int (non-null); targetTs/target_ts: unix-seconds int or null
Transfer target legs	targetEnv/targetChainId/targetTx (+ target_ts) are null when the transfer never crosses chains — never 0/"" sentinels
getOrderHistory pair filter	validate and normalize before sending

Rationale for the coder: unix-int timestamps match PricePoint (which is already
unix-int on both SDKs) and fix a TS internal inconsistency (PricePoint.timestamp: number vs Transfer.sourceTs: string). Nullability comes from TS — null for a
non-crossing leg is real signal that Python's 0/"" sentinels destroy.

---

Repo A — TypeScript (dexalot-sdk-typescript) — most of the work is here

A1. getCombinedTransfers → ergonomic params (src/core/transfer.ts)

Current signature exposes raw backend params. Change to:

public async getCombinedTransfers(opts?: {
    symbol?: string;
    fromTs?: number;   // unix seconds
    toTs?: number;     // unix seconds
    limit?: number;
    offset?: number;
}): Promise<Result<Transfer[]>>

In the body, after resolving address:

• const itemsperpage = Math.max(1, opts?.limit ?? 100);
• const pageno = Math.floor((opts?.offset ?? 0) / itemsperpage) + 1;
• const symbol = opts?.symbol ? this.normalizeToken(opts.symbol) : undefined;
• Forward to the backend as params.periodfrom = opts?.fromTs and
  params.periodto = opts?.toTs (only when defined).
• Build the cache key from the translated values (address +
  itemsperpage/pageno/symbol/periodfrom/periodto) so equivalent
  limit/offset combinations that map to the same page share a slot
  (matches Python).
• Update the method's JSDoc: document symbol/fromTs/toTs/limit/offset,
  and that limit/offset are translated to itemsperpage/pageno internally
  and fromTs/toTs to periodfrom/periodto.

A2. Transfer timestamps → unix seconds (src/types/index.ts + src/core/transfer.ts)

In src/types/index.ts, change the Transfer interface:

• sourceTs: number; (was string) — "Source-leg time as unix seconds (UTC)."
• targetTs: number | null; (was string | null)
• Update the surrounding doc comment that currently says the timestamps are ISO strings.

In src/core/transfer.ts _normalizeTransfer, add a small private helper and use it:

/** ISO-8601 string OR numeric/numeric-string → unix seconds (UTC), or null. */
private _coerceTransferTs(raw: unknown): number | null {
    if (typeof raw === 'string' && raw.trim() !== '') {
        const parsed = Date.parse(raw);
        if (Number.isFinite(parsed)) return Math.floor(parsed / 1000);
    }
    return this._coerceTimestampSeconds(raw);
}

Then:

• const sourceTs = this._coerceTransferTs(r.source_ts) ?? 0; (source always present; 0 fallback keeps it non-null)
• const targetTs = this._coerceTransferTs(r.target_ts); (null when absent — targetEnv/targetChainId/targetTx are already nullable in TS, leave them)

A3. getOrderHistory pair normalization (src/core/clob.ts)

After the existing validatePairFormat(opts.pair, 'pair') check, normalize before
sending. BaseClient.normalizePair() exists (src/core/base.ts:1137). Set
params.pair = this.normalizePair(opts.pair) instead of forwarding the raw
opts.pair.

A4. TS tests (tests/unit/transfer.test.ts, tests/unit/clob.test.ts)

• getCombinedTransfers tests: switch any { itemsperpage, pageno, periodfrom, periodto } call sites to { limit, offset, fromTs, toTs, symbol }; add a test
  asserting the limit/offset → itemsperpage/pageno translation (e.g.
  limit: 50, offset: 100 ⇒ itemsperpage=50, pageno=3) and that fromTs/toTs
  go out as periodfrom/periodto.
• Transfer normalization tests: assert sourceTs/targetTs are numbers (unix
  seconds) and that a row with no target leg yields targetTs === null (alongside
  the already-null targetEnv/targetChainId/targetTx).
• getOrderHistory: add a test asserting a lowercase/alias pair is normalized in
  the outgoing params.pair.

A5. TS docs (README.md)

Update the getCombinedTransfers signature/param table and the Transfer field
descriptions (timestamps now unix-seconds numbers; target legs nullable).

---

Repo B — Python (dexalot-sdk-python) — small changes

B1. Rename kind → symbol (src/dexalot_sdk/core/transfer.py, get_combined_transfers, ~line 2160)

• Signature: kind: str | None = None → symbol: str | None = None.
• Body (~line 2212): if symbol is not None: normalized_symbol = self._normalize_user_token(symbol).
• Docstring: rename the kind: arg to symbol: and update the cache-key tuple line
  (address, kind, ...) → (address, symbol, ...).

B2. Nullable target legs (src/dexalot_sdk/core/transfer.py)

Transfer dataclass (~lines 98-101): change field types to

target_env: str | None
target_chain_id: int | None
target_tx: str | None
target_ts: int | None

Add a one-line doc note that target_* is None for non-crossing transfers.

In _normalize_transfer (~lines 2124-2137): emit None instead of sentinels —

• target_env = target_env_raw if isinstance(target_env_raw, str) else None
• target_chain_id = ... else None (keep the bool-exclusion guard)
• target_tx = target_tx_raw if isinstance(target_tx_raw, str) else None
• target_ts = self._coerce_timestamp_seconds(raw.get("target_ts")) (drop the or 0)
• Leave source_ts = self._coerce_timestamp_seconds(raw.get("source_ts")) or 0 unchanged (source is non-null).

B3. Python tests (tests/unit/core/test_transfer.py)

• Update the three kind= call sites (lines ~3013, ~3063, ~3086) to symbol=.
• Add a test for a row with omitted/null target_* fields asserting target_ts is None, target_env is None, target_chain_id is None, target_tx is None. The
  existing full-row test (lines ~2780-2818) still passes unchanged.

B4. Python docs (README.md, CLAUDE.md if it documents the field shape)

Update the get_combined_transfers param name (kind→symbol) and the Transfer
field nullability note.

---

Gates (run in each repo before requesting review)

Python: make test · make lint · make mypy (all three must pass — mypy
strict will catch any missed | None propagation).

TypeScript: pnpm exec tsc --noEmit -p tsconfig.build.json · pnpm exec jest --ci tests/unit · pnpm audit --audit-level=high. (Ignore the whole-project pnpm typecheck — it has 48 pre-existing test-file errors on main and is not a CI gate.)