@clear-street/studio-sdk 0.1.0-alpha.4

package/src/error.ts

@@ -0,0 +1,146 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { castToError, Headers } from './core';
+
+export class StudioSDKError extends Error {}
+
+export class APIError extends StudioSDKError {
+  readonly status: number | undefined;
+  readonly headers: Headers | undefined;
+  readonly error: Object | undefined;
+
+  constructor(
+    status: number | undefined,
+    error: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+    this.error = error;
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg =
+      error?.message ?
+        typeof error.message === 'string' ?
+          error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return '(no status code or body)';
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ) {
+    if (!status) {
+      return new APIConnectionError({ cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIUserAbortError extends APIError {
+  override readonly status: undefined = undefined;
+
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
+export class APIConnectionError extends APIError {
+  override readonly status: undefined = undefined;
+
+  constructor({ message, cause }: { message?: string; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
+  }
+}
+
+export class BadRequestError extends APIError {
+  override readonly status: 400 = 400;
+}
+
+export class AuthenticationError extends APIError {
+  override readonly status: 401 = 401;
+}
+
+export class PermissionDeniedError extends APIError {
+  override readonly status: 403 = 403;
+}
+
+export class NotFoundError extends APIError {
+  override readonly status: 404 = 404;
+}
+
+export class ConflictError extends APIError {
+  override readonly status: 409 = 409;
+}
+
+export class UnprocessableEntityError extends APIError {
+  override readonly status: 422 = 422;
+}
+
+export class RateLimitError extends APIError {
+  override readonly status: 429 = 429;
+}
+
+export class InternalServerError extends APIError {}

package/src/index.ts

@@ -0,0 +1,206 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as Errors from './error';
+import * as Uploads from './uploads';
+import { type Agent } from './_shims/index';
+import * as Core from "./core";
+import * as API from "./resources/index";
+
+export interface ClientOptions {
+  /**
+   * Defaults to process.env['STUDIO_SDK_BEARER_TOKEN'].
+   */
+  bearerToken?: string | undefined;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   *
+   * Defaults to process.env['STUDIO_SDK_BASE_URL'].
+   */
+  baseURL?: string | null | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
+  timeout?: number;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
+  httpAgent?: Agent;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
+  maxRetries?: number;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
+  defaultHeaders?: Core.Headers;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery;
+}
+
+/**
+ * API Client for interfacing with the Studio SDK API.
+ */
+export class StudioSDK extends Core.APIClient {
+  bearerToken: string;
+
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the Studio SDK API.
+   *
+   * @param {string | undefined} [opts.bearerToken=process.env['STUDIO_SDK_BEARER_TOKEN'] ?? undefined]
+   * @param {string} [opts.baseURL=process.env['STUDIO_SDK_BASE_URL'] ?? https://api.clearstreet.io/studio/v2] - Override the default base URL for the API.
+   * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
+   * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({
+    baseURL = Core.readEnv('STUDIO_SDK_BASE_URL'),
+    bearerToken = Core.readEnv('STUDIO_SDK_BEARER_TOKEN'),
+    ...opts
+  }: ClientOptions = {}) {
+    if (bearerToken === undefined) {
+      throw new Errors.StudioSDKError(
+        "The STUDIO_SDK_BEARER_TOKEN environment variable is missing or empty; either provide it, or instantiate the StudioSDK client with an bearerToken option, like new StudioSDK({ bearerToken: 'My Bearer Token' }).",
+      );
+    }
+
+    const options: ClientOptions = {
+      bearerToken,
+      ...opts,
+      baseURL: baseURL || `https://api.clearstreet.io/studio/v2`,
+    };
+
+    super({
+      baseURL: options.baseURL!,
+      timeout: options.timeout ?? 60000 /* 1 minute */,
+      httpAgent: options.httpAgent,
+      maxRetries: options.maxRetries,
+      fetch: options.fetch,
+    });
+
+    this._options = options;
+
+    this.bearerToken = bearerToken;
+  }
+
+  entities: API.Entities = new API.Entities(this);
+  accounts: API.Accounts = new API.Accounts(this);
+  instruments: API.Instruments = new API.Instruments(this);
+
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return {
+      ...super.defaultHeaders(opts),
+      ...this._options.defaultHeaders,
+    };
+  }
+
+  protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return { Authorization: `Bearer ${this.bearerToken}` };
+  }
+
+  static StudioSDK = this;
+
+  static StudioSDKError = Errors.StudioSDKError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+
+  static toFile = Uploads.toFile;
+  static fileFromPath = Uploads.fileFromPath;
+}
+
+export const {
+  StudioSDKError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  BadRequestError,
+  AuthenticationError,
+  InternalServerError,
+  PermissionDeniedError,
+  UnprocessableEntityError,
+} = Errors;
+
+export import toFile = Uploads.toFile;
+export import fileFromPath = Uploads.fileFromPath;
+
+export namespace StudioSDK {
+  export import RequestOptions = Core.RequestOptions;
+
+  export import Entities = API.Entities;
+  export import Entity = API.Entity;
+  export import PnlSummary = API.PnlSummary;
+  export import PortfolioMargin = API.PortfolioMargin;
+  export import RegtMargin = API.RegtMargin;
+  export import EntityListResponse = API.EntityListResponse;
+
+  export import Accounts = API.Accounts;
+  export import Account = API.Account;
+  export import AccountListResponse = API.AccountListResponse;
+
+  export import Instruments = API.Instruments;
+  export import Instrument = API.Instrument;
+  export import InstrumentRetrieveParams = API.InstrumentRetrieveParams;
+
+  export import LocateOrder = API.LocateOrder;
+  export import Order = API.Order;
+  export import PnlSummaryForAccount = API.PnlSummaryForAccount;
+  export import Position = API.Position;
+  export import RegtMarginSimulation = API.RegtMarginSimulation;
+  export import Trade = API.Trade;
+}
+
+export default StudioSDK;

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/resource.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import type { StudioSDK } from './index';
+
+export class APIResource {
+  protected _client: StudioSDK;
+
+  constructor(client: StudioSDK) {
+    this._client = client;
+  }
+}

package/src/resources/accounts/accounts.ts

@@ -0,0 +1,87 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from "../../resource";
+import * as Core from "../../core";
+import * as AccountsAPI from "./accounts";
+import * as BulkOrdersAPI from "./bulk-orders";
+import * as EasyBorrowsAPI from "./easy-borrows";
+import * as LocateOrdersAPI from "./locate-orders";
+import * as OrdersAPI from "./orders";
+import * as PnlDetailsAPI from "./pnl-details";
+import * as PnlSummaryAPI from "./pnl-summary";
+import * as PositionsAPI from "./positions";
+import * as TradesAPI from "./trades";
+
+export class Accounts extends APIResource {
+  bulkOrders: BulkOrdersAPI.BulkOrders = new BulkOrdersAPI.BulkOrders(this._client);
+  orders: OrdersAPI.Orders = new OrdersAPI.Orders(this._client);
+  trades: TradesAPI.Trades = new TradesAPI.Trades(this._client);
+  positions: PositionsAPI.Positions = new PositionsAPI.Positions(this._client);
+  locateOrders: LocateOrdersAPI.LocateOrders = new LocateOrdersAPI.LocateOrders(this._client);
+  easyBorrows: EasyBorrowsAPI.EasyBorrows = new EasyBorrowsAPI.EasyBorrows(this._client);
+  pnlSummary: PnlSummaryAPI.PnlSummary = new PnlSummaryAPI.PnlSummary(this._client);
+  pnlDetails: PnlDetailsAPI.PnlDetails = new PnlDetailsAPI.PnlDetails(this._client);
+
+  /**
+   * Get an account by its ID.
+   */
+  retrieve(accountId: string, options?: Core.RequestOptions): Core.APIPromise<Account> {
+    return this._client.get(`/accounts/${accountId}`, options);
+  }
+
+  /**
+   * List all available accounts.
+   */
+  list(options?: Core.RequestOptions): Core.APIPromise<AccountListResponse> {
+    return this._client.get('/accounts', options);
+  }
+}
+
+export interface Account {
+  /**
+   * Account ID for the account.
+   */
+  account_id: string;
+
+  /**
+   * Entity ID for the legal entity.
+   */
+  entity_id: string;
+
+  name: string;
+}
+
+export interface AccountListResponse {
+  data?: Array<Account>;
+}
+
+export namespace Accounts {
+  export import Account = AccountsAPI.Account;
+  export import AccountListResponse = AccountsAPI.AccountListResponse;
+  export import BulkOrders = BulkOrdersAPI.BulkOrders;
+  export import BulkOrderCreateResponse = BulkOrdersAPI.BulkOrderCreateResponse;
+  export import BulkOrderCreateParams = BulkOrdersAPI.BulkOrderCreateParams;
+  export import Orders = OrdersAPI.Orders;
+  export import OrderCreateResponse = OrdersAPI.OrderCreateResponse;
+  export import OrderRetrieveResponse = OrdersAPI.OrderRetrieveResponse;
+  export import OrderListResponse = OrdersAPI.OrderListResponse;
+  export import OrderDeleteResponse = OrdersAPI.OrderDeleteResponse;
+  export import OrderCreateParams = OrdersAPI.OrderCreateParams;
+  export import OrderListParams = OrdersAPI.OrderListParams;
+  export import OrderDeleteParams = OrdersAPI.OrderDeleteParams;
+  export import Trades = TradesAPI.Trades;
+  export import TradeListResponse = TradesAPI.TradeListResponse;
+  export import TradeListParams = TradesAPI.TradeListParams;
+  export import Positions = PositionsAPI.Positions;
+  export import PositionListResponse = PositionsAPI.PositionListResponse;
+  export import PositionListParams = PositionsAPI.PositionListParams;
+  export import LocateOrders = LocateOrdersAPI.LocateOrders;
+  export import LocateOrderListResponse = LocateOrdersAPI.LocateOrderListResponse;
+  export import LocateOrderCreateParams = LocateOrdersAPI.LocateOrderCreateParams;
+  export import LocateOrderUpdateParams = LocateOrdersAPI.LocateOrderUpdateParams;
+  export import EasyBorrows = EasyBorrowsAPI.EasyBorrows;
+  export import EasyBorrowListResponse = EasyBorrowsAPI.EasyBorrowListResponse;
+  export import PnlSummary = PnlSummaryAPI.PnlSummary;
+  export import PnlDetails = PnlDetailsAPI.PnlDetails;
+  export import PnlDetailListResponse = PnlDetailsAPI.PnlDetailListResponse;
+}

package/src/resources/accounts/bulk-orders.ts

@@ -0,0 +1,163 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from "../../resource";
+import * as Core from "../../core";
+import * as BulkOrdersAPI from "./bulk-orders";
+
+export class BulkOrders extends APIResource {
+  /**
+   * Creates multiple orders in a single request, up to 1000. Note that a successful
+   * call to this endpoint does not necessarily mean your orders have been accepted,
+   * e.g. a downstream venue might reject your order. You should therefore utilize
+   * our WebSocket APIs to listen for changes in order lifecycle events.
+   *
+   * The response will contain an array of objects, indicating whether your order was
+   * submitted. If the order was submitted, the `order_id` field will be populated
+   * with the order ID assigned to this order. If the order was rejected, the
+   * `reason` field will be populated with the reason for rejection. The data array
+   * returned in the response object is guaranteed to be ordered in the same order as
+   * the orders you provided in the request. Again, note that even if your order was
+   * submitted, that doesn't mean it was _accepted_, and may still be rejected by
+   * downstream venues.
+   */
+  create(
+    accountId: string,
+    body: BulkOrderCreateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<BulkOrderCreateResponse> {
+    return this._client.post(`/accounts/${accountId}/bulk-orders`, { body, ...options });
+  }
+}
+
+export interface BulkOrderCreateResponse {
+  /**
+   * Array indicating whether each respective order was submitted or not. This array
+   * is guaranteed to be sorted in the same order as the orders you provided in your
+   * request.
+   */
+  data: Array<BulkOrderCreateResponse.Data>;
+
+  /**
+   * Total number of orders rejected
+   */
+  rejected: number;
+
+  /**
+   * Total number of orders submitted
+   */
+  submitted: number;
+}
+
+export namespace BulkOrderCreateResponse {
+  export interface Data {
+    /**
+     * True if the order was submitted successfully, false otherwise.
+     */
+    submitted: boolean;
+
+    /**
+     * If the order was submitted, the order ID assigned to this order. Empty if the
+     * order was rejected.
+     */
+    order_id?: string;
+
+    /**
+     * If the order rejected, the reason for rejection. Empty if the order was
+     * accepted.
+     */
+    reason?: string;
+  }
+}
+
+export interface BulkOrderCreateParams {
+  /**
+   * An array of orders to create.
+   */
+  orders: Array<BulkOrderCreateParams.Order>;
+}
+
+export namespace BulkOrderCreateParams {
+  export interface Order {
+    /**
+     * The type of order, can be one of the following:
+     *
+     * - `limit`: A limit order will execute at-or-better than the limit price you
+     *   specify
+     * - `market`: An order that will execute at the prevailing market prices
+     */
+    order_type: 'limit' | 'market';
+
+    /**
+     * The maximum quantity to be executed.
+     */
+    quantity: string;
+
+    /**
+     * Buy, sell, sell-short indicator.
+     */
+    side: 'buy' | 'sell' | 'sell-short';
+
+    /**
+     * Strategy type used for execution, can be one of below. Note, we use sensible
+     * defaults for strategy parameters at the moment. In future, we will provide a way
+     * to provide specify these parameters.
+     *
+     * - `sor`: Smart order router
+     * - `dark`: Dark pool
+     * - `ap`: Arrival price
+     * - `pov`: Percentage of volume
+     * - `twap`: Time weighted average price
+     * - `vwap`: Volume weighted average price
+     *
+     * For more information on these strategies, please refer to our
+     * [documentation](https://docs.clearstreet.io/studio/docs/execution-strategies).
+     */
+    strategy_type: 'sor' | 'dark' | 'ap' | 'pov' | 'twap' | 'vwap';
+
+    /**
+     * The symbol this order is for. See `symbol_format` for supported symbol formats.
+     */
+    symbol: string;
+
+    /**
+     * The lifecycle enforcement of this order.
+     *
+     * - `day`: The order will exist for the duration of the current trading session
+     * - `ioc`: The order will immediately be executed or cancelled
+     * - `day-plus`: The order will exist only for the duration the current trading
+     *   session plus extended hours, if applicable
+     * - `at-open`: The order will exist only for the opening auction of the next
+     *   session
+     * - `at-close`: The order will exist only for the closing auction of the current
+     *   session
+     */
+    time_in_force: 'day' | 'ioc' | 'day-plus' | 'at-open' | 'at-close';
+
+    /**
+     * Name of the broker that provided you inventory for a short-sale. Required if
+     * `side` is `sell-short`. If you procured inventory through us, you can use
+     * `CLST`.
+     */
+    locate_broker?: string;
+
+    /**
+     * The price to execute at-or-better.
+     */
+    price?: string;
+
+    /**
+     * An ID that you provide.
+     */
+    reference_id?: string;
+
+    /**
+     * Denotes the format of the provided `symbol` field.
+     */
+    symbol_format?: 'cms' | 'osi';
+  }
+}
+
+export namespace BulkOrders {
+  export import BulkOrderCreateResponse = BulkOrdersAPI.BulkOrderCreateResponse;
+  export import BulkOrderCreateParams = BulkOrdersAPI.BulkOrderCreateParams;
+}

package/src/resources/accounts/easy-borrows.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from "../../resource";
+import * as Core from "../../core";
+import * as EasyBorrowsAPI from "./easy-borrows";
+
+export class EasyBorrows extends APIResource {
+  /**
+   * List all current easy-to-borrow stock symbols. This list changes dynamically
+   * daily.
+   */
+  list(accountId: string, options?: Core.RequestOptions): Core.APIPromise<EasyBorrowListResponse> {
+    return this._client.get(`/accounts/${accountId}/easy-borrows`, options);
+  }
+}
+
+export interface EasyBorrowListResponse {
+  data: Array<string>;
+}
+
+export namespace EasyBorrows {
+  export import EasyBorrowListResponse = EasyBorrowsAPI.EasyBorrowListResponse;
+}

package/src/resources/accounts/index.ts

@@ -0,0 +1,25 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Account, AccountListResponse, Accounts } from './accounts';
+export { BulkOrderCreateResponse, BulkOrderCreateParams, BulkOrders } from './bulk-orders';
+export { EasyBorrowListResponse, EasyBorrows } from './easy-borrows';
+export {
+  LocateOrderListResponse,
+  LocateOrderCreateParams,
+  LocateOrderUpdateParams,
+  LocateOrders,
+} from './locate-orders';
+export {
+  OrderCreateResponse,
+  OrderRetrieveResponse,
+  OrderListResponse,
+  OrderDeleteResponse,
+  OrderCreateParams,
+  OrderListParams,
+  OrderDeleteParams,
+  Orders,
+} from './orders';
+export { PnlDetailListResponse, PnlDetails } from './pnl-details';
+export { PnlSummary } from './pnl-summary';
+export { PositionListResponse, PositionListParams, Positions } from './positions';
+export { TradeListResponse, TradeListParams, Trades } from './trades';