@clear-street/clearstreet 0.99.0 → 0.101.0

package/src/resources/v1/omni-ai/threads.ts

@@ -13,22 +13,23 @@ import { path } from '../../../internal/utils/path';
  */
 export class Threads extends APIResource {
   /**
-   * Continue an existing conversation thread.
-   *
-   * Appends a new user message to the thread and starts an assistant response. Only
-   * one response may be active per thread at a time — if the previous turn is still
-   * in progress, this endpoint returns **409 Conflict**. Wait for the active
-   * response to reach a terminal status before submitting the next turn.
-   *
+   * Append a user message to an existing thread and start an assistant response.
    * Poll the returned `response_id` via `GET /omni-ai/responses/{response_id}` for
    * assistant output.
    *
+   * Only one response may be active per thread. Wait for it to reach a terminal
+   * status before submitting another turn; otherwise this endpoint returns 409.
+   *
+   * The first accepted selected-account message links an unlinked thread. A linked
+   * thread keeps its account regardless of omission or another selection. A changed
+   * scope also returns 409 without accepting a turn.
+   *
    * @example
    * ```ts
    * const response =
    *   await client.v1.omniAI.threads.createMessage(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *     { account_id: 19816, text: 'Compare that to AMD.' },
+   *     { text: 'Compare that to AMD.' },
    *   );
    * ```
    */
@@ -41,23 +42,21 @@ export class Threads extends APIResource {
   }
 
   /**
-   * Create a new conversation thread.
+   * Atomically create a conversation and submit its first user turn. Use `instant`
+   * with `text` for a prompt, or `deep_insights` with a ticker `target` and optional
+   * `thesis` for long-form research.
    *
-   * Atomically creates a new thread and submits the first user turn. The response
-   * contains a `response_id` that should be polled via
-   * `GET /omni-ai/responses/{response_id}` for assistant output.
-   *
-   * Two creation modes are supported:
+   * Poll the returned `response_id` via `GET /omni-ai/responses/{response_id}` for
+   * assistant output.
    *
-   * - **instant** — provide `text` with a natural-language prompt.
-   * - **deep_insights** — provide a `target` ticker and optional `thesis` for
-   *   long-form research.
+   * Omit `account_id` to start without an account. The first accepted turn with a
+   * selected account links that account permanently. Reuse `Idempotency-Key` only
+   * for an identical request.
    *
    * @example
    * ```ts
    * const response =
    *   await client.v1.omniAI.threads.createThread({
-   *     account_id: 19816,
    *     type: 'instant',
    *   });
    * ```
@@ -70,102 +69,122 @@ export class Threads extends APIResource {
   }
 
   /**
-   * List finalized messages in a thread.
+   * List finalized messages, including messages created before the account link.
+   * Return the latest page by default, in chronological order within each page. Use
+   * the returned page token to navigate history.
    *
-   * Returns the latest page of **finalized** messages by default, with messages
-   * within each page ordered chronologically. Messages from in-progress assistant
-   * turns are excluded — use `GET /omni-ai/threads/{thread_id}/response` or
-   * `GET /omni-ai/responses/{response_id}` for live output.
-   *
-   * If the last finalized message has role `USER`, an active response likely exists
-   * and should be polled separately.
+   * In-progress assistant output is not included. Poll
+   * `GET /omni-ai/responses/{response_id}` until the response reaches a terminal
+   * status, then read its finalized message here.
    *
    * @example
    * ```ts
    * const response = await client.v1.omniAI.threads.getMessages(
    *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *   { account_id: 0 },
    * );
    * ```
    */
   getMessages(
     threadID: string,
-    query: ThreadGetMessagesParams,
+    query: ThreadGetMessagesParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<ThreadGetMessagesResponse> {
     return this._client.get(path`/v1/omni-ai/threads/${threadID}/messages`, { query, ...options });
   }
 
   /**
-   * Get a specific thread.
+   * Read an owned thread's metadata. Use `GET /omni-ai/threads/{thread_id}/messages`
+   * for conversation history.
    *
-   * Returns metadata (title, timestamps) for a single thread. Does not include
-   * messages — use `GET /omni-ai/threads/{thread_id}/messages` for conversation
-   * history.
+   * Omission or another account selection does not change authorization.
    *
    * @example
    * ```ts
    * const response =
    *   await client.v1.omniAI.threads.getThreadByID(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *     { account_id: 0 },
    *   );
    * ```
    */
   getThreadByID(
     threadID: string,
-    query: ThreadGetThreadByIDParams,
+    query: ThreadGetThreadByIDParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<ThreadGetThreadByIDResponse> {
     return this._client.get(path`/v1/omni-ai/threads/${threadID}`, { query, ...options });
   }
 
   /**
-   * Get the active response for a thread.
-   *
-   * Convenience endpoint to look up the currently active response for a thread
-   * without knowing the `response_id`. Useful when reloading a thread whose last
-   * finalized message is a `USER` message — this indicates an assistant turn is
-   * likely in progress.
+   * Look up the currently active response without knowing its `response_id`. Use
+   * this endpoint when reopening a thread whose assistant turn may still be in
+   * progress.
    *
-   * Returns **404** if no active response exists (the thread is idle).
+   * An idle owned thread returns HTTP 200 with `data: null`.
    *
    * @example
    * ```ts
    * const response =
    *   await client.v1.omniAI.threads.getThreadResponse(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *     { account_id: 0 },
    *   );
    * ```
    */
   getThreadResponse(
     threadID: string,
-    query: ThreadGetThreadResponseParams,
+    query: ThreadGetThreadResponseParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<ThreadGetThreadResponseResponse> {
     return this._client.get(path`/v1/omni-ai/threads/${threadID}/response`, { query, ...options });
   }
 
   /**
-   * List conversation threads.
+   * List authorized conversation metadata, newest first. Use `page_size` and
+   * `page_token` for pagination, and the messages endpoint for conversation history.
    *
-   * Returns thread metadata ordered by most recently created first. Use `page_size`
-   * and `page_token` for pagination. Thread objects contain only metadata (title,
-   * timestamps) — use the messages endpoint for conversation history.
+   * With `account_id`, list only conversations linked to that account and require
+   * current account access. Without it, list only conversations with no linked
+   * account.
    *
    * @example
    * ```ts
-   * const response = await client.v1.omniAI.threads.getThreads({
-   *   account_id: 0,
-   * });
+   * const response =
+   *   await client.v1.omniAI.threads.getThreads();
    * ```
    */
-  getThreads(query: ThreadGetThreadsParams, options?: RequestOptions): APIPromise<ThreadGetThreadsResponse> {
+  getThreads(
+    query: ThreadGetThreadsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ThreadGetThreadsResponse> {
     return this._client.get('/v1/omni-ai/threads', { query, ...options });
   }
 }
 
+/**
+ * A snapshot of the widget the user asks about.
+ */
+export interface ContextItem {
+  /**
+   * Relevant widget data, selections, and units. Use strings for exact decimals and
+   * large IDs.
+   */
+  data: { [key: string]: unknown };
+
+  /**
+   * Nonblank descriptive kind. New kinds do not require a backend release.
+   */
+  kind: string;
+
+  /**
+   * Nonblank attachment label for conversation rendering.
+   */
+  label: string;
+
+  /**
+   * Client-reported snapshot time. Omit when unknown.
+   */
+  captured_at?: string | null;
+}
+
 /**
  * Response payload for continuing a thread with a new message.
  */
@@ -215,6 +234,13 @@ export interface Message {
 
   thread_id: string;
 
+  /**
+   * Immutable snapshots attached to this user message. Omitted when none were
+   * supplied. When a null/undefined value is observed, it indicates that there is no
+   * available data.
+   */
+  context?: TurnContext | null;
+
   /**
    * When a null/undefined value is observed, it indicates it does not apply.
    */
@@ -288,7 +314,7 @@ export type MessageOutcome = 'completed' | 'errored' | 'canceled';
 export type MessageRole = 'USER' | 'ASSISTANT';
 
 /**
- * Thread metadata returned by list/get thread endpoints.
+ * Thread metadata.
  */
 export interface Thread {
   id: string;
@@ -302,6 +328,20 @@ export interface Thread {
 
 export type ThreadList = Array<Thread>;
 
+/**
+ * Client snapshots attached to one instant-chat user message.
+ *
+ * Context is separate from visible message text and does not grant account access.
+ * The compact JSON representation must not exceed 64 KiB.
+ */
+export interface TurnContext {
+  /**
+   * One to four snapshots. Each snapshot's data may contain at most 32 levels of
+   * nesting.
+   */
+  items: Array<ContextItem>;
+}
+
 export interface ThreadCreateMessageResponse extends Shared.BaseResponse {
   /**
    * Response payload for continuing a thread with a new message.
@@ -322,7 +362,7 @@ export interface ThreadGetMessagesResponse extends Shared.BaseResponse {
 
 export interface ThreadGetThreadByIDResponse extends Shared.BaseResponse {
   /**
-   * Thread metadata returned by list/get thread endpoints.
+   * Thread metadata.
    */
   data: Thread;
 }
@@ -339,23 +379,44 @@ export interface ThreadGetThreadsResponse extends Shared.BaseResponse {
 }
 
 export interface ThreadCreateMessageParams {
-  account_id: number;
-
   text: string;
 
+  /**
+   * Selected account for creation or the first account-linked turn. Omit for an
+   * unlinked conversation. An existing account link remains authoritative even when
+   * another account is selected.
+   */
+  account_id?: number | null;
+
   capabilities?: Array<'PREFILL_ORDER' | 'OPEN_CHART' | 'OPEN_SCREENER' | 'OPEN_ENTITLEMENT_CONSENT'>;
+
+  /**
+   * Snapshots for this instant-chat message. Omission does not remove earlier
+   * attachments.
+   */
+  context?: TurnContext | null;
 }
 
 export interface ThreadCreateThreadParams {
-  account_id: number;
-
   /**
    * Thread creation mode.
    */
   type: 'instant' | 'deep_insights';
 
+  /**
+   * Selected account for creation or the first account-linked turn. Omit for an
+   * unlinked conversation. An existing account link remains authoritative even when
+   * another account is selected.
+   */
+  account_id?: number | null;
+
   capabilities?: Array<'PREFILL_ORDER' | 'OPEN_CHART' | 'OPEN_SCREENER' | 'OPEN_ENTITLEMENT_CONSENT'>;
 
+  /**
+   * Snapshots for the first instant-chat message. Omit to attach no new context.
+   */
+  context?: TurnContext | null;
+
   /**
    * Deep-insights target payload.
    */
@@ -382,9 +443,11 @@ export namespace ThreadCreateThreadParams {
 
 export interface ThreadGetMessagesParams {
   /**
-   * Account ID for the request
+   * Lists only conversations for this account, or unlinked conversations when
+   * omitted. Other reads authorize the resource's linked account. Omit when no
+   * account is selected; empty values and the string null are invalid.
    */
-  account_id: number;
+  account_id?: number;
 
   /**
    * The number of items to return per page. Only used when page_token is not
@@ -401,23 +464,29 @@ export interface ThreadGetMessagesParams {
 
 export interface ThreadGetThreadByIDParams {
   /**
-   * Account ID for the request
+   * Lists only conversations for this account, or unlinked conversations when
+   * omitted. Other reads authorize the resource's linked account. Omit when no
+   * account is selected; empty values and the string null are invalid.
    */
-  account_id: number;
+  account_id?: number;
 }
 
 export interface ThreadGetThreadResponseParams {
   /**
-   * Account ID for the request
+   * Lists only conversations for this account, or unlinked conversations when
+   * omitted. Other reads authorize the resource's linked account. Omit when no
+   * account is selected; empty values and the string null are invalid.
    */
-  account_id: number;
+  account_id?: number;
 }
 
 export interface ThreadGetThreadsParams {
   /**
-   * Account ID for the request
+   * Lists only conversations for this account, or unlinked conversations when
+   * omitted. Other reads authorize the resource's linked account. Omit when no
+   * account is selected; empty values and the string null are invalid.
    */
-  account_id: number;
+  account_id?: number;
 
   /**
    * The number of items to return per page. Only used when page_token is not
@@ -434,6 +503,7 @@ export interface ThreadGetThreadsParams {
 
 export declare namespace Threads {
   export {
+    type ContextItem as ContextItem,
     type CreateMessageResponse as CreateMessageResponse,
     type CreateThreadResponse as CreateThreadResponse,
     type Message as Message,
@@ -444,6 +514,7 @@ export declare namespace Threads {
     type MessageRole as MessageRole,
     type Thread as Thread,
     type ThreadList as ThreadList,
+    type TurnContext as TurnContext,
     type ThreadCreateMessageResponse as ThreadCreateMessageResponse,
     type ThreadCreateThreadResponse as ThreadCreateThreadResponse,
     type ThreadGetMessagesResponse as ThreadGetMessagesResponse,

package/src/resources/v1/orders.ts

@@ -213,6 +213,12 @@ export interface Execution {
    */
   underlying_instrument_id?: string | null;
 
+  /**
+   * Type of the underlying instrument, alongside `underlying_instrument_id`. When a
+   * null/undefined value is observed, it indicates it does not apply.
+   */
+  underlying_instrument_type?: V1API.SecurityType | null;
+
   /**
    * Venue where this fill occurred, as reported by that venue. Distinct from an
    * order's `venue`, which is the routing destination. Codes are not normalized, so
@@ -231,7 +237,7 @@ export type ExecutionList = Array<Execution>;
 export type InstrumentIDOrSymbol = string;
 
 /**
- * Request to submit a new order (PlaceOrderRequest from spec)
+ * Request to submit a new order
  */
 export interface NewOrderRequest {
   /**
@@ -300,6 +306,13 @@ export interface NewOrderRequest {
    */
   stop_price?: string | null;
 
+  /**
+   * Optional execution strategy. Omit to use standard routing. One of `SOR`, `VWAP`,
+   * or `TWAP`. Supported only on `MARKET` and `LIMIT` orders with `DAY`
+   * time-in-force, and not supported on OTC common-stock orders.
+   */
+  strategy?: OrderStrategy | null;
+
   /**
    * Trading symbol. For equities, use the ticker symbol (e.g., "TSLA"). For options,
    * use the OSI symbol (e.g., "TSLA 250117C00190000"). Either `symbol` or
@@ -461,6 +474,11 @@ export interface Order {
    */
   stop_price?: string | null;
 
+  /**
+   * The execution strategy the order was submitted with, if any.
+   */
+  strategy?: Order.Strategy;
+
   /**
    * Trading symbol. `null` when the order has no single resolvable instrument. When
    * a null/undefined value is observed, it indicates it does not apply.
@@ -492,14 +510,18 @@ export interface Order {
   trailing_stop_px?: string | null;
 
   /**
-   * Trailing watermark price for trailing orders When a null/undefined value is
-   * observed, it indicates it does not apply.
+   * Trailing watermark price for trailing orders. Strategy-computed, so it is absent
+   * on the order-submission acknowledgement and only appears once fetched via the
+   * order fetch or list endpoints. When a null/undefined value is observed, it
+   * indicates it does not apply.
    */
   trailing_watermark_px?: string | null;
 
   /**
-   * Trailing watermark timestamp for trailing orders When a null/undefined value is
-   * observed, it indicates it does not apply.
+   * Trailing watermark timestamp for trailing orders. Strategy-computed, so it is
+   * absent on the order-submission acknowledgement and only appears once fetched via
+   * the order fetch or list endpoints. When a null/undefined value is observed, it
+   * indicates it does not apply.
    */
   trailing_watermark_ts?: string | null;
 
@@ -511,6 +533,36 @@ export interface Order {
    * apply.
    */
   underlying_instrument_id?: string | null;
+
+  /**
+   * Type of the underlying instrument, alongside `underlying_instrument_id`. When a
+   * null/undefined value is observed, it indicates it does not apply.
+   */
+  underlying_instrument_type?: V1API.SecurityType | null;
+}
+
+export namespace Order {
+  /**
+   * The execution strategy the order was submitted with, if any.
+   */
+  export interface Strategy {
+    /**
+     * Execution strategy type.
+     */
+    type: string;
+
+    /**
+     * UTC timestamp (RFC 3339) at which execution ends.
+     */
+    end_at?: string;
+
+    /**
+     * UTC timestamp (RFC 3339) at which execution begins.
+     */
+    start_at?: string;
+
+    [k: string]: unknown;
+  }
 }
 
 export type OrderList = Array<Order>;
@@ -537,6 +589,70 @@ export type OrderStatus =
   | 'CALCULATED'
   | 'OTHER';
 
+/**
+ * Optional execution strategy controlling how the order is worked in the market.
+ * Omit to use standard routing. One of `SOR`, `VWAP`, or `TWAP`.
+ */
+export type OrderStrategy = OrderStrategy.Type | OrderStrategy.UnionMember1 | OrderStrategy.UnionMember2;
+
+export namespace OrderStrategy {
+  /**
+   * Smart Order Router. Routes the order to the best available venue(s).
+   */
+  export interface Type {
+    /**
+     * Execution strategy type.
+     */
+    type: 'SOR';
+  }
+
+  /**
+   * Volume-Weighted Average Price. Works the order to track the volume-weighted
+   * average price over the execution window.
+   */
+  export interface UnionMember1 {
+    /**
+     * Execution strategy type.
+     */
+    type: 'VWAP';
+
+    /**
+     * UTC timestamp (RFC 3339) by which to finish working the order. Defaults to
+     * market close.
+     */
+    end_at?: string;
+
+    /**
+     * UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the
+     * time the order is received.
+     */
+    start_at?: string;
+  }
+
+  /**
+   * Time-Weighted Average Price. Spreads execution evenly across the execution
+   * window.
+   */
+  export interface UnionMember2 {
+    /**
+     * Execution strategy type.
+     */
+    type: 'TWAP';
+
+    /**
+     * UTC timestamp (RFC 3339) by which to finish working the order. Defaults to
+     * market close.
+     */
+    end_at?: string;
+
+    /**
+     * UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the
+     * time the order is received.
+     */
+    start_at?: string;
+  }
+}
+
 /**
  * Order type
  */
@@ -603,8 +719,7 @@ export type RequestOrderType =
   | 'TRAILING_STOP_LIMIT';
 
 /**
- * Position effect for a multileg strategy leg: client-attested open/close intent.
- * Required on every leg of a multileg order submission.
+ * Client-attested open/close intent for an order.
  */
 export type RequestPositionEffect = 'OPEN' | 'CLOSE';
 
@@ -930,6 +1045,7 @@ export declare namespace Orders {
     type Order as Order,
     type OrderList as OrderList,
     type OrderStatus as OrderStatus,
+    type OrderStrategy as OrderStrategy,
     type OrderType as OrderType,
     type QueueState as QueueState,
     type ReplaceOrderRequest as ReplaceOrderRequest,

package/src/resources/v1/positions.ts

@@ -270,6 +270,12 @@ export interface Position {
    */
   underlying_instrument_id?: string | null;
 
+  /**
+   * Type of the underlying instrument, alongside `underlying_instrument_id` When a
+   * null/undefined value is observed, it indicates it does not apply.
+   */
+  underlying_instrument_type?: V1API.SecurityType | null;
+
   /**
    * The total unrealized profit or loss for this position based on current market
    * value When a null/undefined value is observed, it indicates that there is no
@@ -343,6 +349,16 @@ export interface PositionInstruction {
    */
   created_at?: string | null;
 
+  /**
+   * Machine-readable counterpart to `rejection_reason`: a stable reason code plus
+   * params, present on every rejected row that has a `rejection_reason` — on submit,
+   * cancel, get, and list alike. Branch on `rejection.reason` instead of parsing
+   * `rejection_reason`. Forward-only: instructions rejected before this field
+   * shipped may carry only `rejection_reason`. When a null/undefined value is
+   * observed, it indicates it does not apply.
+   */
+  rejection?: PositionInstructionRejection | null;
+
   /**
    * Human-readable explanation populated on any non-success terminal status —
    * `REJECTED` or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the
@@ -366,6 +382,44 @@ export interface PositionInstruction {
 
 export type PositionInstructionList = Array<PositionInstruction>;
 
+/**
+ * Machine-readable detail for a rejected position instruction.
+ *
+ * Present on every rejected row that carries a `rejection_reason`, across the full
+ * lifecycle — submit, cancel, get, and list. Branch on `reason` for programmatic
+ * handling and template your own copy from `metadata`; `rejection_reason` remains
+ * the human-readable fallback. Forward-only: instructions rejected before this
+ * field shipped may carry only `rejection_reason`.
+ */
+export interface PositionInstructionRejection {
+  /**
+   * Namespacing domain of the `reason` code — `com.clearstreet.oems.exercise` for
+   * reasons OEMS validates, `com.clearstreet.oems.clearing` for clearing-owned
+   * reasons.
+   */
+  domain: string;
+
+  /**
+   * Reason-specific parameters as a string→string map. Which keys are present
+   * depends on `reason`:
+   *
+   * - `INSUFFICIENT_POSITION` → `available`, `requested`
+   * - `DNE_NOT_ON_EXPIRY` / `CEA_NOT_ON_EXPIRY` → `expiry`, `business_date`
+   * - `EXERCISE_PAST_CUTOFF` → `cutoff_time`
+   * - `DUPLICATE_INSTRUCTION` → `existing_id`
+   *
+   * Empty for reasons that carry no parameters. New keys may be added over time, so
+   * treat unknown keys leniently.
+   */
+  metadata: { [key: string]: string };
+
+  /**
+   * Stable, machine-readable reason code, e.g. `DNE_NOT_ON_EXPIRY`,
+   * `INSUFFICIENT_POSITION`, `OPTIONS_LEVEL_EXCEEDED`, `EXERCISE_PAST_CUTOFF`.
+   */
+  reason: string;
+}
+
 /**
  * Lifecycle status of a position instruction.
  *
@@ -550,6 +604,7 @@ export declare namespace Positions {
     type Position as Position,
     type PositionInstruction as PositionInstruction,
     type PositionInstructionList as PositionInstructionList,
+    type PositionInstructionRejection as PositionInstructionRejection,
     type PositionInstructionStatus as PositionInstructionStatus,
     type PositionInstructionType as PositionInstructionType,
     type PositionList as PositionList,

package/src/resources/v1/screener.ts

@@ -158,8 +158,8 @@ export class Screener extends APIResource {
    * `instrument_id` column is always prepended. Metadata carries `total_items`,
    * `total_pages`, and `next_page_token` for paging.
    *
-   * Due to the volatility of screener responses we recommend reconciling page
-   * results since results can shuffle between calls.
+   * Screener results can shuffle between calls; reconcile by re-checking rows across
+   * pages rather than assuming stable ordering.
    *
    * @example
    * ```ts
@@ -516,7 +516,7 @@ export interface ModifierDef {
   args: Array<ModifierArg>;
 
   /**
-   * `"ADD"` or `"SUBTRACT"`.
+   * The modifier operation name: one of `"ADD"` or `"SUBTRACT"`.
    */
   name: string;
 }