Release: JS/TS SDK 1.0 + accumulated staging changes#153
Merged
Conversation
feat: adds initial documentation for js sdk
Updates every SDK-JS doc under sdk/js/ to reflect the ADR-007 reversal:
public API now surfaces standard Promises. Neverthrow remains internal
to the SDK — callers never see Result types.
Mechanical changes (15 files):
- Import path: `marketdata-sdk-js` → `marketdata-sdk`.
- Type signatures: `MarketDataResult<T>` → `MarketDataPromise<T>`,
`TypedResult<T,H,P>` → `TypedPromise<T,H,P>`.
- Link anchors: `#MarketDataResult` → `#MarketDataPromise`.
- Example blocks: every `result.match(ok, err)` / `isOk()/value/error`
/ `_unsafeUnwrap()` example rewritten to idiomatic `try/catch`
around `await`.
- Error handling sections: list the new 7 spec classes
(Authentication/BadRequest/NotFound/RateLimit/Server/Network/Parse
+ client-side Validation) with cf-ray, status, url, timestamp context.
- 404-as-no-data noted: response.no_data / hasData() patterns.
client.mdx additionally documents:
- `ready: Promise<void>` for eager startup validation
- `skipStartupValidation` config flag for serverless
- 99s request timeout
- Global 50-request concurrency pool
- Utilities resource on the client
- MarketDataPromise response-model methods (isJson/isCsv/isHtml/
hasData/no_data/saveToFile/save/blob)
- Updated User-Agent to `marketdata-sdk-javascript/{version}`
installation.mdx: `neverthrow` line reworded to note it's now an
internal dep, with a link to the client error-handling section.
No structural rewrites; ADRs under `sdk/js/docs/adr/` intentionally
untouched (historical snapshots).
Verified: grep for `isOk|isErr|ResultAsync|TypedResult|MarketDataResult|
_unsafeUnwrap|.match(|marketdata-sdk-js|unwrap(` under sdk/js/ returns
zero hits outside ADRs.
Adds prominent admonitions on the API root page and Authentication page warning that any endpoint may return 203 (cached response) instead of 200, since clients that check only status == 200 silently drop valid cached responses. Adds a Status Codes section to the mode page with the correct 200/203/204 mapping (203 fires on any cache-layer hit, not exclusively on mode=cached) and a Python retry example for the 204 cache-miss path. Tracking the matching OpenAPI spec fix in MarketData-App/api#61.
The plain /contact/ links were being rewritten by Docusaurus to /docs/contact/. Use absolute URL to point to the WordPress contact form, matching the existing pattern in api/cors.mdx.
New page at /docs/account/data-freshness explains the freshness model in three categories — Real-time (<15m), Delayed (15+m, current session), Historical (15+m, prior session closed) — and clarifies the rollover rule that's been silently confusing customers and support: stocks roll to Historical at 4:15 PM ET (close + 15 min), but options roll only at the *next* session's 9:30 AM ET open. So Friday's options data does not become Historical until 9:30:01 Monday — a query at 6:33 AM Wednesday on a Historical-only plan returns Monday's close, not Tuesday's, and that's correct. Each plan tier (Free Forever, Starter Trial, Trader Trial, Starter, Trader, Quant, Prime) gets a per-endpoint freshness table covering every API endpoint family. Cross-reference links added from the plan docs, plan-limits, and the universal-parameters/mode page. A few cells (funds endpoints, UTP-entitled stock candles) are flagged as pending product confirmation in the page footer.
Adds a shared lib/mdx-to-md.js that the Cloudflare Worker, the new SDK export CLI, and (eventually) the LLM-bundle script all use for converting Docusaurus MDX into clean Markdown. Replaces the worker's inline cleanMarkdown. Improvements delivered to the live .md serving via the worker: - Admonitions (:::tip / :::info / :::warning ...) now render as GitHub Alert blockquotes (> [!TIP]) instead of passing through unchanged. - Internal /sdk/, /api/, /img/ links get rewritten to absolute www.marketdata.app/docs URLs. - Code-fence-aware import stripping: imports inside ```typescript fences (e.g. `import { MarketDataClient } from "marketdata-sdk-js"`) are no longer eaten by the regex. The fix is a proper tokenizer, not a patched regex. Adds: - lib/mdx-to-md.js — pure CJS, runs in V8 isolates and Node - lib/__tests__/mdx-to-md.test.js — 33 node --test cases - scripts/export-sdk-docs.js — `yarn export-sdk-docs --sdk js` - .github/workflows/sync-sdk-docs.yml — push-to-staging or manual dispatch opens a PR in MarketDataApp/sdk-js with regenerated /docs. Uses a GitHub App for cross-repo auth; preserves SDK-repo-owned content via banner-based selective deletion. Pilot scope: sdk-js only. Matrix is one-line to extend.
The "<!-- Generated from ... -->" banner was doing two jobs: telling humans not to edit, and giving the sync workflow a signal to scope deletion to previously-generated files. Splits those responsibilities: - Drop the banner from each .md file; titles now start with `# ...` directly. - CLI writes docs/.sync-manifest.txt listing every generated path. - Workflow reads that manifest to decide what to delete; SDK-repo-owned content (ADRs, READMEs not in the manifest) stays untouched. - PR body now surfaces the "do not edit" notice once, pointing reviewers at the manifest.
…gets
Switches directory indices from index.md to README.md so GitHub auto-renders
them at each directory URL, and fixes a real link bug surfaced by the
change: links like [Stocks](/sdk/js/stocks) were rewriting to ./stocks.md
(a file that never existed) instead of the directory landing page.
Mechanism: the export CLI now walks the source tree first, builds a map
{ Docusaurus-subpath → repo-relative output file }, and passes it to
cleanMdx via a new `linkTargets` opt. The lib uses this map to resolve
same-SDK links accurately, and collapses common path prefixes so
siblings get './neighbor.md' rather than '../dir/neighbor.md'.
Worker and LLM-bundle callers don't pass linkTargets — they keep
rewriting same-SDK paths to absolute www.marketdata.app/docs URLs as
before. Five new unit tests cover the directory-index resolution and
prefix collapsing.
Adds the four utilities pages (status, headers, user) plus an options/strikes reference. Index page updated to list the new namespace alongside stocks/options/ funds/markets. Mirrors the SDK source under sdk-js/src/resources/utilities and sdk-js/src/resources/options/strikes.ts; documents the constructor-issued startup user() call and the /user/ 404→NotFoundError carve-out. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the sop/ directory to .gitignore. Internal SOPs are not part of the public docs site.
Replaces the inline MDX-cleaning logic in generate-master-docs.js with a call to the shared cleanMdx helper from lib/mdx-to-md, matching the approach used by the SDK docs sync workflow. Also adds two package.json scripts: - export-sdk-docs: produce the SDK docs bundle - test:lib: run lib/__tests__ via node --test
The malformed value=">MacLinux" broke the worker's MDX→MD TabItem regex, causing /docs/sdk/go/authentication.md to leak the raw <TabItem> tag and fail the post-deploy integration test.
Removes sdk/js/options/strikes.mdx after Taylor confirmed the strikes endpoint will no longer be offered. The options DocCardList is sidebar- autogenerated and refreshes automatically. Adds a Quick Start block to sdk/js/index.mdx mirroring the snippet in the sdk-js README, addressing Santiago's review comment on PR #148. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The chain.mdx Parameters list and Filtered example used snake_case names (strike_limit, min_open_interest, …) plus days_to_expiration, none of which the live API recognises — mirroring the SDK schema bug fixed in sdk-js #19. Rename to the API names: dte, strikeLimit, minBid/maxBid, minAsk/maxAsk, maxBidAskSpread, maxBidAskSpreadPct, minOpenInterest, minVolume. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Link UtilitiesResource in the Resources list (parity with the other
resources, which all link to their per-resource pages).
- Rewrite the NotFoundError row in the Error classes table. The previous
copy described an internal sentinel (`{s: "no_data"}`) that never
escapes _makeRequest; the SDK exposes 404 as an empty response with
`no_data: true`. Also call out the `/user/` opt-in throw path.
- Add PaymentRequiredError (402) and ForbiddenError (403) rows so the
Error classes table matches the classes actually exported from
sdk-js src/error.ts on main.
The companion sdk-js change removes client.utilities.user() — its
declared schema never matched the live API response, so callers always
got `{}` at runtime. Rate-limit data is on client.rateLimits (populated
automatically at startup from the same /user/ response headers), and
sdk-py never exposed this surface in the first place.
- Delete sdk/js/utilities/user.mdx
- Rework utilities/index.mdx intro: "All three" -> "Both", drop the
rate-limit framing on this page, and point readers to
client.rateLimits for the data the user page used to advertise.
…-strikes Docs/sdk js utilities and strikes
Line still mentioned the user endpoint after PR #148 removed the page.
docs(sdk/js): drop stale 'user' from utilities resource list
Adds JS and TS logos and a card linking to /sdk/js, matching the layout of the other SDK cards.
docs(sdk): add JavaScript/TypeScript SDK card to main SDK page
Rename npm package from `marketdata-sdk` to `@marketdata/sdk` across all JavaScript SDK pages, drop the pre-release callouts, and bump the User-Agent examples to 1.0.0.
… SDK tabs (#152) Bring the JS examples across the API reference in line with the other languages now that the JavaScript/TypeScript SDK (marketdata-sdk) is shipped. Each affected page's single NodeJS raw-fetch tab is replaced with paired JavaScript and TypeScript tabs using the SDK (await + try/catch), sourced from the matching sdk/js/* page. - 13 endpoint pages: 1:1 SDK swap (stocks/{quotes,prices,candles, earnings,news}, options/{chain,expirations,lookup,quotes}, funds/candles, markets/status, utilities/{status,headers}). - authentication.mdx: env-var + explicit-token forms. - troubleshooting/logging.mdx: SDK DefaultLogger(LogLevel.DEBUG). - troubleshooting/real-time-data.mdx: client.stocks.quotes + Mode.LIVE, keeping the data-age diagnostic logic. - troubleshooting/service-outages.mdx: client.utilities.status(). - stocks/bulkcandles.mdx: SDK has no bulk method yet, so JavaScript keeps raw fetch() and TypeScript uses the typed Response API; a note documents this until bulk support lands. Closes #151 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Follow-up to the JS SDK 1.0 publish: the api/ pages added in #152 used the pre-release `marketdata-sdk` package name. Swap them to the published `@marketdata/sdk` so the API reference matches the SDK docs.
The SDK now emits `marketdata-sdk-js/{version}` instead of
`marketdata-sdk-javascript/{version}`. Update the client notes and the
utilities.headers() example to match.
Auto-fix from scripts/fix-table-alignment.js. Resolves the table-alignment CI check on PR #153.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Promotes everything currently on
stagingto production. The headline is the JavaScript/TypeScript SDK 1.0 launch (@marketdata/sdk); a batch of unrelated staging changes also ride along per the standard staging → main flow.JavaScript / TypeScript SDK 1.0
sdk/js/— installation, client, authentication, settings, and per-endpoint pages for stocks, options, funds, markets, utilitiessdk/index, withjavascript-logo.svg+typescript-logo.svg0.0.1, no more "install from GitHub"); package is@marketdata/sdkand User-Agent ismarketdata-sdk-js/{version}api/): every NodeJS raw-fetch tab replaced with paired JavaScript + TypeScript tabs using the SDK (docs(api): replace NodeJS raw-fetch tabs with JavaScript + TypeScript… #152)Other changes also shipping
account/data-freshness.md— new per-endpoint freshness pageaccount/plans/*— minor plan-page tweaksaccount/plan-limits.md— dropped custom-plan tipaccount/plans/commercial.mdx— unlisted sales-only page addedapi/universal-parameters/mode.md— new universal-parameter pageapi/index.md— surface HTTP 203/204 cache responsesworker/— refactor and shared MDX→MD libscripts/,lib/,.github/workflows/sync-sdk-docs.yml— SDK docs sync workflowsdk/go/authentication.mdx— stray>fixsdk/sdk-requirements.md— retry policy clarification (3 retries, 1s/2s/4s backoff)Test plan
www-staging.marketdata.app/docs/sdk/js/renders correctly end-to-end before mergewww-staging.marketdata.app/docs/api/troubleshooting/real-time-data(largest JS+TS rewrite)@marketdata/sdkpackage install instructions render correctly on stagingwww.marketdata.app/docs/sdk/js/MarketDataApp/www-marketdata-apporchestrator