snaptrade-typescript-sdk 11.0.0-canary.0 → 11.0.0

package/README.md

@@ -6,7 +6,7 @@
 
 Connect brokerage accounts to your app for live positions and trading
 
-[![npm](https://img.shields.io/badge/npm-v11.0.0--canary.0-blue)](https://www.npmjs.com/package/snaptrade-typescript-sdk/v/11.0.0-canary.0)
+[![npm](https://img.shields.io/badge/npm-v11.0.0-blue)](https://www.npmjs.com/package/snaptrade-typescript-sdk/v/11.0.0)
 [![More Info](https://img.shields.io/badge/More%20Info-Click%20Here-orange)](https://snaptrade.com/)
 
 </div>
@@ -124,7 +124,10 @@ yarn add snaptrade-typescript-sdk
 ## Getting Started<a id="getting-started"></a>
 
 ```typescript
+// Commercial API key example: registers a SnapTrade user and uses userId/userSecret.
 const { Snaptrade, SnaptradeAuth } = require("snaptrade-typescript-sdk");
+const { randomUUID } = require("crypto");
+const readline = require("readline");
 
 async function main() {
   // 1) Initialize a client with your clientID and consumerKey.
@@ -140,32 +143,51 @@ async function main() {
   console.log("status:", status.data);
 
   // 3) Create a new user on SnapTrade
-  const userId = uuid();
-  const { userSecret } = (
+  const userId = randomUUID();
+  const registerResponse = (
     await snaptrade.authentication.registerSnapTradeUser({
       userId,
     })
   ).data;
+  console.log("registerResponse:", registerResponse);
 
   // Note: A user secret is only generated once. It's required to access
   // resources for certain endpoints.
-  console.log("userSecret:", userSecret);
+  const userSecret = registerResponse.userSecret;
 
   // 4) Get a redirect URI. Users will need this to connect
-  const data = (
+  // their brokerage to the SnapTrade server.
+  const redirectURI = (
     await snaptrade.authentication.loginSnapTradeUser({ userId, userSecret })
   ).data;
-  if (!("redirectURI" in data)) throw Error("Should have gotten redirect URI");
-  console.log("redirectURI:", data.redirectURI);
+  console.log("redirectURI:", redirectURI);
 
-  // 5) Obtaining account holdings data
-  const holdings = (
-    await snaptrade.accountInformation.getAllUserHoldings({
+  await waitForEnter(
+    "Open the link in your browser. When done logging in, press Enter to continue..."
+  );
+
+  // 5) Get a list of connections
+  const connections = (
+    await snaptrade.connections.listBrokerageAuthorizations({
       userId,
       userSecret,
     })
   ).data;
-  console.log("holdings:", holdings);
+  console.log("connections:", connections);
+
+  // 6) Get a list of accounts for the first connection, if available
+  if (!Array.isArray(connections) || connections.length === 0) {
+    console.log("No brokerage connections found for the user.");
+  } else {
+    const accounts = (
+      await snaptrade.connections.listBrokerageAuthorizationAccounts({
+        authorizationId: connections[0].id,
+        userId,
+        userSecret,
+      })
+    ).data;
+    console.log("accounts:", accounts);
+  }
 
   // 6) Deleting a user
   const deleteResponse = (
@@ -174,26 +196,17 @@ async function main() {
   console.log("deleteResponse:", deleteResponse);
 }
 
-// Should be replaced with function to get user ID
-function getUserId() {
-  var d = new Date().getTime(); //Timestamp
-  var d2 =
-    (typeof performance !== "undefined" &&
-      performance.now &&
-      performance.now() * 1000) ||
-    0; //Time in microseconds since page-load or 0 if unsupported
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
-    var r = Math.random() * 16; //random number between 0 and 16
-    if (d > 0) {
-      //Use timestamp until depleted
-      r = (d + r) % 16 | 0;
-      d = Math.floor(d / 16);
-    } else {
-      //Use microseconds since page-load if supported
-      r = (d2 + r) % 16 | 0;
-      d2 = Math.floor(d2 / 16);
-    }
-    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+function waitForEnter(prompt) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
   });
 }
 
@@ -689,13 +702,10 @@ const getUserHoldingsResponse =
 
 
 ### `snaptrade.accountInformation.listUserAccounts`<a id="snaptradeaccountinformationlistuseraccounts"></a>
-![Deprecated](https://img.shields.io/badge/deprecated-yellow)
-
-**Deprecated, please use the [list accounts for a connection endpoint](/reference/Connections/Connections_listBrokerageAuthorizationAccounts) instead.**
 
 Returns all brokerage accounts across all connections known to SnapTrade for the authenticated user.
 
-This endpoint returns Daily data regardless of the customer's plan. Daily data is cached and refreshed once a day. Exact refresh timing may vary by brokerage. To get real-time data on Pay as you Go / Real-time, use the connection-scoped endpoint linked above. Customers on Pay as you Go / Daily can force a refresh with the [manual refresh endpoint](/reference/Connections/Connections_refreshBrokerageAuthorization).
+This endpoint returns Daily data regardless of the customer's plan. Daily data is cached and refreshed once a day, which makes this endpoint fast and well-suited to listing accounts across all of a user's connections in a single call. Exact refresh timing may vary by brokerage. To get real-time data on Pay as you Go / Real-time, use the [list accounts for a connection endpoint](/reference/Connections/Connections_listBrokerageAuthorizationAccounts). Customers on Pay as you Go / Daily can force a refresh with the [manual refresh endpoint](/reference/Connections/Connections_refreshBrokerageAuthorization).
 
 
 #### 🛠️ Usage<a id="🛠️-usage"></a>
@@ -1124,7 +1134,7 @@ Trigger a holdings update for all accounts under this connection. Updates will b
 This endpoint will also trigger a transaction sync for the past day if one has not yet occurred.
 
 **Because of the cost of refreshing a connection, each call to this endpoint incurs an additional charge. You can find the exact cost for your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing)**
-**Please note this endpoint is disabled for Personal and Pay as you Go Real-time plans. Real-time plans do not benefit from this feature since data is refreshed when calls are made**
+**Please note this endpoint is disabled for Real-time plans (Personal and Pay as you go) unless the connection is delayed. Real-time connections do not benefit from this feature since data is refreshed when calls are made. Refer to the `data_freshness_mode` field on a connection to determine this.**
 
 
 #### 🛠️ Usage<a id="🛠️-usage"></a>
@@ -1223,6 +1233,8 @@ Returns a list of session events associated with a user.
 ```typescript
 const sessionEventsResponse = await snaptrade.connections.sessionEvents({
   partnerClientId: "SNAPTRADETEST",
+  userId:
+    "917c8734-8470-4a3e-a18f-57c3f2ee6631,65e839a3-9103-4cfb-9b72-2071ef80c5f2",
   sessionId:
     "917c8734-8470-4a3e-a18f-57c3f2ee6631,65e839a3-9103-4cfb-9b72-2071ef80c5f2",
 });
@@ -1232,6 +1244,10 @@ const sessionEventsResponse = await snaptrade.connections.sessionEvents({
 
 ##### partnerClientId: `string`<a id="partnerclientid-string"></a>
 
+##### userId: `string`<a id="userid-string"></a>
+
+Optional comma separated list of user IDs used to filter the request on specific users
+
 ##### sessionId: `string`<a id="sessionid-string"></a>
 
 Optional comma separated list of session IDs used to filter the request on specific users
@@ -1292,6 +1308,7 @@ This endpoint requires `userId` and `userSecret` in addition to the partner sign
 const addSubscriptionResponse =
   await snaptrade.experimentalEndpoints.addSubscription({
     account_id: "917c8734-8470-4a3e-a18f-57c3f2ee6631",
+    check_interval_seconds: 300,
   });
 ```
 
@@ -1301,6 +1318,10 @@ const addSubscriptionResponse =
 
 Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade.
 
+##### check_interval_seconds: `number`<a id="check_interval_seconds-number"></a>
+
+How often the subscribed account should be checked for new trades. Must match an active Trade Detection plan.
+
 #### 🔄 Return<a id="🔄-return"></a>
 
 [TradeDetectionSubscription](./models/trade-detection-subscription.ts)
@@ -1502,7 +1523,7 @@ const listSubscriptionsResponse =
 
 Returns a list of option positions in the specified account. For stock/ETF/crypto/mutual fund positions, please use the [positions endpoint](/reference/Account%20Information/AccountInformation_getUserAccountPositions).
 
-This endpoint is deprecatd. Consider using the newer [unified positions endpoint](/reference/Account%20Information/AccountInformation_getAllAccountPositions). This will allow you to get both equity and option positions in a single call, as well as additional asset classes such as futures.
+This endpoint is deprecated. Consider using the newer [unified positions endpoint](/reference/Account%20Information/AccountInformation_getAllAccountPositions). This will allow you to get both equity and option positions in a single call, as well as additional asset classes such as futures.
 
 Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
   - If you do, this endpoint returns real-time data.
@@ -2284,8 +2305,9 @@ Number of shares for the order. This can be a decimal for fractional orders. Mus
 
 ### `snaptrade.trading.placeComplexOrder`<a id="snaptradetradingplacecomplexorder"></a>
 
-Places a complex conditional order (OCO, OTO, or OTOCO). Disabled by default — contact support to enable.
+Places a complex conditional order (OCO, OTO, or OTOCO).
 Only supported on certain brokerages.
+Please refer to the [brokerage trading support page](https://support.snaptrade.com/brokerages) for details on which brokerages support complex orders and which types they support.
 
 - **OCO** (One Cancels the Other): Two peer orders; when one fills the other is cancelled.
 - **OTO** (One Triggers the Other): A trigger order that, when filled, activates a conditional order.
@@ -2313,7 +2335,7 @@ const placeComplexOrderResponse = await snaptrade.trading.placeComplexOrder({
       stop: 29.5,
     },
   ],
-  client_order_id: "my-order-123",
+  client_order_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 ```
 
@@ -2331,9 +2353,7 @@ The orders that make up the complex order. Required counts and roles per type: -
 
 The ID of the account to execute the trade on.
 
-##### client_order_id: `string`<a id="client_order_id-string"></a>
-
-An optional client-provided identifier for this complex order. Passed through to the brokerage and returned in the response.
+##### client_order_id: [`string`](./models/model-string.ts)<a id="client_order_id-stringmodelsmodel-stringts"></a>
 
 #### 🔄 Return<a id="🔄-return"></a>
 
@@ -2445,9 +2465,11 @@ const placeForceOrderResponse = await snaptrade.trading.placeForceOrder({
   order_type: "Market",
   time_in_force: "Day",
   trading_session: "REGULAR",
+  expiry_date: "2026-08-21T23:27:55.027Z",
   price: 31.33,
   stop: 31.33,
   units: 10.5,
+  client_order_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 ```
 
@@ -2465,9 +2487,9 @@ The action describes the intent or side of a trade. This is either `BUY` or `SEL
 
 The type of order to place.  - For `Limit` and `StopLimit` orders, the `price` field is required. - For `Stop` and `StopLimit` orders, the `stop` field is required. 
 
-##### time_in_force: [`TimeInForceStrict`](./models/time-in-force-strict.ts)<a id="time_in_force-timeinforcestrictmodelstime-in-force-strictts"></a>
+##### time_in_force: [`ManualTradePlaceTimeInForceStrict`](./models/manual-trade-place-time-in-force-strict.ts)<a id="time_in_force-manualtradeplacetimeinforcestrictmodelsmanual-trade-place-time-in-force-strictts"></a>
 
-The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. Here are the supported values:   - `Day` - Day. The order is valid only for the trading day on which it is placed.   - `GTC` - Good Til Canceled. The order is valid until it is executed or canceled.   - `FOK` - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.   - `IOC` - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled. 
+The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. Here are the supported values:   - `Day` - Day. The order is valid only for the trading day on which it is placed.   - `GTC` - Good Til Canceled. The order is valid until it is executed or canceled.   - `FOK` - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.   - `IOC` - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled.   - `GTD` - Good Til Date. The order is valid until `expiry_date`, which is required. Not available for market orders. GTD orders are only available on certain brokerages. Visit https://support.snaptrade.com/brokerages for brokerage support. 
 
 ##### universal_symbol_id: [`string`](./models/model-string.ts)<a id="universal_symbol_id-stringmodelsmodel-stringts"></a>
 
@@ -2481,6 +2503,10 @@ The security\\\'s trading ticker symbol. If \\\'symbol\\\' is provided, then \\\
 
 The trading session for the order. This field indicates which market session the order will be placed in. This is only available for certain brokerages. Defaults to REGULAR. Here are the supported values:   - `REGULAR` - Regular trading hours.   - `EXTENDED` - Extended trading hours. 
 
+##### expiry_date: `string`<a id="expiry_date-string"></a>
+
+Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format indicating when the order expires. Required when `time_in_force` is `GTD`. Include a timezone offset or `Z` for UTC; if no timezone is provided, UTC is assumed. GTD orders are only available on certain brokerages. Visit https://support.snaptrade.com/brokerages for brokerage support.
+
 ##### price: `number`<a id="price-number"></a>
 
 The limit price for `Limit` and `StopLimit` orders.
@@ -2495,6 +2521,8 @@ For Equity orders, this represents the number of shares for the order. This can
 
 ##### notional_value: [`ManualTradeFormNotionalValue`](./models/manual-trade-form-notional-value.ts)<a id="notional_value-manualtradeformnotionalvaluemodelsmanual-trade-form-notional-valuets"></a>
 
+##### client_order_id: [`string`](./models/model-string.ts)<a id="client_order_id-stringmodelsmodel-stringts"></a>
+
 #### 🔄 Return<a id="🔄-return"></a>
 
 [AccountOrderRecord](./models/account-order-record.ts)