Release: JS/TS SDK 1.0 + accumulated staging changes

.github/workflows/sync-sdk-docs.yml

@@ -0,0 +1,164 @@
+# Syncs SDK docs from /sdk/<lang>/ in this repo into MarketDataApp/sdk-<lang>/docs/
+# by converting MDX → clean Markdown and opening a PR against the target repo.
+#
+# Pilot scope: sdk-js only. Adding more SDKs is a one-line matrix change.
+#
+# ────────────────────────────────────────────────────────────────────────────
+# One-time setup (GitHub App auth — survives the eventual repo migration to
+# the MarketData-App org without code changes):
+#
+# 1. Create a GitHub App owned by `MarketData-App` (org settings → Developer
+#    settings → GitHub Apps → New GitHub App). Suggested name:
+#    `marketdata-docs-sync`. Set "Where can this be installed?" to "Any
+#    account" so it can run against repos that still live under the
+#    MarketDataApp user (current home) and later the MarketData-App org.
+# 2. Permissions: Contents = Read & write, Pull requests = Read & write,
+#    Metadata = Read. No webhook (uncheck "Active").
+# 3. Generate a private key (.pem) and download it.
+# 4. Install the App on `MarketDataApp` (user), granting access to
+#    `documentation` and `sdk-js`. (Add more SDK repos as the matrix grows.)
+# 5. In this repo:
+#    - Repo variable `SDK_DOCS_APP_ID` = the App ID (a number)
+#    - Repo secret   `SDK_DOCS_APP_PRIVATE_KEY` = the .pem contents
+# 6. After repo migration to the org, change `TARGET_OWNER` below from
+#    `MarketDataApp` to `MarketData-App`.
+# ────────────────────────────────────────────────────────────────────────────
+
+name: "SDK Docs: Sync to SDK Repos"
+
+on:
+  push:
+    branches: [staging]
+    paths:
+      - 'sdk/js/**'
+      - 'lib/mdx-to-md.js'
+      - 'scripts/export-sdk-docs.js'
+      - '.github/workflows/sync-sdk-docs.yml'
+  workflow_dispatch:
+    inputs:
+      sdk:
+        description: 'Which SDK to sync (pilot: js only)'
+        required: true
+        default: 'js'
+        type: choice
+        options: [js]
+
+env:
+  SOURCE_OWNER: MarketDataApp
+  TARGET_OWNER: MarketDataApp # change to MarketData-App after repo migration
+  MANIFEST_FILE: docs/.sync-manifest.txt
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [js]
+    steps:
+      - name: Checkout documentation source
+        uses: actions/checkout@v4
+        with:
+          path: docs-source
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run unit tests for the conversion lib
+        working-directory: docs-source
+        run: node --test lib/__tests__/*.test.js
+
+      - name: Convert sdk/<lang>/ → clean .md
+        working-directory: docs-source
+        env:
+          SDK: ${{ matrix.sdk }}
+          OUT_DIR: ${{ runner.temp }}/out
+        run: node scripts/export-sdk-docs.js --sdk "$SDK" --out "$OUT_DIR"
+
+      - name: Mint cross-repo token (GitHub App)
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.SDK_DOCS_APP_ID }}
+          private-key: ${{ secrets.SDK_DOCS_APP_PRIVATE_KEY }}
+          owner: ${{ env.TARGET_OWNER }}
+          repositories: sdk-${{ matrix.sdk }}
+
+      - name: Checkout target SDK repo
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.TARGET_OWNER }}/sdk-${{ matrix.sdk }}
+          token: ${{ steps.app-token.outputs.token }}
+          path: target
+
+      - name: Replace previously-generated docs with fresh export
+        # We DO NOT wipe target/docs/ wholesale — it may contain SDK-repo-owned
+        # content (ADRs, internal READMEs). The previous sync wrote a manifest
+        # at $MANIFEST_FILE listing every file it generated. Delete exactly
+        # those paths, then drop the fresh export in (which writes a new
+        # manifest).
+        env:
+          OUT_DIR: ${{ runner.temp }}/out
+        run: |
+          set -euo pipefail
+          mkdir -p target/docs
+          if [ -f "target/$MANIFEST_FILE" ]; then
+            while IFS= read -r rel; do
+              # Skip blank lines and comments (lines beginning with '#')
+              case "$rel" in
+                ''|'#'*) continue ;;
+              esac
+              rm -f "target/docs/$rel"
+            done < "target/$MANIFEST_FILE"
+          fi
+          # Remove any now-empty directories left behind.
+          find target/docs -type d -empty -delete || true
+          mkdir -p target/docs
+          cp -R "$OUT_DIR/." target/docs/
+
+      - name: Compute diff summary for PR body
+        id: diff
+        working-directory: target
+        run: |
+          set -euo pipefail
+          git add -A docs/
+          {
+            echo "summary<<DIFFEOF"
+            if git diff --cached --quiet; then
+              echo "_No changes — docs are already in sync._"
+            else
+              git diff --cached --name-status -- docs/
+            fi
+            echo "DIFFEOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Open / update PR in target SDK repo
+        uses: peter-evans/create-pull-request@v6
+        with:
+          path: target
+          token: ${{ steps.app-token.outputs.token }}
+          branch: sync/docs-from-documentation
+          delete-branch: true
+          commit-message: 'docs: sync from documentation@${{ github.sha }}'
+          title: 'docs: sync from documentation@${{ github.sha }}'
+          body: |
+            Automated sync from [`${{ env.SOURCE_OWNER }}/documentation@${{ github.sha }}`](https://github.com/${{ env.SOURCE_OWNER }}/documentation/commit/${{ github.sha }}).
+
+            **SDK:** `${{ matrix.sdk }}`
+            **Source path:** `sdk/${{ matrix.sdk }}/`
+            **Workflow run:** [#${{ github.run_id }}](https://github.com/${{ env.SOURCE_OWNER }}/documentation/actions/runs/${{ github.run_id }})
+
+            ### Changed files
+
+            ```
+            ${{ steps.diff.outputs.summary }}
+            ```
+
+            > **These files are auto-synced from
+            > [MarketDataApp/documentation](https://github.com/MarketDataApp/documentation/tree/staging/sdk/${{ matrix.sdk }})** —
+            > edit the source `.mdx` there, not the rendered `.md` here.
+            > Hand-edits to files listed in `docs/.sync-manifest.txt` will
+            > be overwritten on the next sync.

.gitignore

@@ -31,3 +31,6 @@ static/robots.txt
 static/css/
 worker/node_modules
 
+# Internal SOPs (not for public docs site)
+sop/
+

account/data-freshness.md

@@ -0,0 +1,173 @@
+---
+title: Data Freshness
+sidebar_position: 5.5
+---
+
+Market Data classifies the data you receive into three freshness categories:
+
+- **Real-time** — under 15 minutes old. Live trading data.
+- **Delayed** — 15+ minutes old, but from the current trading session.
+- **Historical** — from a previous, fully-closed trading session.
+
+Which category applies depends on your plan, the data type, and the time of day.
+
+## When Delayed data becomes Historical
+
+Historical requires both a >15-minute delay floor *and* a data-type-specific session-closed condition. The session-closed condition is **different for stocks and options**:
+
+- **Stocks:** Historical at session close + 15 min — **4:15:01 PM ET** on a regular trading day. Between 4:00 PM and 4:15 PM ET, the data is still Delayed (the 15-minute Delayed window hasn't elapsed yet).
+- **Options:** Historical at the *next* session's open — **9:30:01 AM ET** the next trading day, not at the prior session's close.
+
+Friday's options quotes therefore do **not** become Historical until **9:30:01 AM ET Monday** — they remain Delayed all weekend.
+
+If you query an options endpoint at 6:33 AM ET Wednesday on a plan that provides Historical-only options data, you will receive **Monday's** close, not Tuesday's. Tuesday's options data does not roll to Historical until 9:30:01 AM ET Wednesday. This is the most common cause of "the data doesn't match my broker" support requests — the behavior is correct, the customer is just querying before the next session has opened.
+
+## By Plan
+
+The tables below show the freshness category for every API endpoint, by plan. Real-time stock and options data also requires non-professional status. See [Exchange Entitlements](./entitlements) for the underlying entitlement model.
+
+### Free Forever
+
+All pricing data is Historical (24-hour delayed). Metadata and computed-index endpoints remain Real-time.
+
+| Endpoint                   | Freshness  | Notes                             |
+|----------------------------|------------|-----------------------------------|
+| `/v1/stocks/quotes/`       | Historical |                                   |
+| `/v1/stocks/candles/`      | Historical |                                   |
+| `/v1/stocks/bulkcandles/`  | Historical |                                   |
+| `/v1/stocks/prices/`       | Historical |                                   |
+| `/v1/options/quotes/`      | Historical |                                   |
+| `/v1/options/chain/`       | Historical |                                   |
+| `/v1/options/strikes/`     | Real-time  | Contract metadata, no pricing     |
+| `/v1/options/expirations/` | Real-time  | Contract metadata                 |
+| `/v1/options/lookup/`      | Real-time  | Contract metadata                 |
+| `/v1/indices/quotes/`      | Real-time  | Indices are computed continuously |
+| `/v1/indices/candles/`     | Real-time  | Indices are computed continuously |
+| `/v1/markets/status/`      | Real-time  | Calendar metadata                 |
+| `/v1/funds/*`              | See note   | Pending product confirmation      |
+
+### Starter Trial
+
+Same as Free Forever — all pricing data is Historical (24-hour delayed).
+
+| Endpoint                   | Freshness  | Notes                             |
+|----------------------------|------------|-----------------------------------|
+| `/v1/stocks/quotes/`       | Historical |                                   |
+| `/v1/stocks/candles/`      | Historical |                                   |
+| `/v1/stocks/bulkcandles/`  | Historical |                                   |
+| `/v1/stocks/prices/`       | Historical |                                   |
+| `/v1/options/quotes/`      | Historical |                                   |
+| `/v1/options/chain/`       | Historical |                                   |
+| `/v1/options/strikes/`     | Real-time  | Contract metadata, no pricing     |
+| `/v1/options/expirations/` | Real-time  | Contract metadata                 |
+| `/v1/options/lookup/`      | Real-time  | Contract metadata                 |
+| `/v1/indices/quotes/`      | Real-time  | Indices are computed continuously |
+| `/v1/indices/candles/`     | Real-time  | Indices are computed continuously |
+| `/v1/markets/status/`      | Real-time  | Calendar metadata                 |
+| `/v1/funds/*`              | See note   | Pending product confirmation      |
+
+### Trader Trial
+
+Same as Starter Trial — all pricing data is Historical (24-hour delayed).
+
+| Endpoint                   | Freshness  | Notes                             |
+|----------------------------|------------|-----------------------------------|
+| `/v1/stocks/quotes/`       | Historical |                                   |
+| `/v1/stocks/candles/`      | Historical |                                   |
+| `/v1/stocks/bulkcandles/`  | Historical |                                   |
+| `/v1/stocks/prices/`       | Historical |                                   |
+| `/v1/options/quotes/`      | Historical |                                   |
+| `/v1/options/chain/`       | Historical |                                   |
+| `/v1/options/strikes/`     | Real-time  | Contract metadata, no pricing     |
+| `/v1/options/expirations/` | Real-time  | Contract metadata                 |
+| `/v1/options/lookup/`      | Real-time  | Contract metadata                 |
+| `/v1/indices/quotes/`      | Real-time  | Indices are computed continuously |
+| `/v1/indices/candles/`     | Real-time  | Indices are computed continuously |
+| `/v1/markets/status/`      | Real-time  | Calendar metadata                 |
+| `/v1/funds/*`              | See note   | Pending product confirmation      |
+
+### Starter
+
+Real-time stock data, 15-minute Delayed options data.
+
+| Endpoint                   | Freshness | Notes                                                                      |
+|----------------------------|-----------|----------------------------------------------------------------------------|
+| `/v1/stocks/quotes/`       | Real-time | IEX entitlement                                                            |
+| `/v1/stocks/candles/`      | Real-time | UTP entitlement may impose 15-min delay on intraday candles — see footnote |
+| `/v1/stocks/bulkcandles/`  | Real-time | Same as `/candles/`                                                        |
+| `/v1/stocks/prices/`       | Real-time |                                                                            |
+| `/v1/options/quotes/`      | Delayed   | 15 minutes                                                                 |
+| `/v1/options/chain/`       | Delayed   | 15 minutes                                                                 |
+| `/v1/options/strikes/`     | Real-time | Contract metadata                                                          |
+| `/v1/options/expirations/` | Real-time | Contract metadata                                                          |
+| `/v1/options/lookup/`      | Real-time | Contract metadata                                                          |
+| `/v1/indices/quotes/`      | Real-time |                                                                            |
+| `/v1/indices/candles/`     | Real-time |                                                                            |
+| `/v1/markets/status/`      | Real-time | Calendar metadata                                                          |
+| `/v1/funds/*`              | See note  | Pending product confirmation                                               |
+
+### Trader
+
+Real-time data for both stocks and options.
+
+| Endpoint                   | Freshness | Notes                        |
+|----------------------------|-----------|------------------------------|
+| `/v1/stocks/quotes/`       | Real-time |                              |
+| `/v1/stocks/candles/`      | Real-time |                              |
+| `/v1/stocks/bulkcandles/`  | Real-time |                              |
+| `/v1/stocks/prices/`       | Real-time |                              |
+| `/v1/options/quotes/`      | Real-time | OPRA entitlement             |
+| `/v1/options/chain/`       | Real-time | OPRA entitlement             |
+| `/v1/options/strikes/`     | Real-time | Contract metadata            |
+| `/v1/options/expirations/` | Real-time | Contract metadata            |
+| `/v1/options/lookup/`      | Real-time | Contract metadata            |
+| `/v1/indices/quotes/`      | Real-time |                              |
+| `/v1/indices/candles/`     | Real-time |                              |
+| `/v1/markets/status/`      | Real-time | Calendar metadata            |
+| `/v1/funds/*`              | See note  | Pending product confirmation |
+
+### Quant
+
+Real-time data for both stocks and options. Same freshness profile as Trader.
+
+| Endpoint                   | Freshness | Notes                        |
+|----------------------------|-----------|------------------------------|
+| `/v1/stocks/quotes/`       | Real-time |                              |
+| `/v1/stocks/candles/`      | Real-time |                              |
+| `/v1/stocks/bulkcandles/`  | Real-time |                              |
+| `/v1/stocks/prices/`       | Real-time |                              |
+| `/v1/options/quotes/`      | Real-time | OPRA entitlement             |
+| `/v1/options/chain/`       | Real-time | OPRA entitlement             |
+| `/v1/options/strikes/`     | Real-time | Contract metadata            |
+| `/v1/options/expirations/` | Real-time | Contract metadata            |
+| `/v1/options/lookup/`      | Real-time | Contract metadata            |
+| `/v1/indices/quotes/`      | Real-time |                              |
+| `/v1/indices/candles/`     | Real-time |                              |
+| `/v1/markets/status/`      | Real-time | Calendar metadata            |
+| `/v1/funds/*`              | See note  | Pending product confirmation |
+
+### Prime
+
+Real-time data for both stocks and options. Same freshness profile as Trader and Quant.
+
+| Endpoint                   | Freshness | Notes                        |
+|----------------------------|-----------|------------------------------|
+| `/v1/stocks/quotes/`       | Real-time |                              |
+| `/v1/stocks/candles/`      | Real-time |                              |
+| `/v1/stocks/bulkcandles/`  | Real-time |                              |
+| `/v1/stocks/prices/`       | Real-time |                              |
+| `/v1/options/quotes/`      | Real-time | OPRA entitlement             |
+| `/v1/options/chain/`       | Real-time | OPRA entitlement             |
+| `/v1/options/strikes/`     | Real-time | Contract metadata            |
+| `/v1/options/expirations/` | Real-time | Contract metadata            |
+| `/v1/options/lookup/`      | Real-time | Contract metadata            |
+| `/v1/indices/quotes/`      | Real-time |                              |
+| `/v1/indices/candles/`     | Real-time |                              |
+| `/v1/markets/status/`      | Real-time | Calendar metadata            |
+| `/v1/funds/*`              | See note  | Pending product confirmation |
+
+## Notes
+
+- **Real-time data and professional status:** Real-time stock and options data is only available to non-professional users. Professional users on any paid plan revert to Delayed data unless they have signed the OPRA professional subscriber agreement. See [Exchange Entitlements](./entitlements) and [Professional Status](https://www.marketdata.app/education/stocks/professional-status-explained/).
+- **`/v1/funds/*` freshness** is documented per fund-data type and is pending publication here. Until then, refer to the individual endpoint pages under [Funds API](../api/funds/).
+- **UTP entitlement and intraday stock candles:** the [UTP entitlement](./entitlements#utp-entitlement) grants "15-minute delayed intraday stock candles." On plans with Real-time stock quotes (Starter and above), this means intraday candles may carry a 15-minute delay even though quotes do not. Confirm with the [Plan Limits](./plan-limits) page for your plan.