@clear-street/clearstreet 0.100.0 → 0.102.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

@@ -172,7 +172,8 @@ export interface Execution {
   order_id: string;
 
   /**
-   * Filled quantity.
+   * Filled quantity. For a strategy-level multileg fill this is the net strategy
+   * quantity, not a per-leg quantity.
    */
   quantity: string;
 
@@ -187,9 +188,9 @@ export interface Execution {
   transaction_time: string;
 
   /**
-   * Unique instrument identifier. `null` when this fill has no single resolvable
-   * instrument. When a null/undefined value is observed, it indicates it does not
-   * apply.
+   * Unique instrument identifier. `null` when this is a strategy-level multileg fill
+   * whose legs are reported individually in `legs[]`. When a null/undefined value is
+   * observed, it indicates it does not apply.
    */
   instrument_id?: string | null;
 
@@ -200,8 +201,9 @@ export interface Execution {
   price?: string | null;
 
   /**
-   * Trading symbol. `null` when this fill has no single resolvable instrument. When
-   * a null/undefined value is observed, it indicates it does not apply.
+   * Trading symbol. `null` when this is a strategy-level multileg fill whose legs
+   * are reported individually in `legs[]`. When a null/undefined value is observed,
+   * it indicates it does not apply.
    */
   symbol?: string | null;
 
@@ -306,6 +308,13 @@ export interface NewOrderRequest {
    */
   stop_price?: string | null;
 
+  /**
+   * Optional execution strategy. One of `SOR`, `VWAP`, or `TWAP`. Defaults to `SOR`.
+   * `VWAP` and `TWAP` are supported only on `MARKET` and `LIMIT` orders with `DAY`
+   * time-in-force, and are 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
@@ -424,15 +433,16 @@ export interface Order {
   extended_hours?: boolean | null;
 
   /**
-   * Instrument identifier for the traded instrument. `null` when the order has no
-   * single resolvable instrument. When a null/undefined value is observed, it
-   * indicates it does not apply.
+   * Instrument identifier for the traded instrument. `null` when the order is a
+   * multileg strategy whose legs are reported individually in `legs[]`. When a
+   * null/undefined value is observed, it indicates it does not apply.
    */
   instrument_id?: string | null;
 
   /**
-   * Type of security. `null` when the order has no single resolvable instrument.
-   * When a null/undefined value is observed, it indicates it does not apply.
+   * Type of security. `null` when the order is a multileg strategy whose legs are
+   * reported individually in `legs[]`. When a null/undefined value is observed, it
+   * indicates it does not apply.
    */
   instrument_type?: V1API.SecurityType | null;
 
@@ -468,8 +478,14 @@ export interface Order {
   stop_price?: string | null;
 
   /**
-   * Trading symbol. `null` when the order has no single resolvable instrument. When
-   * a null/undefined value is observed, it indicates it does not apply.
+   * The execution strategy the order was submitted with, if any.
+   */
+  strategy?: Order.Strategy;
+
+  /**
+   * Trading symbol. `null` when the order is a multileg strategy whose legs are
+   * reported individually in `legs[]`. When a null/undefined value is observed, it
+   * indicates it does not apply.
    */
   symbol?: string | null;
 
@@ -529,6 +545,30 @@ export interface Order {
   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>;
 
 /**
@@ -553,6 +593,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
  */
@@ -870,26 +974,40 @@ export interface OrderGetOrdersParams {
 export namespace OrderGetOrdersParams {
   export interface UpdatedAt {
     /**
-     * > **Alpha** — this parameter is experimental and may change or be removed at any
-     * > time.
+     * Return only rows where `updated_at` is strictly after the given value. A bare
+     * `YYYY-MM-DD` date expands to the end of that day (UTC), so this matches from the
+     * start of the following day. See
+     * [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters)
+     * for accepted formats, bare-date expansion, and combining bounds. Returns 400 if
+     * the resulting range is inverted.
      */
     gt?: string;
 
     /**
-     * > **Alpha** — this parameter is experimental and may change or be removed at any
-     * > time.
+     * Return only rows where `updated_at` is on or after the given value. A bare
+     * `YYYY-MM-DD` date expands to the start of that day (UTC). See
+     * [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters)
+     * for accepted formats, bare-date expansion, and combining bounds. Returns 400 if
+     * the resulting range is inverted.
      */
     gte?: string;
 
     /**
-     * > **Alpha** — this parameter is experimental and may change or be removed at any
-     * > time.
+     * Return only rows where `updated_at` is strictly before the given value. A bare
+     * `YYYY-MM-DD` date expands to the start of that day (UTC). See
+     * [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters)
+     * for accepted formats, bare-date expansion, and combining bounds. Returns 400 if
+     * the resulting range is inverted.
      */
     lt?: string;
 
     /**
-     * > **Alpha** — this parameter is experimental and may change or be removed at any
-     * > time.
+     * Return only rows where `updated_at` is on or before the given value. A bare
+     * `YYYY-MM-DD` date expands to the end of that day (UTC), so this matches through
+     * the end of that day. See
+     * [Range filters](https://docs.clearstreet.com/guides/api-fundamentals#range-filters)
+     * for accepted formats, bare-date expansion, and combining bounds. Returns 400 if
+     * the resulting range is inverted.
      */
     lte?: string;
   }
@@ -945,6 +1063,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

@@ -350,12 +350,11 @@ 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.
+   * Machine-readable counterpart to `rejection_reason`: a stable reason code,
+   * human-readable `description`, and params, present on every rejected row — on
+   * submit, cancel, get, and list alike. Branch on `rejection.reason` and read
+   * `rejection.description` instead of the top-level `rejection_reason`. When a
+   * null/undefined value is observed, it indicates it does not apply.
    */
   rejection?: PositionInstructionRejection | null;
 
@@ -385,13 +384,17 @@ 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`.
+ * Present on every rejected row, across the full lifecycle — submit, cancel, get,
+ * and list. Branch on `reason` for programmatic handling and template your own
+ * copy from `metadata`, or show `description` directly.
  */
 export interface PositionInstructionRejection {
+  /**
+   * Human-readable explanation of the rejection. Duplicates the top-level
+   * `rejection_reason`; prefer this field.
+   */
+  description: string;
+
   /**
    * Namespacing domain of the `reason` code — `com.clearstreet.oems.exercise` for
    * reasons OEMS validates, `com.clearstreet.oems.clearing` for clearing-owned