@totalis/hip4-client 0.0.0-stage → 0.65.2

package/dist/base.d.ts

@@ -0,0 +1,41 @@
+import { type ClientOptions } from "openapi-fetch";
+import { type RetryPolicy } from "./request.js";
+export declare const publicServers: {
+    readonly production: "https://hip4-api.totalis.trade";
+    readonly staging: "https://hip4-api-staging.totalis.trade";
+    readonly local: "http://localhost:8080";
+};
+/**
+ * Where each environment serves its WebSockets (`/v1/stream` and
+ * `/v1/market-stream`). Production and staging have a dedicated stream host;
+ * the API host still serves both paths during the migration.
+ */
+export declare const publicStreamServers: {
+    readonly production: "wss://hip4-ws.totalis.trade";
+    readonly staging: "wss://hip4-ws-staging.totalis.trade";
+    readonly local: "ws://localhost:8080";
+};
+export type PublicEnvironment = keyof typeof publicServers;
+/** A bearer credential, or a function that returns the current one (for sessions that renew). */
+export type AccessToken = string | (() => string | Promise<string>);
+export type ApiClientOptions = Omit<ClientOptions, "baseUrl"> & {
+    accessToken?: AccessToken;
+    /** Replace the environment's origin, for example a local stack. */
+    baseUrl?: string;
+    /** Resend policy for network failures and BACKOFF errors; `false` sends once. */
+    retry?: RetryPolicy | false;
+    /**
+     * A partner's publishable browser key (`tpb_v1_…`), sent as
+     * `X-Totalis-Partner` from the partner's registered origins. It is public
+     * and only labels the traffic; it is never the `tpk_` server key.
+     */
+    partnerKey?: string;
+};
+/** The X-Totalis-Partner header for a publishable key, refusing anything else, above all a server key. */
+export declare function partnerHeader(partnerKey: string | undefined): Record<string, string> | undefined;
+/** Request headers as a plain record, for the stream handshake outside a browser. */
+export declare function headerRecord(headers: ClientOptions["headers"]): Record<string, string>;
+export declare function serverUrl(environment: PublicEnvironment, baseUrl?: string): string;
+/** A custom `baseUrl` serves the stream paths too, so it stays the stream origin unless `streamBaseUrl` is set. */
+export declare function streamServerUrl(environment: PublicEnvironment, baseUrl?: string, streamBaseUrl?: string): string;
+export declare function audienceClient<Paths extends Record<string, unknown>>(environment: PublicEnvironment, options?: ApiClientOptions): import("openapi-fetch").Client<Paths, `${string}/${string}`>;

package/dist/base.js

@@ -0,0 +1,60 @@
+import createOpenApiClient, { mergeHeaders } from "openapi-fetch";
+import { retryingFetch } from "./request.js";
+export const publicServers = {
+    production: "https://hip4-api.totalis.trade",
+    staging: "https://hip4-api-staging.totalis.trade",
+    local: "http://localhost:8080",
+};
+/**
+ * Where each environment serves its WebSockets (`/v1/stream` and
+ * `/v1/market-stream`). Production and staging have a dedicated stream host;
+ * the API host still serves both paths during the migration.
+ */
+export const publicStreamServers = {
+    production: "wss://hip4-ws.totalis.trade",
+    staging: "wss://hip4-ws-staging.totalis.trade",
+    local: "ws://localhost:8080",
+};
+const browserKey = /^tpb_v1_(dev|stg|prd)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The X-Totalis-Partner header for a publishable key, refusing anything else, above all a server key. */
+export function partnerHeader(partnerKey) {
+    if (partnerKey === undefined)
+        return undefined;
+    if (partnerKey.startsWith("tpk_"))
+        throw new Error("partnerKey takes the publishable tpb_ key; a tpk_ server key must stay on your server");
+    if (!browserKey.test(partnerKey))
+        throw new Error("partnerKey is not a publishable tpb_v1 key");
+    return { "X-Totalis-Partner": partnerKey };
+}
+/** Request headers as a plain record, for the stream handshake outside a browser. */
+export function headerRecord(headers) {
+    const record = {};
+    mergeHeaders(headers).forEach((value, name) => { record[name] = value; });
+    return record;
+}
+export function serverUrl(environment, baseUrl) {
+    return baseUrl ?? publicServers[environment];
+}
+/** A custom `baseUrl` serves the stream paths too, so it stays the stream origin unless `streamBaseUrl` is set. */
+export function streamServerUrl(environment, baseUrl, streamBaseUrl) {
+    return (streamBaseUrl ?? baseUrl ?? publicStreamServers[environment]).replace(/^http/, "ws");
+}
+export function audienceClient(environment, options = {}) {
+    const { accessToken, headers, baseUrl, retry, partnerKey, fetch: fetchImpl, ...rest } = options;
+    const resolvedHeaders = mergeHeaders(headers, partnerHeader(partnerKey), typeof accessToken === "string" ? { Authorization: `Bearer ${accessToken}` } : undefined);
+    const client = createOpenApiClient({
+        ...rest,
+        baseUrl: serverUrl(environment, baseUrl),
+        headers: resolvedHeaders,
+        fetch: retry === false ? (fetchImpl ?? ((request) => globalThis.fetch(request))) : retryingFetch(fetchImpl, retry),
+    });
+    if (typeof accessToken === "function") {
+        client.use({
+            async onRequest({ request }) {
+                request.headers.set("Authorization", `Bearer ${await accessToken()}`);
+                return request;
+            },
+        });
+    }
+    return client;
+}

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import { type ApiClientOptions, type PublicEnvironment } from "./base.js";
+import type { paths } from "./generated/client.js";
+export { publicServers, publicStreamServers } from "./base.js";
+export type { components, operations, paths } from "./generated/client.js";
+export type { AccessToken, ApiClientOptions, PublicEnvironment } from "./base.js";
+/** The typed HTTP client for the `client` audience. `createTotalis` adds the flows. */
+export declare function createClient(environment: PublicEnvironment, options?: ApiClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;
+export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, type Acceptance, type AcceptanceResult, type Amount, type BridgeState, type CashoutBid, type Chooser, type Deployment, type DepositAccepted, type EntryCash, type EntryFailure, type EntryQuote, type CoreExit, type LegacySignedEntry, type Leg, type NotAdmitted, type RecordListener, type Operation, type Quote, type ResponseOf, type SellBackQuote, type SignedAcceptance, type SignedCashout, type SignedCoreExit, type SignedDeposit, type SignedEntry, type SignedReturnToCore, type Totalis, type TotalisOptions, type TransferQuote, type WalletCall, type Withdrawal, } from "./totalis.js";
+export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, type BridgedCash, type HypercoreAnswer, type HypercoreSignature, type HypercoreTransport, type HyperliquidNetwork, type SendAssetAction, type SignedSendAsset, } from "./hypercore.js";
+export { ApiError, envelope, NetworkError, randomBytes32, retryingFetch, sendOnce, unwrap, uuidv7, type Fetch, type Repaired, type RetryPolicy } from "./request.js";
+export { items, pages, type Page, type PageQuery } from "./pagination.js";
+export { toTotalisSigner, type SignerInput, type TotalisSigner } from "./signer.js";
+export { BalanceUnknownError, ExitUnavailableError, normalizeError, type NormalizedError } from "./flow-errors.js";
+export { netCashout, netOfProfitFee, netPayout, netStake, spendableCash } from "./money.js";
+export { createUiAdapter, type AccountResource, type QuoteView, type UiAdapter, type UiAdapterOptions } from "./ui.js";
+export { StreamClosedError, TotalisStream, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscription } from "./stream.js";

package/dist/client.js

@@ -0,0 +1,15 @@
+import { audienceClient } from "./base.js";
+export { publicServers, publicStreamServers } from "./base.js";
+/** The typed HTTP client for the `client` audience. `createTotalis` adds the flows. */
+export function createClient(environment, options) {
+    return audienceClient(environment, options);
+}
+export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, } from "./totalis.js";
+export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, } from "./hypercore.js";
+export { ApiError, envelope, NetworkError, randomBytes32, retryingFetch, sendOnce, unwrap, uuidv7 } from "./request.js";
+export { items, pages } from "./pagination.js";
+export { toTotalisSigner } from "./signer.js";
+export { BalanceUnknownError, ExitUnavailableError, normalizeError } from "./flow-errors.js";
+export { netCashout, netOfProfitFee, netPayout, netStake, spendableCash } from "./money.js";
+export { createUiAdapter } from "./ui.js";
+export { StreamClosedError, TotalisStream } from "./stream.js";

package/dist/controller.d.ts

@@ -0,0 +1,50 @@
+import type { components } from "./generated/openapi.js";
+import { type Hex, type TotalisDeployment, type UsdcDeployment } from "./typed-data.js";
+/**
+ * A zero-value transaction for a wallet to sign and send itself: the API's
+ * `TransactionCall` (maker funding, collateral reductions), for any deployment
+ * chain and with hex-typed fields. The SDK never sends transactions or holds a
+ * gas key.
+ */
+export type TransactionCall = Omit<components["schemas"]["TransactionCall"], "chain_id" | "to" | "data"> & {
+    readonly chain_id: string;
+    readonly to: Hex;
+    readonly data: Hex;
+};
+type Input = {
+    readonly name: string;
+    readonly type: string;
+};
+type Value = bigint | string;
+/** Calldata from the API, or a TypeError. */
+export declare function calldata(value: string): Hex;
+/** ABI-encode a call whose arguments are all static words (addresses and unsigned integers). */
+export declare function encodeCall(name: string, inputs: readonly Input[], values: readonly Value[]): Hex;
+/**
+ * Open a maker vault. A maker is one wallet: send this from `wallet`, which
+ * becomes both its controller and its quote signer. A wallet opens at most one
+ * maker: read the new maker ID with the vault's `makerOf(wallet)`, never
+ * predict it.
+ */
+export declare function openMakerVaultTransaction(deployment: TotalisDeployment, wallet: string): TransactionCall;
+/**
+ * Vault transactions for one maker, built from the canonical ABI. The maker
+ * wallet sends all of them except `approveUsdc` and `deposit`, which come from
+ * whichever wallet funds the deposit. `controller` is the maker wallet (`owner`
+ * in GET /v1/makers/{maker_id}/capital): the vault refuses a deposit naming any
+ * other.
+ */
+export declare function controllerTransactions(deployment: TotalisDeployment & UsdcDeployment, makerId: string, controller: string): {
+    /** USDC `approve(vault, amount)`, sent by the funding wallet before `deposit`. */
+    approveUsdc: (amount: Value) => TransactionCall;
+    /** `depositMaker`: pull approved USDC from the sending wallet into this maker's vault. */
+    deposit: (amount: Value) => TransactionCall;
+    /** `requestMakerWithdraw`: start the withdrawal delay for `amount` to `to`. */
+    requestWithdraw: (amount: Value, to: string) => TransactionCall;
+    /** `executeMakerWithdraw`: pay out the pending request once its delay has passed. */
+    executeWithdraw: () => TransactionCall;
+    cancelWithdraw: () => TransactionCall;
+    resetDiscount: () => TransactionCall;
+};
+export type ControllerTransactions = ReturnType<typeof controllerTransactions>;
+export {};

package/dist/controller.js

@@ -0,0 +1,60 @@
+import { keccak_256 } from "@noble/hashes/sha3";
+import { controllerFunctions } from "./generated/vault-abi.js";
+import { address } from "./typed-data.js";
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+function word(type, value) {
+    if (type === "address")
+        return address(String(value)).slice(2).toLowerCase().padStart(64, "0");
+    const bits = /^uint(\d+)$/.exec(type)?.[1];
+    if (bits === undefined)
+        throw new TypeError(`unsupported ABI type ${type}`);
+    const integer = BigInt(value);
+    if (integer < 0n || integer >= 1n << BigInt(bits))
+        throw new RangeError(`${value} does not fit ${type}`);
+    return integer.toString(16).padStart(64, "0");
+}
+/** Calldata from the API, or a TypeError. */
+export function calldata(value) {
+    if (!/^0x(?:[0-9a-fA-F]{2})*$/.test(value))
+        throw new TypeError(`not calldata: ${value}`);
+    return value;
+}
+/** ABI-encode a call whose arguments are all static words (addresses and unsigned integers). */
+export function encodeCall(name, inputs, values) {
+    if (values.length !== inputs.length)
+        throw new TypeError(`${name} takes ${inputs.length} arguments`);
+    const selector = hex(keccak_256(new TextEncoder().encode(`${name}(${inputs.map((input) => input.type).join(",")})`)).slice(0, 4));
+    return `0x${selector}${inputs.map((input, index) => word(input.type, values[index])).join("")}`;
+}
+const call = (deployment, to, data) => ({ chain_id: deployment.chain_id, to: address(to.toLowerCase()), data, value: "0" });
+const vaultCall = (deployment, name, values) => call(deployment, deployment.vault_address, encodeCall(name, controllerFunctions[name], values));
+/**
+ * Open a maker vault. A maker is one wallet: send this from `wallet`, which
+ * becomes both its controller and its quote signer. A wallet opens at most one
+ * maker: read the new maker ID with the vault's `makerOf(wallet)`, never
+ * predict it.
+ */
+export function openMakerVaultTransaction(deployment, wallet) {
+    return vaultCall(deployment, "openMakerVault", [wallet]);
+}
+/**
+ * Vault transactions for one maker, built from the canonical ABI. The maker
+ * wallet sends all of them except `approveUsdc` and `deposit`, which come from
+ * whichever wallet funds the deposit. `controller` is the maker wallet (`owner`
+ * in GET /v1/makers/{maker_id}/capital): the vault refuses a deposit naming any
+ * other.
+ */
+export function controllerTransactions(deployment, makerId, controller) {
+    return {
+        /** USDC `approve(vault, amount)`, sent by the funding wallet before `deposit`. */
+        approveUsdc: (amount) => call(deployment, deployment.usdc.address, encodeCall("approve", [{ name: "spender", type: "address" }, { name: "amount", type: "uint256" }], [deployment.vault_address, amount])),
+        /** `depositMaker`: pull approved USDC from the sending wallet into this maker's vault. */
+        deposit: (amount) => vaultCall(deployment, "depositMaker", [makerId, controller, amount]),
+        /** `requestMakerWithdraw`: start the withdrawal delay for `amount` to `to`. */
+        requestWithdraw: (amount, to) => vaultCall(deployment, "requestMakerWithdraw", [makerId, amount, to]),
+        /** `executeMakerWithdraw`: pay out the pending request once its delay has passed. */
+        executeWithdraw: () => vaultCall(deployment, "executeMakerWithdraw", [makerId]),
+        cancelWithdraw: () => vaultCall(deployment, "cancelMakerWithdraw", [makerId]),
+        resetDiscount: () => vaultCall(deployment, "resetDiscount", [makerId]),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export * from "./generated/errors.js";
+export { ApiError, NetworkError } from "./request.js";
+export { BalanceUnknownError, EntryError, ExitUnavailableError, normalizeError, type NormalizedError } from "./flow-errors.js";

package/dist/errors.js

@@ -0,0 +1,3 @@
+export * from "./generated/errors.js";
+export { ApiError, NetworkError } from "./request.js";
+export { BalanceUnknownError, EntryError, ExitUnavailableError, normalizeError } from "./flow-errors.js";

package/dist/flow-errors.d.ts

@@ -0,0 +1,61 @@
+import type { Retry } from "./generated/errors.js";
+/**
+ * An entry that stopped while planning its funding, before anything was sent,
+ * so nothing traded: `BALANCE_UNKNOWN` or `INSUFFICIENT_FUNDS`.
+ */
+export declare class EntryError extends Error {
+    readonly code: "BALANCE_UNKNOWN" | "INSUFFICIENT_FUNDS";
+    readonly name = "EntryError";
+    constructor(code: "BALANCE_UNKNOWN" | "INSUFFICIENT_FUNDS", message: string);
+}
+/**
+ * A withdrawal, exit or return to HyperCore needs a balance the venue has no
+ * current read of (`component` is not `CURRENT` in `GET /v1/me/balances`).
+ * Nothing was signed or sent; read the balances again and retry. An entry
+ * throws `EntryError` `BALANCE_UNKNOWN` instead.
+ */
+export declare class BalanceUnknownError extends Error {
+    readonly component: "VAULT_FREE" | "WALLET_USDC";
+    readonly name = "BalanceUnknownError";
+    readonly code = "BALANCE_UNKNOWN";
+    constructor(component: "VAULT_FREE" | "WALLET_USDC", message: string);
+}
+/**
+ * This deployment has no exit to HyperCore (`deployment: null` on
+ * `GET /v1/me/core-exits`, or the venue's 503 `CORE_EXIT_UNAVAILABLE`;
+ * staging runs without one). Retrying
+ * will not help: hide the action instead. `cause` is the venue's refusal when
+ * there was one.
+ */
+export declare class ExitUnavailableError extends Error {
+    readonly name = "ExitUnavailableError";
+    readonly code = "EXIT_UNAVAILABLE";
+    constructor(options?: {
+        cause: unknown;
+    });
+}
+/** Any SDK failure in one shape, for a UI or a log line. */
+export type NormalizedError = {
+    /** The venue's registered code, `EntryError`'s code, `BALANCE_UNKNOWN`, `EXIT_UNAVAILABLE`, `NETWORK`, `STREAM_CLOSED` (with the close reason in `message`), `TIMEOUT`, `ABORTED` or `UNKNOWN`. */
+    readonly code: string;
+    readonly message: string;
+    /** Trying again can succeed: the same request later (BACKOFF, a lost response) or a fresh read and a new request (REFRESH, an unknown balance). */
+    readonly retryable: boolean;
+    /** The venue's `retry` for an `ApiError`. */
+    readonly retry: Retry | undefined;
+    /** The venue's request ID, to quote to support. */
+    readonly requestId: string | undefined;
+    readonly status: number | undefined;
+    /**
+     * The command may have reached the venue and may still execute: its
+     * response was lost, it was aborted or timed out in flight, it was still
+     * BACKOFF after the resends (an earlier send may have been lost), or a
+     * proxy answered 5xx without the venue's error envelope. Never sign a new
+     * command; `resend` it or read its state.
+     */
+    readonly mayStillRun: boolean;
+    /** Sends the identical request again, when the flow attached it. */
+    readonly resend: (() => Promise<unknown>) | undefined;
+    readonly cause: unknown;
+};
+export declare function normalizeError(error: unknown): NormalizedError;

package/dist/flow-errors.js

@@ -0,0 +1,70 @@
+import { ApiError, NetworkError } from "./request.js";
+import { StreamClosedError } from "./stream.js";
+/**
+ * An entry that stopped while planning its funding, before anything was sent,
+ * so nothing traded: `BALANCE_UNKNOWN` or `INSUFFICIENT_FUNDS`.
+ */
+export class EntryError extends Error {
+    code;
+    name = "EntryError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * A withdrawal, exit or return to HyperCore needs a balance the venue has no
+ * current read of (`component` is not `CURRENT` in `GET /v1/me/balances`).
+ * Nothing was signed or sent; read the balances again and retry. An entry
+ * throws `EntryError` `BALANCE_UNKNOWN` instead.
+ */
+export class BalanceUnknownError extends Error {
+    component;
+    name = "BalanceUnknownError";
+    code = "BALANCE_UNKNOWN";
+    constructor(component, message) {
+        super(message);
+        this.component = component;
+    }
+}
+/**
+ * This deployment has no exit to HyperCore (`deployment: null` on
+ * `GET /v1/me/core-exits`, or the venue's 503 `CORE_EXIT_UNAVAILABLE`;
+ * staging runs without one). Retrying
+ * will not help: hide the action instead. `cause` is the venue's refusal when
+ * there was one.
+ */
+export class ExitUnavailableError extends Error {
+    name = "ExitUnavailableError";
+    code = "EXIT_UNAVAILABLE";
+    constructor(options) {
+        super("exits to HyperCore are not configured on this deployment", options);
+    }
+}
+export function normalizeError(error) {
+    const base = { retry: undefined, requestId: undefined, status: undefined, mayStillRun: false, resend: undefined, cause: error };
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ApiError) {
+        return {
+            ...base, code: error.code, message, retryable: error.retry !== "NEVER", retry: error.retry, requestId: error.requestId, status: error.status,
+            // A command still BACKOFF after its resends (it carries `resend`) may hide an earlier send that was lost after reaching the venue.
+            mayStillRun: error.resend !== undefined || (error.code.startsWith("HTTP_") && error.status >= 500), resend: error.resend,
+        };
+    }
+    if (error instanceof NetworkError)
+        return { ...base, code: "NETWORK", message, retryable: true, mayStillRun: true, resend: error.resend };
+    if (error instanceof EntryError)
+        return { ...base, code: error.code, message, retryable: error.code === "BALANCE_UNKNOWN" };
+    if (error instanceof BalanceUnknownError)
+        return { ...base, code: error.code, message, retryable: true };
+    if (error instanceof ExitUnavailableError)
+        return { ...base, code: error.code, message, retryable: false };
+    if (error instanceof StreamClosedError)
+        return { ...base, code: "STREAM_CLOSED", message: error.reason, retryable: false };
+    // An aborted or timed-out request may still have reached the venue.
+    if (error instanceof Error && error.name === "TimeoutError")
+        return { ...base, code: "TIMEOUT", message, retryable: true, mayStillRun: true };
+    if (error instanceof Error && error.name === "AbortError")
+        return { ...base, code: "ABORTED", message, retryable: false, mayStillRun: true };
+    return { ...base, code: "UNKNOWN", message, retryable: false };
+}