ci: check the public type surface with api-extractor

.github/workflows/test.yaml

@@ -106,6 +106,34 @@ jobs:
       # builds its own dependency tree, which is why it is a separate job.
       - name: Entry-point load test
         run: node scripts/entry-load.mjs reactfire-${{ github.run_id }}/reactfire.tgz --react ${{ matrix.react }}
+  check-api:
+    runs-on: ubuntu-latest
+    name: Check API surface
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - name: Setup node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '24'
+          cache: 'npm'
+      - name: Install deps
+        run: npm ci
+      # vite build, not tsc: tsconfig.json sets noEmit, so tsc is a type check
+      # only. @rollup/plugin-typescript inside the vite build is what emits the
+      # declarations api-extractor reads.
+      - name: Build declarations
+        run: npx vite build
+      # Fails when the emitted public type surface no longer matches the
+      # committed report in etc/. The report is generated (npm run api:report)
+      # and never hand-edited, so a type change shows up as a reviewable diff in
+      # the pull request. Needs no network and no published release to compare
+      # against, which is what 4.2.4 lacked when it shipped a breaking type
+      # change as a patch (#749).
+      - name: API report
+        run: npm run api:check
   test:
     runs-on: ubuntu-latest
     needs: build
@@ -176,7 +204,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     name: Publish (NPM)
-    needs: [test, verify-package, verify-loads]
+    needs: [test, verify-package, verify-loads, check-api]
     if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'release' }}
     steps:
       - name: Setup node

.gitignore

@@ -29,3 +29,6 @@ unpack.sh
 example/.parcel-cache/
 .firebaserc
 stats.html
+
+# api-extractor scratch output
+temp/

api-extractor.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  // Runs against the emitted declarations, not src, so what is reported is what
+  // consumers actually resolve.
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+
+  "compiler": {
+    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
+  },
+
+  // The committed report is the whole point: a change to the public type surface
+  // shows up as a diff in review, and CI fails when the report is out of date.
+  // Generated, never hand-edited.
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/etc/",
+    "reportFileName": "reactfire.api.md"
+  },
+
+  "docModel": { "enabled": false },
+  "dtsRollup": { "enabled": false },
+  "tsdocMetadata": { "enabled": false },
+
+  "messages": {
+    // Missing release tags are not interesting here; the repo does not use them.
+    "extractorMessageReporting": {
+      "ae-missing-release-tag": { "logLevel": "none" },
+      "ae-forgotten-export": { "logLevel": "warning" }
+    },
+    "tsdocMessageReporting": {
+      "default": { "logLevel": "none" }
+    }
+  }
+}