PipSync SDK

Official, hand-written SDKs for the documented PipSync v1 read API and report schedule creation. This repository contains dependency-light clients for Node.js/TypeScript and Python, plus webhook signature verification helpers.

The SDK deliberately does not expose signal ingest, order placement, broker credentials, or any trade-execution operation.

Safety defaults

• The default base URL is http://127.0.0.1:4010/api/v1, intended for the PipSync mock server. Production must be selected explicitly.
• API keys must be passed explicitly. Neither client reads environment variables.
• Remote URLs must use HTTPS. Plain HTTP is accepted only for loopback hosts.
• Safe GET requests retry rate limits, selected 5xx responses, and transport failures with bounded backoff. POST /reports/schedules is never retried automatically because duplicate creation is not known to be idempotent.
• Successful JSON responses are validated at runtime. Fields that the OpenAPI snapshot does not require remain optional; when present, known fields must match their documented type and enum. The SDK never invents business values for omitted response fields.
• Webhooks are verified against the exact raw bytes, with a five-minute default timestamp tolerance and an optional durable replay-claim callback.

Supported API surface

SDK method	HTTP operation	Auth
health	GET /health	No
getMe / get_me	GET /me	Yes
listSignals / list_signals	GET /signals	Yes
listTrades / list_trades	GET /trades	Yes
listReports / list_reports	GET /reports	Yes
getTradeReport / get_trade_report	GET /reports/trades?format=json	Yes
downloadTradeReport / download_trade_report	GET /reports/trades?format=csv|pdf	Yes
listReportSchedules / list_report_schedules	GET /reports/schedules	Yes
createReportSchedule / create_report_schedule	POST /reports/schedules	Yes
getAccountUsage / get_account_usage	GET /account/usage	Yes

Node.js / TypeScript

Requires Node.js 20 or newer. Until the first npm registry publication, install from a checked-out source package:

git clone https://github.com/pipsyncio/pipsync-sdk.git
cd pipsync-sdk
npm ci
npm run build
mkdir -p ../artifacts
npm pack --pack-destination ../artifacts
# In the consuming project:
npm install ../artifacts/pipsync-sdk-0.1.0.tgz

After the first npm registry publication, npm install @pipsync/sdk will be the shorter equivalent.

import { PipSyncClient } from "@pipsync/sdk";

const client = new PipSyncClient({
  apiKey: "replace_with_your_api_key",
  baseUrl: "https://app.pipsync.io/api/v1",
});

const page = await client.listSignals({ limit: 20 });
for (const signal of page.data ?? []) {
  console.log(signal.instrument, signal.direction);
}

Create a report schedule explicitly:

const created = await client.createReportSchedule({
  frequency: "weekly",
  format: "pdf",
  targetEmail: "reports@example.com",
  timezone: "Europe/Berlin",
});

console.log(created.data?.id);

Treat an uncertain response from this POST as an unknown outcome: query listReportSchedules() before trying again.

Python

Requires Python 3.10 or newer and has no runtime dependencies. Until the first PyPI publication, install from the checked-out source tree:

git clone https://github.com/pipsyncio/pipsync-sdk.git
python -m pip install ./pipsync-sdk/python

After the first PyPI publication, python -m pip install pipsync-sdk will be the shorter equivalent.

from pipsync import PipSyncClient

client = PipSyncClient(
    api_key="replace_with_your_api_key",
    base_url="https://app.pipsync.io/api/v1",
)

for signal in client.list_signals(limit=20).data or ():
    print(signal.instrument, signal.direction)

from pipsync import CreateReportSchedule

created = client.create_report_schedule(
    CreateReportSchedule(
        frequency="weekly",
        format="pdf",
        target_email="reports@example.com",
        timezone="Europe/Berlin",
    )
)
print(created.data.id if created.data else None)

Webhook verification

PipSync sends X-PipSync-Signature in the form t=<unix-seconds>,v1=<hex-hmac-sha256>. The signed message is <timestamp>.<exact raw body>. Never parse, trim, or re-serialize the body before verification.

Node.js:

import { verifyWebhook } from "@pipsync/sdk";

const verified = await verifyWebhook(rawBody, signatureHeader, webhookSecret, {
  toleranceSeconds: 300,
  claimReplayKey: async (key, timestamp) => {
    // Atomically insert `key` into durable storage with a unique constraint.
    // Return false if another process already claimed it.
    return replayStore.claim(key, timestamp);
  },
});

Python:

from pipsync import verify_webhook

verified = verify_webhook(
    raw_body,
    signature_header,
    webhook_secret,
    tolerance_seconds=300,
    claim_replay_key=lambda key, timestamp: replay_store.claim(key, timestamp),
)

The replay hook receives a stable opaque digest and runs only after timestamp and signature verification. An in-memory set is useful in tests but is not durable protection across processes or restarts.

Pagination helpers

The currently documented list responses are bounded but do not publish a universal cursor. paginate/collectPages and iter_pages/collect_pages therefore require the caller to provide the continuation state instead of inventing unsupported query parameters. Both helpers stop after 100 pages by default.

Errors and rate limits

Both SDKs expose typed configuration, authentication, permission, validation, rate-limit, response, transport, and generic API errors. API errors include the HTTP status, RFC 7807 problem details when available, X-Request-ID, and Retry-After information. The latest rate-limit headers are available as client.lastRateLimit in Node.js and client.last_rate_limit in Python.

A valid server Retry-After is honored exactly, even when it exceeds the client's exponential-backoff cap. To avoid an unbounded wait, the clients default to a five-minute safety ceiling (maxRetryAfterMs in Node.js, max_retry_after in Python). A longer or malformed value causes the current request to fail with its typed API error without an early retry. The retryMaxDelayMs / retry_max_delay settings apply only to client-computed exponential backoff.

Do not log API keys, webhook secrets, signature headers, or full sensitive payloads when handling an error.

Local development

Node.js:

npm ci
npm run test:all
npm pack --dry-run

Python:

PYTHONPATH=python/src python -m unittest discover -s python/tests -v
python -m pip install ./python

All tests use synthetic fixtures and local fake transports. They never contact the production API.

Versioning and support

This project follows Semantic Versioning. 0.x releases may refine model names as the public API stabilizes, while endpoint safety boundaries remain explicit. See CHANGELOG.md, SECURITY.md, and CONTRIBUTING.md.

Continue with PipSync

The SDK can be evaluated entirely with local fake transports. When you need a scoped hosted API key and the current production contract, follow the PipSync API quickstart.

Licensed under Apache-2.0. See LICENSE.