@sentico-labs/sdk 0.1.0-preview.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0-preview.1
+
+- Converts the SDK into a publishable preview package.
+- Adds `SenticoreClient` with explicit `public`, `trading`, `orderEntry`, `raw`, and `ws` planes.
+- Adds typed `ApiResponse`, rate-limit metadata, request-id propagation, timeouts, and retries.
+- Adds typed API errors for auth, validation, conflict, rate-limit, payload-too-large, and server failures.
+- Adds Institutional Order Entry batch encoding for the current cold JSON payload over
+  `application/x-senticore-order-entry-batch`.
+- Keeps `client.mm`, `mmApiKey`, and `SenticoreMarketMakerClient` as deprecated compatibility aliases.
+- Keeps legacy `SenticoreHttpClient` and `SenticoreWsClient` exports for existing examples.
+- Adds Node test coverage and npm packaging verification.

package/README.md

@@ -0,0 +1,190 @@
+# Senticore TypeScript SDK
+
+Official TypeScript SDK preview for Senticore HTTP, WebSocket, and
+Institutional Order Entry.
+
+Package name: `@sentico-labs/sdk`
+Preview version: `0.1.0-preview.1`
+
+## Install
+
+```bash
+npm install @sentico-labs/sdk@0.1.0-preview.1
+```
+
+For local development from the repository:
+
+```bash
+npm ci
+npm run verify
+```
+
+## Quick Start
+
+```ts
+import { SenticoreClient } from "@sentico-labs/sdk";
+
+const client = new SenticoreClient({
+  publicHttpBaseUrl: "https://api.sentico-labs.xyz",
+  tradingHttpBaseUrl: "https://api.sentico-labs.xyz",
+  publicWsUrl: "wss://api.sentico-labs.xyz/api/v1/ws/public",
+  privateWsUrl: "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}",
+  orderEntryHttpBaseUrl: "https://api.sentico-labs.xyz",
+  orderEntryBinaryPath: "/api/order-entry/binary",
+  bearerToken: process.env.SENTICORE_BEARER_TOKEN,
+  orderEntryApiKey: process.env.SENTICORE_ORDER_ENTRY_API_KEY
+});
+
+const markets = await client.public.listMarkets();
+console.log(markets.data, markets.requestId, markets.rateLimit);
+```
+
+## Client Planes
+
+- `client.public`: anonymous public HTTP reads.
+- `client.trading`: authenticated private reads and trading writes.
+- `client.orderEntry`: Institutional Order Entry.
+- `client.mm`: deprecated alias for `client.orderEntry`.
+- `client.raw`: escape hatch for endpoints not promoted to stable helpers yet.
+- `client.ws`: public and private WebSocket helpers.
+
+Legacy `SenticoreHttpClient` and `SenticoreWsClient` exports are still present
+for existing integrations. New integrations should use `SenticoreClient`.
+
+## Public Market Data
+
+```ts
+const markets = await client.public.listMarkets();
+const book = await client.public.getMarketOrderbook(1, { book: "YES", depth: 20 });
+const trades = await client.public.listMarketTrades(1, { limit: 50 });
+```
+
+## Trading HTTP
+
+```ts
+const account = "0x00000000000000000000000000000000000000d3";
+const nonce = await client.trading.reserveNonce(account, {
+  count: 1,
+  ttlMs: 30_000,
+  idempotencyKey: "nonce-1"
+});
+
+const signedAction = {
+  payload: {
+    account,
+    nonce: nonce.data.startNonce,
+    nonceReservationId: nonce.data.reservationId,
+    ts: Date.now(),
+    action: {
+      PlaceOrder: {
+        market: 1,
+        book: "YES",
+        side: "Bid",
+        price: 500000,
+        qty: 100000,
+        is_market: false,
+        reduce_only: false,
+        time_in_force: null,
+        expires_at: null,
+        stp_mode: null
+      }
+    }
+  },
+  signature: {
+    scheme: "EcdsaSecp256k1",
+    bytes: new Uint8Array(65)
+  }
+};
+
+const accepted = await client.trading.submitSignedAction(signedAction, {
+  idempotencyKey: "client-order-1"
+});
+console.log(accepted.data);
+```
+
+## Institutional Order Entry
+
+The current Senticore cold binary path uses compact JSON bytes on the wire:
+
+```json
+{"version":1,"actions":[...],"idempotencyKey":"..."}
+```
+
+The SDK sends this payload with
+`Content-Type: application/x-senticore-order-entry-batch` and
+`X-Senticore-Order-Entry-Key`.
+
+The canonical private-beta endpoint is `POST /api/order-entry/binary`. The live
+edge maps that alias to the trading plane's `/api/v1/mm/orders/batch.bin`
+handler. If you connect directly to a trading-plane service without the edge
+alias, set `orderEntryBinaryPath: "/api/v1/mm/orders/batch.bin"`.
+
+```ts
+const response = await client.orderEntry.submitActions([signedAction], {
+  idempotencyKey: "order-entry-batch-1",
+  responseMode: "summary"
+});
+
+console.log(response.data.ok, response.data.seqs, response.data.ackMode);
+```
+
+Low-latency clients that already produce venue payload bytes can call:
+
+```ts
+await client.orderEntry.submitEncoded(encodedPayload, {
+  idempotencyKey: "order-entry-raw-1"
+});
+```
+
+## WebSocket
+
+```ts
+const socket = client.ws.connectPublic((frame) => {
+  console.log(frame);
+});
+
+socket.addEventListener("open", () => {
+  client.ws.subscribe(socket, {
+    type: "l2Book",
+    marketId: 1,
+    depth: 20
+  });
+});
+```
+
+Private user streams:
+
+```ts
+const token = await client.trading.issuePrivateWsToken(account, {
+  ttlMs: 60_000
+});
+
+const socket = client.ws.connectPrivate(account, token.data.token, (frame) => {
+  console.log(frame);
+});
+```
+
+Replay gaps raise `ReplayGapError` during frame parsing. Production clients
+should resync from an HTTP snapshot and resubscribe from a known sequence.
+
+## Error Handling
+
+```ts
+import { RateLimitError, SenticoreApiError } from "@sentico-labs/sdk";
+
+try {
+  await client.public.listMarkets();
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    console.log("retry after", error.retryAfter);
+  } else if (error instanceof SenticoreApiError) {
+    console.log(error.status, error.requestId, error.payload);
+  }
+}
+```
+
+## Preview Compatibility
+
+`0.1.0-preview.1` is not a v1 stability promise. The stable preview shape is the
+top-level namespace split: `public`, `trading`, `orderEntry`, `raw`, and `ws`.
+`mm` remains as a deprecated compatibility alias.

package/dist/examples/market-maker-batch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/market-maker-batch.js

@@ -0,0 +1,35 @@
+import { SenticoreClient } from "../src/index.js";
+const account = process.env.SENTICORE_ACCOUNT;
+const client = new SenticoreClient({
+    publicHttpBaseUrl: process.env.SENTICORE_PUBLIC_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    tradingHttpBaseUrl: process.env.SENTICORE_TRADING_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    publicWsUrl: process.env.SENTICORE_PUBLIC_WS_URL ?? "wss://api.sentico-labs.xyz/api/v1/ws/public",
+    privateWsUrl: process.env.SENTICORE_PRIVATE_WS_URL ??
+        "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}",
+    orderEntryHttpBaseUrl: process.env.SENTICORE_ORDER_ENTRY_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    orderEntryBinaryPath: process.env.SENTICORE_ORDER_ENTRY_BINARY_PATH ?? "/api/order-entry/binary",
+    orderEntryApiKey: process.env.SENTICORE_ORDER_ENTRY_API_KEY ?? process.env.SENTICORE_MM_API_KEY
+});
+const action = {
+    payload: {
+        account,
+        nonce: Number(process.env.SENTICORE_NONCE ?? "0"),
+        nonceReservationId: null,
+        ts: Date.now(),
+        action: {
+            Cancel: {
+                order_id: process.env.SENTICORE_ORDER_ID ??
+                    "0x0101010101010101010101010101010101010101010101010101010101010101"
+            }
+        }
+    },
+    signature: {
+        scheme: "EcdsaSecp256k1",
+        bytes: new Uint8Array(65)
+    }
+};
+const response = await client.orderEntry.submitActions([action], {
+    idempotencyKey: `order-entry-${Date.now()}`,
+    responseMode: "summary"
+});
+console.log(response.data);

package/dist/examples/private-user-stream.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/private-user-stream.js

@@ -0,0 +1,21 @@
+import { SenticoreClient } from "../src/index.js";
+const account = process.env.SENTICORE_ACCOUNT;
+const client = new SenticoreClient({
+    publicHttpBaseUrl: process.env.SENTICORE_PUBLIC_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    tradingHttpBaseUrl: process.env.SENTICORE_TRADING_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    publicWsUrl: process.env.SENTICORE_PUBLIC_WS_URL ?? "wss://api.sentico-labs.xyz/api/v1/ws/public",
+    privateWsUrl: process.env.SENTICORE_PRIVATE_WS_URL ??
+        "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}",
+    bearerToken: process.env.SENTICORE_BEARER_TOKEN
+});
+const token = await client.trading.issuePrivateWsToken(account, {
+    ttlMs: 120_000,
+    clientId: "algo-desk-1"
+});
+const socket = client.ws.connectPrivate(account, token.data.token, (frame) => {
+    console.log("private frame", frame);
+});
+socket.addEventListener("open", () => {
+    client.ws.subscribe(socket, { type: "account" });
+    client.ws.subscribe(socket, { type: "userFills" });
+});

package/dist/examples/public-market-stream.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/public-market-stream.js

@@ -0,0 +1,18 @@
+import { SenticoreClient } from "../src/index.js";
+const client = new SenticoreClient({
+    publicHttpBaseUrl: process.env.SENTICORE_PUBLIC_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    tradingHttpBaseUrl: process.env.SENTICORE_TRADING_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    publicWsUrl: process.env.SENTICORE_PUBLIC_WS_URL ?? "wss://api.sentico-labs.xyz/api/v1/ws/public",
+    privateWsUrl: process.env.SENTICORE_PRIVATE_WS_URL ??
+        "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}"
+});
+const socket = client.ws.connectPublic((frame) => {
+    console.log("public frame", frame);
+});
+socket.addEventListener("open", () => {
+    client.ws.subscribe(socket, {
+        type: "marketSnapshot",
+        marketId: 1,
+        cursor: 0
+    });
+});

package/dist/examples/recover-from-gap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/recover-from-gap.js

@@ -0,0 +1,35 @@
+import { ReplayGapError, SenticoreClient } from "../src/index.js";
+const client = new SenticoreClient({
+    publicHttpBaseUrl: process.env.SENTICORE_PUBLIC_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    tradingHttpBaseUrl: process.env.SENTICORE_TRADING_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    publicWsUrl: process.env.SENTICORE_PUBLIC_WS_URL ?? "wss://api.sentico-labs.xyz/api/v1/ws/public",
+    privateWsUrl: process.env.SENTICORE_PRIVATE_WS_URL ??
+        "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}"
+});
+let lastCursor = 0;
+function handle(frame) {
+    if (typeof frame.seq === "number") {
+        lastCursor = frame.seq;
+    }
+    console.log(frame);
+}
+const socket = client.ws.connectPublic((frame) => {
+    try {
+        handle(frame);
+    }
+    catch (error) {
+        if (error instanceof ReplayGapError) {
+            void client.public.getMarketSnapshot(1, { depth: 20 }).then((snapshot) => {
+                console.log("resynced snapshot", snapshot.data);
+                lastCursor = 0;
+            });
+        }
+    }
+});
+socket.addEventListener("open", () => {
+    client.ws.subscribe(socket, {
+        type: "marketSnapshot",
+        marketId: 1,
+        cursor: lastCursor
+    });
+});

package/dist/examples/submit-order.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/submit-order.js

@@ -0,0 +1,45 @@
+import { SenticoreClient } from "../src/index.js";
+const account = process.env.SENTICORE_ACCOUNT;
+const client = new SenticoreClient({
+    publicHttpBaseUrl: process.env.SENTICORE_PUBLIC_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    tradingHttpBaseUrl: process.env.SENTICORE_TRADING_HTTP_URL ?? "https://api.sentico-labs.xyz",
+    publicWsUrl: process.env.SENTICORE_PUBLIC_WS_URL ?? "wss://api.sentico-labs.xyz/api/v1/ws/public",
+    privateWsUrl: process.env.SENTICORE_PRIVATE_WS_URL ??
+        "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}",
+    bearerToken: process.env.SENTICORE_BEARER_TOKEN
+});
+const nonce = await client.trading.reserveNonce(account, {
+    count: 1,
+    ttlMs: 30_000,
+    idempotencyKey: `nonce-${Date.now()}`
+});
+const signedAction = {
+    payload: {
+        account,
+        nonce: Number(nonce.data.startNonce),
+        nonceReservationId: nonce.data.reservationId,
+        ts: Date.now(),
+        action: {
+            PlaceOrder: {
+                market: 1,
+                book: "YES",
+                side: "Bid",
+                price: 500000,
+                qty: 100000,
+                is_market: false,
+                reduce_only: false,
+                time_in_force: null,
+                expires_at: null,
+                stp_mode: null
+            }
+        }
+    },
+    signature: {
+        scheme: "EcdsaSecp256k1",
+        bytes: new Uint8Array(65)
+    }
+};
+const response = await client.trading.submitSignedAction(signedAction, {
+    idempotencyKey: `order-${Date.now()}`
+});
+console.log(response.data);

package/dist/src/client.d.ts

@@ -0,0 +1,15 @@
+import { SenticorePublicHttpClient, SenticoreRawHttpClient, SenticoreTradingHttpClient } from "./http.js";
+import { SenticoreOrderEntryClient } from "./mm.js";
+import type { NormalizedSenticoreSdkConfig, SenticoreSdkConfig } from "./types.js";
+import { SenticoreWsClient } from "./ws.js";
+export declare class SenticoreClient {
+    readonly config: NormalizedSenticoreSdkConfig;
+    readonly public: SenticorePublicHttpClient;
+    readonly trading: SenticoreTradingHttpClient;
+    readonly orderEntry: SenticoreOrderEntryClient;
+    /** @deprecated Use orderEntry. */
+    readonly mm: SenticoreOrderEntryClient;
+    readonly raw: SenticoreRawHttpClient;
+    readonly ws: SenticoreWsClient;
+    constructor(config: SenticoreSdkConfig);
+}

package/dist/src/client.js

@@ -0,0 +1,24 @@
+import { normalizeConfig } from "./config.js";
+import { SenticoreHttpTransport, SenticorePublicHttpClient, SenticoreRawHttpClient, SenticoreTradingHttpClient } from "./http.js";
+import { SenticoreOrderEntryClient } from "./mm.js";
+import { SenticoreWsClient } from "./ws.js";
+export class SenticoreClient {
+    config;
+    public;
+    trading;
+    orderEntry;
+    /** @deprecated Use orderEntry. */
+    mm;
+    raw;
+    ws;
+    constructor(config) {
+        this.config = normalizeConfig(config);
+        const transport = new SenticoreHttpTransport(this.config);
+        this.public = new SenticorePublicHttpClient(transport);
+        this.trading = new SenticoreTradingHttpClient(transport);
+        this.orderEntry = new SenticoreOrderEntryClient(transport);
+        this.mm = this.orderEntry;
+        this.raw = new SenticoreRawHttpClient(transport);
+        this.ws = new SenticoreWsClient(this.config);
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedSenticoreSdkConfig, SenticoreSdkConfig } from "./types.js";
+export declare function normalizeConfig(config: SenticoreSdkConfig): NormalizedSenticoreSdkConfig;

package/dist/src/config.js

@@ -0,0 +1,41 @@
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_BACKOFF_MS = 250;
+const DEFAULT_ORDER_ENTRY_BINARY_PATH = "/api/order-entry/binary";
+const DEFAULT_USER_AGENT = "@sentico-labs/sdk/0.1.0-preview.1";
+export function normalizeConfig(config) {
+    const fetchImpl = config.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!fetchImpl) {
+        throw new Error("Senticore SDK requires fetch or config.fetch");
+    }
+    const WebSocketCtor = config.WebSocketCtor ?? globalThis.WebSocket;
+    const orderEntryHttpBaseUrl = trimTrailingSlash(config.orderEntryHttpBaseUrl ?? config.mmHttpBaseUrl ?? config.tradingHttpBaseUrl);
+    const orderEntryBinaryPath = normalizePath(config.orderEntryBinaryPath ?? config.mmBinaryPath ?? DEFAULT_ORDER_ENTRY_BINARY_PATH);
+    const orderEntryApiKey = config.orderEntryApiKey ?? config.mmApiKey;
+    return {
+        publicHttpBaseUrl: trimTrailingSlash(config.publicHttpBaseUrl),
+        tradingHttpBaseUrl: trimTrailingSlash(config.tradingHttpBaseUrl),
+        publicWsUrl: config.publicWsUrl,
+        privateWsUrl: config.privateWsUrl,
+        orderEntryHttpBaseUrl,
+        orderEntryBinaryPath,
+        orderEntryApiKey,
+        mmHttpBaseUrl: orderEntryHttpBaseUrl,
+        mmBinaryPath: orderEntryBinaryPath,
+        bearerToken: config.bearerToken,
+        mmApiKey: orderEntryApiKey,
+        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+        retryBackoffMs: config.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS,
+        userAgent: config.userAgent ?? DEFAULT_USER_AGENT,
+        headers: config.headers ?? {},
+        fetch: fetchImpl,
+        WebSocketCtor
+    };
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function normalizePath(path) {
+    return path.startsWith("/") ? path : `/${path}`;
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,38 @@
+export declare class SenticoreError extends Error {
+    constructor(message: string);
+}
+export declare class TransportError extends SenticoreError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class ReplayGapError extends SenticoreError {
+    readonly frame?: unknown;
+    constructor(message: string, frame?: unknown);
+}
+export declare class SenticoreApiError extends SenticoreError {
+    readonly status: number;
+    readonly payload: unknown;
+    readonly headers: Headers;
+    readonly requestId?: string | undefined;
+    constructor(message: string, status: number, payload: unknown, headers: Headers, requestId?: string | undefined);
+}
+export declare class AuthenticationError extends SenticoreApiError {
+}
+export declare class PermissionDeniedError extends SenticoreApiError {
+}
+export declare class NotFoundError extends SenticoreApiError {
+}
+export declare class ConflictError extends SenticoreApiError {
+}
+export declare class ValidationError extends SenticoreApiError {
+}
+export declare class PayloadTooLargeError extends SenticoreApiError {
+}
+export declare class ServerError extends SenticoreApiError {
+}
+export declare class RateLimitError extends SenticoreApiError {
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, status: number, payload: unknown, headers: Headers, requestId?: string, retryAfter?: number | undefined);
+}
+export declare function requestIdFromHeaders(headers: Headers): string | undefined;
+export declare function apiErrorFromStatus(response: Response, payload: unknown): SenticoreApiError;

package/dist/src/errors.js

@@ -0,0 +1,106 @@
+export class SenticoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class TransportError extends SenticoreError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+export class ReplayGapError extends SenticoreError {
+    frame;
+    constructor(message, frame) {
+        super(message);
+        this.frame = frame;
+    }
+}
+export class SenticoreApiError extends SenticoreError {
+    status;
+    payload;
+    headers;
+    requestId;
+    constructor(message, status, payload, headers, requestId) {
+        super(message);
+        this.status = status;
+        this.payload = payload;
+        this.headers = headers;
+        this.requestId = requestId;
+    }
+}
+export class AuthenticationError extends SenticoreApiError {
+}
+export class PermissionDeniedError extends SenticoreApiError {
+}
+export class NotFoundError extends SenticoreApiError {
+}
+export class ConflictError extends SenticoreApiError {
+}
+export class ValidationError extends SenticoreApiError {
+}
+export class PayloadTooLargeError extends SenticoreApiError {
+}
+export class ServerError extends SenticoreApiError {
+}
+export class RateLimitError extends SenticoreApiError {
+    retryAfter;
+    constructor(message, status, payload, headers, requestId, retryAfter) {
+        super(message, status, payload, headers, requestId);
+        this.retryAfter = retryAfter;
+    }
+}
+export function requestIdFromHeaders(headers) {
+    return (headers.get("x-request-id") ??
+        headers.get("x-correlation-id") ??
+        headers.get("x-senticore-request-id") ??
+        undefined);
+}
+export function apiErrorFromStatus(response, payload) {
+    const requestId = requestIdFromHeaders(response.headers);
+    const message = messageFromPayload(response.status, payload);
+    if (response.status === 401) {
+        return new AuthenticationError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 403) {
+        return new PermissionDeniedError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 404) {
+        return new NotFoundError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 409) {
+        return new ConflictError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 400 || response.status === 422) {
+        return new ValidationError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 413) {
+        return new PayloadTooLargeError(message, response.status, payload, response.headers, requestId);
+    }
+    if (response.status === 429) {
+        return new RateLimitError(message, response.status, payload, response.headers, requestId, parseRetryAfter(response.headers.get("retry-after")));
+    }
+    if (response.status >= 500) {
+        return new ServerError(message, response.status, payload, response.headers, requestId);
+    }
+    return new SenticoreApiError(message, response.status, payload, response.headers, requestId);
+}
+function messageFromPayload(status, payload) {
+    if (payload && typeof payload === "object") {
+        const record = payload;
+        for (const key of ["error", "message", "detail"]) {
+            if (typeof record[key] === "string" && record[key]) {
+                return `Senticore HTTP ${status}: ${record[key]}`;
+            }
+        }
+    }
+    return `Senticore HTTP ${status}`;
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}