Add TypeScript SDK API reference docs with TypeDoc

.github/workflows/ci-amd.yml

@@ -138,6 +138,7 @@ jobs:
       run-coverage: ${{ steps.source-run-info.outputs.run-coverage }}
       run-go-sdk-tests: ${{ steps.selective-checks.outputs.run-go-sdk-tests }}
       run-java-sdk-tests: ${{ steps.selective-checks.outputs.run-java-sdk-tests }}
+      run-ts-sdk-docs: ${{ steps.selective-checks.outputs.run-ts-sdk-docs }}
       run-helm-tests: ${{ steps.selective-checks.outputs.run-helm-tests }}
       run-kubernetes-tests: ${{ steps.selective-checks.outputs.run-kubernetes-tests }}
       run-mypy-providers: ${{ steps.selective-checks.outputs.run-mypy-providers }}
@@ -1082,6 +1083,38 @@ jobs:
           if-no-files-found: error
           overwrite: 'true'
 
+  build-ts-sdk-docs:
+    name: "TypeScript SDK docs"
+    needs: [build-info]
+    runs-on: ${{ fromJSON(needs.build-info.outputs.runner-type) }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    if: needs.build-info.outputs.run-ts-sdk-docs == 'true'
+    env:
+      GITHUB_REPOSITORY: ${{ github.repository }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GITHUB_USERNAME: ${{ github.actor }}
+      VERBOSE: "true"
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - name: "Install Breeze"
+        uses: ./.github/actions/breeze
+      - name: "Build TypeScript SDK API reference"
+        run: breeze build-docs --sdk-docs-only --sdk=typescript
+      - name: "Upload TypeScript SDK docs artifact"
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: ts-sdk-docs
+          path: generated/_build/docs/ts-sdk/
+          retention-days: 7
+          if-no-files-found: error
+          overwrite: 'true'
+
   tests-airflow-ctl:
     name: "Airflow CTL tests"
     uses: ./.github/workflows/airflow-distributions-tests.yml
@@ -1137,6 +1170,7 @@ jobs:
       - tests-go-sdk
       - tests-java-sdk
       - build-java-sdk-docs
+      - build-ts-sdk-docs
       - tests-with-lowest-direct-resolution-core
       - tests-with-lowest-direct-resolution-providers
     uses: ./.github/workflows/finalize-tests.yml

.github/workflows/ci-arm.yml

@@ -127,6 +127,7 @@ jobs:
       run-coverage: ${{ steps.source-run-info.outputs.run-coverage }}
       run-go-sdk-tests: ${{ steps.selective-checks.outputs.run-go-sdk-tests }}
       run-java-sdk-tests: ${{ steps.selective-checks.outputs.run-java-sdk-tests }}
+      run-ts-sdk-docs: ${{ steps.selective-checks.outputs.run-ts-sdk-docs }}
       run-helm-tests: ${{ steps.selective-checks.outputs.run-helm-tests }}
       run-kubernetes-tests: ${{ steps.selective-checks.outputs.run-kubernetes-tests }}
       run-mypy-providers: ${{ steps.selective-checks.outputs.run-mypy-providers }}
@@ -1071,6 +1072,38 @@ jobs:
           if-no-files-found: error
           overwrite: 'true'
 
+  build-ts-sdk-docs:
+    name: "TypeScript SDK docs"
+    needs: [build-info]
+    runs-on: ${{ fromJSON(needs.build-info.outputs.runner-type) }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    if: needs.build-info.outputs.run-ts-sdk-docs == 'true'
+    env:
+      GITHUB_REPOSITORY: ${{ github.repository }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GITHUB_USERNAME: ${{ github.actor }}
+      VERBOSE: "true"
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - name: "Install Breeze"
+        uses: ./.github/actions/breeze
+      - name: "Build TypeScript SDK API reference"
+        run: breeze build-docs --sdk-docs-only --sdk=typescript
+      - name: "Upload TypeScript SDK docs artifact"
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: ts-sdk-docs
+          path: generated/_build/docs/ts-sdk/
+          retention-days: 7
+          if-no-files-found: error
+          overwrite: 'true'
+
   tests-airflow-ctl:
     name: "Airflow CTL tests"
     uses: ./.github/workflows/airflow-distributions-tests.yml
@@ -1126,6 +1159,7 @@ jobs:
       - tests-go-sdk
       - tests-java-sdk
       - build-java-sdk-docs
+      - build-ts-sdk-docs
       - tests-with-lowest-direct-resolution-core
       - tests-with-lowest-direct-resolution-providers
     uses: ./.github/workflows/finalize-tests.yml

.github/workflows/publish-docs-to-s3.yml

@@ -356,18 +356,19 @@ jobs:
           INCLUDE_COMMITS: ${{ startsWith(inputs.ref, 'providers') && 'true' || 'false' }}
           FAIL_ON_INVENTORIES: ${{ inputs.ignore-missing-inventories != true && '--fail-on-missing-third-party-inventories' || '' }}
         run: |
-          # The Java SDK docs are built with Dokka by the separate build-java-sdk-docs job;
-          # java-sdk is not a Sphinx package, so it must not be passed to breeze build-docs.
+          # The language SDK docs are built by their own jobs with their native toolchains
+          # (Dokka for java-sdk, TypeDoc for ts-sdk). Neither is a Sphinx package, so they
+          # must not be passed to breeze build-docs.
           SPHINX_INCLUDE_DOCS=""
           for package in ${INCLUDE_DOCS}; do
-            if [[ "${package}" != "java-sdk" ]]; then
+            if [[ "${package}" != "java-sdk" && "${package}" != "ts-sdk" ]]; then
               SPHINX_INCLUDE_DOCS="${SPHINX_INCLUDE_DOCS} ${package}"
             fi
           done
           if [[ -n "${INCLUDE_DOCS}" && -z "${SPHINX_INCLUDE_DOCS// /}" ]]; then
-            echo "Only java-sdk docs were requested - skipping the Sphinx docs build."
+            echo "Only language SDK docs were requested - skipping the Sphinx docs build."
             mkdir -p generated/_build/docs
-            echo "The Sphinx docs build was skipped: only java-sdk docs were requested." \
+            echo "The Sphinx docs build was skipped: only language SDK docs were requested." \
               > generated/_build/docs/sphinx-build-skipped.txt
             echo "sphinx-build-skipped=true" >> "${GITHUB_OUTPUT}"
           else
@@ -489,14 +490,80 @@ jobs:
           if-no-files-found: 'error'
           overwrite: 'true'
 
+  build-ts-sdk-docs:
+    needs: [build-info]
+    timeout-minutes: 30
+    name: "Build TypeScript SDK API reference"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    env:
+      GITHUB_REPOSITORY: ${{ github.repository }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GITHUB_USERNAME: ${{ github.actor }}
+      VERBOSE: "true"
+    outputs:
+      built: ${{ steps.sdk-present.outputs.exists }}
+    steps:
+      - name: "Checkout ${{ inputs.ref }}"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.ref }}
+      - name: "Decide whether to build the TypeScript SDK API reference"
+        id: sdk-present
+        env:
+          REF: ${{ inputs.ref }}
+          INCLUDE_DOCS: ${{ inputs.include-docs }}
+        run: |
+          # Mirrors the java-sdk rule: only build for full doc builds (include-docs == 'all')
+          # or when 'ts-sdk' is explicitly listed. A providers-only publish wave must not
+          # refresh the ts-sdk docs as a side effect.
+          if [[ "${INCLUDE_DOCS}" != "all" && " ${INCLUDE_DOCS} " != *" ts-sdk "* ]]; then
+            echo "exists=false" >> "${GITHUB_OUTPUT}"
+            echo "include-docs='${INCLUDE_DOCS}' is a specific package list without 'ts-sdk' — skipping TypeDoc build."
+          elif [[ -f "ts-sdk/docs/typedoc.json" ]]; then
+            echo "exists=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "exists=false" >> "${GITHUB_OUTPUT}"
+            echo "ts-sdk/docs/ not found at ref ${REF} — skipping TypeDoc build."
+          fi
+      - name: "Install Breeze"
+        if: steps.sdk-present.outputs.exists == 'true'
+        uses: ./.github/actions/breeze
+      # The TypeDoc toolchain is installed with `npm ci` inside the build container, which
+      # reads its download cache from HOME. Without this the ~250 pinned packages are
+      # fetched from the registry on every run.
+      - name: "Cache TypeDoc toolchain downloads"
+        if: steps.sdk-present.outputs.exists == 'true'
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ts-sdk/docs/.npm-home/.npm
+          key: ts-sdk-docs-npm-${{ hashFiles('ts-sdk/docs/package-lock.json') }}
+          restore-keys: ts-sdk-docs-npm-
+      - name: "Build TypeScript SDK API reference"
+        if: steps.sdk-present.outputs.exists == 'true'
+        run: breeze build-docs --sdk-docs-only --sdk=typescript
+      - name: "Upload TypeScript SDK docs"
+        if: steps.sdk-present.outputs.exists == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: ts-sdk-docs
+          path: generated/_build/docs/ts-sdk/
+          retention-days: '7'
+          if-no-files-found: 'error'
+          overwrite: 'true'
+
   publish-docs-to-s3:
-    needs: [build-docs, build-java-sdk-docs, build-info, update-registry]
+    needs: [build-docs, build-java-sdk-docs, build-ts-sdk-docs, build-info, update-registry]
     # `update-registry` is skipped for non-provider distributions, and a job whose dependency was
     # skipped is skipped in turn, so its result is checked rather than implied - which means the
     # two that are not conditional have to be asserted here as well.
     if: >
       !cancelled() && needs.build-docs.result == 'success' &&
       needs.build-java-sdk-docs.result == 'success' &&
+      needs.build-ts-sdk-docs.result == 'success' &&
       needs.update-registry.result != 'failure'
     name: "Publish documentation to S3"
     permissions:
@@ -542,6 +609,12 @@ jobs:
         with:
           name: java-sdk-docs
           path: generated/_build/docs/java-sdk
+      - name: "Download TypeScript SDK docs artifact"
+        if: needs.build-ts-sdk-docs.outputs.built == 'true'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: ts-sdk-docs
+          path: generated/_build/docs/ts-sdk
       - name: "Make sure SBOM dir exists and has the right permissions"
         run: |
           sudo mkdir -vp ./files/sbom

airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst

@@ -26,14 +26,19 @@ The TypeScript SDK lets you implement Airflow task logic in TypeScript (or plain
 Node.js. The Dag and its scheduling remain in Python; individual tasks delegate to a Node.js subprocess that
 is spawned by :class:`~airflow.sdk.coordinators.node.NodeCoordinator` for each task instance.
 
-The SDK is the ``@apache-airflow/ts-sdk`` package (ESM-only). It is currently in **alpha** and its API may change.
+The SDK is an ESM-only package that ships from the ``ts-sdk/`` directory of the Airflow repository. It is currently in **alpha** and its API may change.
 
 .. warning::
 
   The SDK is not yet published to npm. To try it today, build it from source in the
   `ts-sdk/ <https://github.com/apache/airflow/tree/main/ts-sdk>`__ directory of the Airflow repository and
   depend on it locally (see ``ts-sdk/example/`` for a working setup).
 
+.. seealso::
+
+  For the full TypeScript API reference (task handlers, ``TaskClient``, and the coordinator runtime),
+  see the `TypeScript SDK API reference <https://airflow.apache.org/docs/ts-sdk/stable/>`__.
+
 .. contents:: Contents
    :local:
    :depth: 2

dev/breeze/doc/ci/04_selective_checks.md

@@ -595,6 +595,7 @@ GitHub Actions to pass the list of parameters to a command to execute
 | run-mypy                                                | Whether mypy check is supposed to run in this build                                                     | true                                     |      |
 | run-system-tests                                        | Whether system tests should be run ("true"/"false")                                                     | true                                     |      |
 | run-task-sdk-tests                                      | Whether Task SDK tests should be run ("true"/"false")                                                   | true                                     |      |
+| run-ts-sdk-docs                                         | Whether the TypeScript SDK API reference should be built — on `ts-sdk/docs/` or `ts-sdk/src/` changes, including Markdown ("true"/"false")          | true                                     |      |
 | run-ts-sdk-e2e-tests                                    | Whether TypeScript SDK e2e tests should be run — on `ts-sdk/`, TS e2e test, or Node coordinator changes ("true"/"false")          | true                                     |      |
 | run-ui-tests                                            | Whether UI tests should be run ("true"/"false")                                                         | true                                     |      |
 | run-unit-tests                                          | Whether unit tests should be run ("true"/"false")                                                       | true                                     |      |