@stxapp/stx-typescript 0.9.0-alpha.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,27 +1,80 @@
1
1
  # Changelog
2
2
 
3
- ## 0.9.0-alpha.1 (2026-10-10)
3
+ ## 0.10.0 (2026-11-11)
4
4
 
5
- Alpha: install with `npm install @stxapp/stx-typescript@alpha`. The new API may change before beta.
5
+ Breaking for anyone passing a geolocation option or using the location check: API key requests are now located from your connection, so the SDK no longer sends or reads geolocation data and no longer has its own location check.
6
6
 
7
- Sign in with your STX account, and connect your STX account:
7
+ - The `geoLocation` option is gone from `new STX()`, `placeOrder()`, `placeOrders()`, `cancelOrder()`, `cancelOrders()`, `cancelAllOrders()`, `geoCheck()`, `comboPlayer()` and `comboMaker()`, along with the `GeoOption` and `GeoLocationProvider` types and `STX.geoLocation`. A `geoLocation` key on a `placeOrders()` order is an unknown field. Remove the option; nothing else changes.
8
+ - `ComboJoinReply.next_geolocation_at`, `nextGeolocationAt` on the combo sessions, and `GeoCheckResult.sentPacket` are gone. The exchange may still send `next_geolocation_at`, and the SDK ignores it.
9
+ - `geoCheck()`, `STXGeoLocationException`, `geoRejection()` and the `GeoRejection` and `GeoCheckResult` types are gone. The exchange still refuses order requests from outside the region (422), and that refusal is now a plain `STXRejectedException` with the exchange's message. Catch `STXRejectedException` instead, and drop any `geoCheck()` call: the exchange checks every order write itself. See https://docs.stxapp.io/concepts/us-and-canada/
8
10
 
9
- - `createConnect()` in `@stxapp/stx-typescript/oauth` runs the OpenID Connect sign-in from your server. `start()` returns the redirect (optionally straight to Google, Apple or X, with a login hint), `finish()` exchanges the code and verifies the ID token, `refresh()` keeps the connection, `userInfo()` reads the member's claims again, and `disconnect()` ends the connection at STX.
10
- - `OAuthClient.authorizationUrl()` and `beginAuthorization()` take `connection` and `loginHint`, for an app with its own login that connects a member's STX account.
11
- - Two typed errors when the member does not come back connected: `STXAccountPendingException` (the member's STX account is still being verified) and `STXAccessDeniedException` (the member declined, or their account cannot be connected). Both extend `STXOAuthException`, so existing `catch` blocks keep working.
12
- - A refresh or code exchange refused because the member's account is still being verified also throws `STXAccountPendingException` (`errorReason` is `account_pending`), and `memberClient()` keeps the stored tokens: the same refresh token works once the member is verified. A refresh refused because the connection ended still throws `STXGrantRevokedException` and deletes them.
13
- - `STXOAuthException.errorReason` carries the narrower reason when the exchange sends one.
14
- - An error on the callback is reported only for a sign-in your app started: `finish()`, `completeAuthorization()` and `readCallback()` check the `state` before the error, so a callback with a missing or unknown `state` throws `invalid_state` whatever error it carries. `completeAuthorization()` and `readCallback()` also use the `state` up, so a replayed callback throws `invalid_state`; with `finish()` the saved sign-in is yours, so delete it after the first callback.
15
- - `TokenSet.idToken` carries the ID token when `openid` is granted.
11
+ WebSocket reliability, for cancel-on-disconnect in particular:
12
+
13
+ - Cancel-on-disconnect pings at a third of the granted `ping_timeout` instead of 60%, so two pings can be lost before the exchange cancels your orders. At 60%, a client stall of about 2 seconds could let a 5 second timeout fire on a healthy connection.
14
+ - When the exchange closes or errors one channel while the socket stays up (for example, its cancel-on-disconnect timer fired), the client rejoins that channel with its filters and cancel-on-disconnect, then calls `onReconnect` so you can resync. `ws.channelRejoins` counts these. A close meant for an earlier join of the channel is ignored.
15
+ - Each channel is joined once per connection, even when joins or rejoins overlap. Before, two overlapping calls for one topic, or a rejoin racing a reconnect, could join it twice, and the exchange answers a second join by closing the first. Joining a channel while the socket is reconnecting now waits for that reconnect instead of opening a second socket.
16
+ - A `market(marketId)` channel that the exchange closes after the market results or is voided now ends instead of rejoining.
17
+ - If restoring a channel's `marketUpdates` watches fails after a rejoin, only the watches are retried, without joining again.
18
+ - An `onReconnect` that throws is logged and no longer drops the socket it just reconnected.
19
+ - A refused socket handshake (for example an expired OAuth token, answered 401 or 403) now only rejects `connect()` with an `STXTransportException` carrying the status. Before, closing the refused socket also raised an unhandled "WebSocket was closed before the connection was established" error on Node and on Bun 1.4.4 and later, which could stop the process and kept the OAuth token refresh from recovering.
20
+
21
+ Loyalty program:
22
+
23
+ - `loyalty()` and `iterLoyalty()` throw `STXNotAvailableException` (feature `loyalty`) where the exchange has the loyalty program switched off. The exchange answers `GET /api/v1/portfolio/loyalty` there with 404 `{"error": "Loyalty program is not enabled"}`, which was an `STXNotFoundException` before. US demo and US QA have it off since 2026-11-07.
24
+ - `capabilities()` reports `loyalty`, from a signed `GET /api/v1/portfolio/loyalty?limit=1`.
25
+
26
+ ## 0.9.0 (2026-10-21)
27
+
28
+ One SDK for every STX exchange. Features an exchange does not have yet say so instead of failing obscurely, so the same release works against Ontario production today and against the features on US demo.
29
+
30
+ Not available:
31
+
32
+ - `STXNotAvailableException` (extends `STXAPIException`) with `feature`, `host` and a sentence such as `Combos are not available on demo.stxapp.ca yet.` It is thrown for: combos on an exchange without the combo topics (`STXCombosUnavailableException` stays a channel exception and now also matches `instanceof STXNotAvailableException`, with `feature` and `host`); OAuth discovery, token, refresh, revoke and introspect calls on an exchange without OAuth (a 404, or a 403 page from in front of the exchange); `createConnect()` where there is no OpenID configuration; `marketTypes()`, `eventPlayers()`, `createMarkets()` and the leaderboard calls where the exchange has no such route (or, for the leaderboard, has it switched off) (a 404 `{"error": "not_found"}`; a 404 about a missing event is still `STXNotFoundException`); and an `invalid_scope` for a scope the exchange's discovery document does not list (`feature` is `scope:<name>`).
33
+ - `await stx.capabilities()` reports which features the exchange has (`oauth`, `oauth.member`, `oauth.app`, `connect`, `terms.stx_page`, `markets.create`, `market_types`, `event_players`, `leaderboard`, `combos`) from its discovery document, `/api_version`, signed GETs and a join of a combo topic nobody owns. Nothing is created or changed. Cached per client; `has()` and `require()` on the result.
34
+ - Every other call behaves exactly as in 0.8.3.
35
+
36
+ Apps (OAuth):
37
+
38
+ - `OAuthClient.discover()` builds a client from the exchange's discovery document and keeps it as `oauth.metadata`; `fromMetadata()` keeps it too.
39
+ - Sign in with your STX account: `createConnect()` runs the OpenID Connect sign-in from your server. `start()` returns the redirect (optionally straight to Google, Apple or X, with a login hint), `finish()` exchanges the code and verifies the ID token, `refresh()` keeps the connection, `userInfo()` reads the member's claims again, and `disconnect()` ends the connection at STX. `TokenSet.idToken` carries the ID token.
40
+ - `authorizationUrl()` and `beginAuthorization()` take `connection` and `loginHint`.
41
+ - `STXAccountPendingException` when the member's STX account is still being verified (on the callback, or on a refresh or code exchange; `memberClient()` keeps the stored tokens), and `STXAccessDeniedException` when the member declined or cannot connect. Both extend `STXOAuthException`; `STXOAuthException.errorReason` carries the exchange's narrower reason.
42
+ - A callback error is reported only for a sign-in your app started: the `state` is checked (and used up) first.
43
+ - Terms are accepted on an STX page. `STXTermsRequiredException` (extends `STXForbiddenException`, with `termsUrl`) when a connected member has new terms to accept; `termsUrlWithReturn()`; a refresh while terms are pending succeeds and carries `termsRequired` and `termsUrl`, with an `onTermsRequired` session hook; `STXTermsNotAcceptedException` when the member leaves the terms page during sign-in. `MemberScopes.TERMS_WRITE` and the legacy `onboarding` are removed, since the exchange retired the scope, and `parseScopes()` leaves them out.
44
+ - `STXIPNotAllowedException` (extends `STXForbiddenException`) for a write from an address the app's IP allow-list lacks (`ip_not_allowed`).
16
45
  - HTTP Basic client credentials are form-urlencoded before base64, as RFC 6749 requires. Client ids and secrets with only letters, digits and `_-.` are sent exactly as before.
17
46
 
18
- Creating markets as your app:
47
+ Leaderboard:
48
+
49
+ - `leaderboard()`, `leaderboardMe()` and `updateProfile()` (`GET /api/v1/leaderboard`, `GET /api/v1/leaderboard/me`, `PATCH /api/v1/me/profile`).
50
+
51
+ Markets:
52
+
53
+ - `marketTypes()` lists the market types (`GET /api/v1/types`): the rules an app can create, their fields and the stats per event type. `NewMarket`, `PlayerStatLineMarket` and `MarketRule` name the input types; `NewMarketInput` is unchanged.
54
+
55
+ Fixes:
56
+
57
+ - The socket no longer sends channel `ping` frames on the `market:<id>`, `rfq:` and `combo_quote:` topics, which have no `ping` command. On the combo topics each one was refused (`unknown_command`) and logged a "ping failed" warning every 30 seconds per channel; on `market:<id>` it crashed the channel on the exchange, which then rejoined every 30 seconds. The socket heartbeat keeps these topics alive. Other channels are pinged as before.
58
+ - `ComboPlayer.leave()` and `ComboMaker.leave()` document that delivery stops when they resolve: the requests and quotes on that channel end as `cancelled`, and the exchange's `negotiation_closed` for them, which arrives after the channel has closed, is not delivered.
59
+
60
+ Examples: `examples/sign-in-with-stx.ts` and `examples/expo-connect/` (an Expo / React Native app with its server).
61
+
62
+ ## 0.8.3 (2026-10-20)
63
+
64
+ - Combos are no longer marked preview.
65
+ - `ComboRfqLeg.short_name` is `string | null`: the exchange sends `null` when it has no name for a leg.
66
+
67
+ ## 0.8.2 (2026-10-15)
68
+
69
+ - `createMarkets()` sends each market in the form the exchange takes, `{ rule: "player_stat_line", player_id, stat, line }`. Markets sent by 0.8.0 and 0.8.1 came back `rejected` with `invalid_market`.
70
+ - `createMarkets(eventId, markets, { dryRun: true })` runs every check on STX and creates nothing; a market that would be created comes back `valid`.
71
+ - Each result carries `index` (its position in the list you passed), `market_id`, `reason` (`null` unless rejected) and `market`, the market as you requested it. Rejection reasons follow the exchange: `invalid_market`, `unsupported_rule`, `unsupported_stat`, `invalid_line`, `unknown_player`, `event_not_open` and `not_created`.
72
+ - `propType` is no longer sent; a player stat line is always over/under.
73
+
74
+ ## 0.8.1 (2026-10-12)
19
75
 
20
- - `marketTypes()` lists the market types (`GET /api/v1/types`): the rules an app can create, the fields each takes and the stats on offer per event type.
21
- - `createMarkets()` takes each market by its `rule`: `{ rule: "player_stat_line", playerId, stat, line }`. **Changed from 0.8.0:** `rule` is now required and `propType` is gone.
22
- - `createMarkets(..., { dryRun: true })` runs every check and creates nothing; a market that would be created comes back `valid`.
23
- - **Changed from 0.8.0:** each result is `{ index, status, market_id, reason }`. `index` is the market's position in your list, `market_id` and `reason` are `null` when they do not apply, and the `market` echo of the request is gone (use `index`). The `NewMarketInput` and `MarketRequestEcho` types are replaced by `NewMarket`.
24
- - Fixed: a market the exchange returned no result for now comes back `rejected` with `not_created` instead of leaving a gap in the results.
76
+ - Combos (preview: available on US demo; may change before general availability). `ws.comboPlayer()` requests quotes on a combination, cashes one out, accepts, cancels and reads a request; `ws.comboMaker()` receives requests, quotes and withdraws quotes. Events and replies are typed (`ComboPlayerEvent`, `ComboMakerEvent` and the reply types), with `waitFor()`, `next()` and `for await`.
77
+ - `STXCombosUnavailableException` when an environment does not offer combos, `STXComboRefusedException` with the exchange's reason in `code` (and `detail` for `player_refused`), and `STXComboPriceMovedException` with the live best quote.
25
78
 
26
79
  ## 0.8.0 (2026-10-06)
27
80
 
package/README.md CHANGED
@@ -22,46 +22,49 @@ const client = new STX();
22
22
  const page = await client.markets({ status: "open", trading: true, limit: 5 });
23
23
 
24
24
  for (const market of page.items) {
25
- // bids are what buyers will pay, offers what sellers will accept, best price first.
25
+ // bids are what buyers will pay, offers what sellers will accept. Both lists are sorted
26
+ // by price, highest first, so the best bid is the first entry and the best offer the last.
26
27
  // Prices are dollars per contract, as strings; a winning contract pays market.max_price.
27
28
  const bid = market.bids?.[0]?.price ?? "-"; // "-" when nobody is bidding
28
- const offer = market.offers?.[0]?.price ?? "-";
29
+ const offer = market.offers?.at(-1)?.price ?? "-";
29
30
  console.log(`${market.event_title}: ${market.title} bid ${bid} offer ${offer}`);
30
31
  }
31
32
  ```
32
33
 
33
- Sample output:
34
+ Sample output (two of the five markets):
34
35
 
35
36
  ```text
36
- New York Yankees at San Diego Padres: Padres First Run bid - offer -
37
- New York Yankees at San Diego Padres: Yankees First Run bid 0.4200 offer -
38
- Norfolk State Spartans at Old Dominion Monarchs: Old Dominion Score Last bid - offer -
39
- Norfolk State Spartans at Old Dominion Monarchs: Norfolk St Score Last bid - offer -
40
- Los Angeles Chargers at Buffalo Bills: NFL - Week 3 LAC @ BUF bid - offer -
37
+ Edmonton Oilers at San Jose Sharks: NHL EDM @ SJ bid 0.5800 offer 0.5900
38
+ Edmonton Oilers at San Jose Sharks: C. McDavid 3.5 SOG bid 0.4900 offer 0.5300
41
39
  ```
42
40
 
43
- A bid of `0.4200` on a market whose winning contract pays `1.0000` means a buyer will pay 42 cents for a contract that pays $1 if the Yankees score first.
41
+ A bid of `0.5800` on a market whose winning contract pays `1.0000` means a buyer will pay 58 cents for a contract that pays $1 if the Oilers win.
44
42
 
45
43
  <details>
46
44
  <summary>One market from the response (selected fields)</summary>
47
45
 
48
46
  ```json
49
47
  {
50
- "market_id": "ddb216af-e752-422c-8688-52f95630b219",
51
- "symbol": "STXMLB-26SEP042140NYYSD-ESLAWAYFIRSTRUNNA",
52
- "event_title": "New York Yankees at San Diego Padres",
53
- "title": "Yankees First Run",
54
- "question": "Will New York Yankees score the first run of the game?",
48
+ "market_id": "e00651a3-10cb-4bc1-9e1f-c5ea1796c83b",
49
+ "symbol": "STXNHL-26OCT101600EDMSJ-GAMEEDM",
50
+ "event_title": "Edmonton Oilers at San Jose Sharks",
51
+ "title": "NHL EDM @ SJ",
52
+ "question": "Will the Edmonton Oilers defeat the San Jose Sharks?",
55
53
  "status": "open",
56
54
  "trading": true,
57
- "event_start": "2026-09-05T01:40:00.000000Z",
55
+ "event_start": "2026-10-10T20:00:00.000000Z",
58
56
  "max_price": "1.0000",
59
- "last_traded_price": null,
57
+ "last_traded_price": "0.5800",
60
58
  "bids": [
61
- { "quantity": "5.00", "price": "0.4200" },
62
- { "quantity": "4.00", "price": "0.2400" }
59
+ { "price": "0.5800", "quantity": "210.00" },
60
+ { "price": "0.5700", "quantity": "420.00" },
61
+ { "price": "0.5600", "quantity": "1200.00" }
63
62
  ],
64
- "offers": []
63
+ "offers": [
64
+ { "price": "0.6100", "quantity": "900.00" },
65
+ { "price": "0.6000", "quantity": "650.00" },
66
+ { "price": "0.5900", "quantity": "310.00" }
67
+ ]
65
68
  }
66
69
  ```
67
70
 
@@ -69,16 +72,16 @@ Every field is described in the [API reference](https://docs.stxapp.io/sdks/type
69
72
 
70
73
  </details>
71
74
 
72
- ## For apps: STX accounts and markets (alpha)
75
+ ## For apps: STX accounts and markets
73
76
 
74
- An app registered with STX can bring its members' STX accounts in, and can act as itself. These are in the alpha: `npm install @stxapp/stx-typescript@alpha`. They run on your server; the client secret and the tokens never go to a browser or a mobile app. There are two ways to bring a member's STX account in.
77
+ An app registered with STX can bring its members' STX accounts in, and can act as itself. This runs on your server; the client secret and the tokens never go to a browser or a mobile app. OAuth is on in US demo today; on an exchange without it these calls throw `STXNotAvailableException`, and `await stx.capabilities()` says which features an exchange has. There are two ways to bring a member's STX account in.
75
78
 
76
79
  **Connect your STX account.** Your app keeps its own login, and a signed-in user links their STX account so your app can trade and read for them. It works with any login system (your own passwords, or a login service you already use); STX never sees it.
77
80
 
78
81
  ```ts
79
82
  import { MemoryPendingAuthorizationStore, MemoryTokenStore, OAuthClient } from "@stxapp/stx-typescript/oauth";
80
83
 
81
- const oauth = new OAuthClient({ baseUrl: "https://demo.stxapp.io", clientId, clientSecret, redirectUri });
84
+ const oauth = await OAuthClient.discover({ baseUrl: "https://demo.stxapp.io", clientId, clientSecret, redirectUri });
82
85
  const pending = new MemoryPendingAuthorizationStore(); // sign-ins in progress; use your session store or database
83
86
  const store = new MemoryTokenStore(); // members' tokens; use your database
84
87
  const { url } = await oauth.beginAuthorization(pending, { scope: ["balance.read", "orders.write"], data: { userId } });
@@ -109,7 +112,7 @@ const results = await stx.createMarkets(eventId, [
109
112
  ]);
110
113
  ```
111
114
 
112
- See the guides for [signing in and connecting](https://docs.stxapp.io/sdks/typescript/sign-in-with-stx/) and [creating markets](https://docs.stxapp.io/sdks/typescript/markets/), and `examples/sign-in-with-stx.ts`, `examples/isv-backend/` and `examples/create-markets.ts`.
115
+ See the guides for [what you can do where](https://docs.stxapp.io/sdks/typescript/capabilities/), [signing in and connecting](https://docs.stxapp.io/sdks/typescript/sign-in-with-stx/) and [creating markets](https://docs.stxapp.io/sdks/typescript/markets/), and `examples/sign-in-with-stx.ts`, `examples/isv-backend/`, `examples/expo-connect/` and `examples/create-markets.ts`.
113
116
 
114
117
  ## Documentation
115
118
 
@@ -118,4 +121,4 @@ See the guides for [signing in and connecting](https://docs.stxapp.io/sdks/types
118
121
  - [Release notes](https://docs.stxapp.io/changelog/)
119
122
  - [Support](https://docs.stxapp.io/support/)
120
123
 
121
- MIT license. Use of the STX API and exchange is subject to the STX terms of use and privacy policy: United States ([terms of use](https://config.stxapp.io/us/terms_of_use.pdf), [privacy policy](https://config.stxapp.io/us/privacy_policy.pdf)), Ontario ([terms of use](https://config.stxapp.ca/on/terms-of-use.pdf), [privacy policy](https://config.stxapp.ca/on/privacy-policy.pdf)).
124
+ MIT license. Use of the STX API and exchange is subject to the STX terms of use and privacy policy: United States ([terms of use](https://stxapp.io/legal/terms-of-use.pdf), [privacy policy](https://stxapp.io/legal/privacy-policy.pdf)), Ontario ([terms of use](https://stxapp.ca/legal/terms-of-use.pdf), [privacy policy](https://stxapp.ca/legal/privacy-policy.pdf)).