feat: generate v1 API client from OpenAPI

.github/workflows/ci.yml

@@ -29,6 +29,14 @@ jobs:
         working-directory: nodejs
         run: pnpm install --frozen-lockfile
 
+      - name: Check generated client
+        working-directory: nodejs
+        run: pnpm check:generated
+
+      - name: Typecheck
+        working-directory: nodejs
+        run: pnpm typecheck
+
       - name: Run lint
         working-directory: nodejs
         run: pnpm lint
@@ -37,6 +45,10 @@ jobs:
         working-directory: nodejs
         run: pnpm build
 
+      - name: Build API reference
+        working-directory: nodejs
+        run: pnpm docs:build
+
       - name: Run tests
         working-directory: nodejs
         env:

.github/workflows/pages.yml

@@ -0,0 +1,55 @@
+name: API reference
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10.33.2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: nodejs/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: nodejs
+        run: pnpm install --frozen-lockfile
+
+      - name: Build API reference
+        working-directory: nodejs
+        run: pnpm docs:build
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: nodejs/.docs-dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

nodejs/.eslintignore

@@ -0,0 +1 @@
+src/generated/

nodejs/.gitignore

@@ -82,6 +82,7 @@ web_modules/
 # Nuxt.js build / generate output
 .nuxt
 dist
+.docs-dist/
 
 # Gatsby files
 .cache/

nodejs/.stackblitzrc

@@ -0,0 +1,3 @@
+{
+  "startCommand": "pnpm build"
+}

nodejs/README.md

@@ -87,6 +87,7 @@ const client = new HackMDAPI('YOUR_ACCESS_TOKEN', 'https://api.hackmd.io/v1', {
 ```
 
 The client will automatically retry requests that fail with:
+
 - 5xx server errors
 - 429 Too Many Requests errors
 - Network errors
@@ -105,16 +106,28 @@ const data = await client.getMe({ unwrapData: true })
 
 ### ETag Support
 
-The client supports ETag-based caching for note retrieval. You can pass an ETag to check if the content has changed:
+The client can send an ETag to check whether a note changed. The server
+generates the ETag and decides whether to return 304; the client does not cache
+the note body for you:
 
 ```javascript
-// First request
-const note = await client.getNote('note-id')
-const etag = note.etag
+const first = await client.getNote('note-id', { unwrapData: false })
+const response = await client.getNote('note-id', {
+  etag: first.headers.etag,
+  unwrapData: false,
+})
+// 304 has no body; keep first.data. Otherwise, use response.data.
+const note = response.status === 304 ? first.data : response.data
+```
 
-// Subsequent request with ETag
-const updatedNote = await client.getNote('note-id', { etag })
-// If the note hasn't changed, the response will have status 304
+Team notes work the same way through the existing client:
+
+```javascript
+const teamFirst = await client.getTeamNote('team-path', 'note-id')
+const teamResponse = await client.getTeamNote('team-path', 'note-id', {
+  etag: teamFirst.etag,
+})
+const teamNote = teamResponse.status === 304 ? teamFirst : teamResponse
 ```
 
 ### Image Upload
@@ -134,20 +147,117 @@ const uploadedFromNode = await client.uploadNoteImage('note-id', image, {
 console.log(uploadedFromNode.data.link)
 ```
 
+### Webhooks
+
+Manage personal or team webhooks through the same `API` client. Save the secret
+returned by `createWebhook` when you create a webhook; later reads do not return it.
+
+```javascript
+const webhook = await client.createWebhook({
+  scope: { type: 'workspace' },
+  url: 'https://example.com/webhook',
+})
+console.log(webhook.secret)
+
+const teamWebhooks = await client.listTeamWebhooks('team-path')
+```
+
+`listWebhookDeliveries('hook-id', { page: 1, limit: 20 })` returns delivery data
+and pagination metadata. `exportWebhookDeliveries('hook-id')` returns
+newline-delimited JSON as a string; parse the lines yourself if needed.
+
+### Trash
+
+Use `listTrash()` or `listTeamTrash('team-path')` to find deleted notes.
+`restoreNote('note-id')` restores one note; `batchRestore({ noteIds })` reports
+success or failure for each note. Pass `{ unwrapData: false }` to inspect the
+batch HTTP status (200 or 207).
+
+### Versions
+
+`listVersions('note-id', { named_only: true, page: 1, limit: 20 })` lists saved
+versions. Use `getVersion('note-id', versionId)` for content, or
+`compareVersions('note-id', { base: 'version:<id>', target: 'note_content' })`
+to compare it with the live note. `createVersion` and `updateVersion` accept the
+corresponding OpenAPI request bodies.
+
+### Comments
+
+Use `listNoteComments('note-id', { page: 1, limit: 20, threadStatus: 'open' })`
+to browse comments. `getNoteComment('note-id', commentId)` reads one comment;
+`resolveNoteComment` and `unresolveNoteComment` return the updated comment and
+any affected thread.
+
+### Generated Raw API
+
+The `@hackmd/api/raw` entry point exposes every OpenAPI operation as a generated,
+one-to-one function. Create a client to share authentication and the API endpoint:
+
+```typescript
+import { createClient, getNote } from '@hackmd/api/raw'
+
+const client = createClient({
+  auth: 'YOUR_ACCESS_TOKEN',
+  baseURL: 'https://api.hackmd.io/v1',
+})
+
+const response = await getNote({
+  client,
+  path: { noteId: 'NOTE_ID' },
+  throwOnError: true,
+})
+
+console.log(response.data.content)
+```
+
+The package root retains the existing `API` class. Files under
+`src/generated` are generated from the vendored OpenAPI document and must not
+be edited manually.
+
+On `API`, `listNotes`, `listFolders`, `listTeamNotes`, `listTeamFolders`, and
+`listTeams` match the OpenAPI operation names. Existing `getNoteList`,
+`getFolderList`, `getTeamNotes`, `getTeamFolderList`, and `getTeams` remain
+compatible aliases.
+
 ## API
 
-See the [code](./src/index.ts) and [typings](./src/type.ts). The API client is written in TypeScript, so you can get auto-completion and type checking in any TypeScript Language Server powered editor or IDE.
+The [API reference](https://hackmdio.github.io/api-client/) covers the existing
+`API` class and every raw operation and DTO. To explore autocomplete
+without a real token, open the type-only example:
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/fork/github/hackmdio/api-client/tree/master/nodejs?file=tests/types/playground.mts)
+
+The Pages site is deployed from `master` only.
+
+Run `pnpm docs:dev` from `nodejs` and open `http://127.0.0.1:3000` to preview
+the reference locally. It builds the HTML once before serving; rerun the
+command after changing source or docs. The output in `.docs-dist` is not
+committed.
+
+## Regenerating the raw client
+
+Generation requires Node.js 22.18 or newer.
+
+```bash
+pnpm spec:pull
+pnpm codegen
+pnpm check:generated
+```
+
+The OpenAPI document is committed at `spec/hackmd-openapi.json`, and generated
+sources are committed under `src/generated` so package builds remain offline and
+deterministic.
 
 ## E2E tests (live API)
 
 Integration tests call a real HackMD API (staging or production). They are **not** run by `pnpm test` or the default CI job.
 
-**Requirements**
+## Requirements
 
 - `HACKMD_ACCESS_TOKEN` — a valid personal access token for the environment you target.
 - Optional: `HACKMD_API_ENDPOINT` — defaults to `https://api.hackmd.io/v1`. For staging, use `https://api-stage.hackmd.io/v1`.
 
-**Read-only (default e2e)**
+## Read-only (default e2e)
 
 ```bash
 cd nodejs
@@ -156,7 +266,7 @@ export HACKMD_API_ENDPOINT=https://api-stage.hackmd.io/v1   # optional
 pnpm test:e2e
 ```
 
-**With CRUD / mutations**
+## With CRUD / mutations
 
 Set `HACKMD_E2E_MUTATIONS=1` to run write tests against your account:
 

nodejs/docs/README.md

@@ -0,0 +1,40 @@
+# HackMD API for TypeScript
+
+This reference covers the existing `API` class and every generated operation
+and type in `@hackmd/api/raw`.
+
+```sh
+npm install @hackmd/api
+```
+
+## API client
+
+```ts
+import { API } from '@hackmd/api'
+
+const client = new API('YOUR_ACCESS_TOKEN')
+const note = await client.getNote('NOTE_ID')
+console.log(note.content)
+```
+
+Existing applications can keep using `API` and its current method signatures.
+
+## Generated raw API
+
+```ts
+import { createClient, getNote } from '@hackmd/api/raw'
+
+const client = createClient({ auth: 'YOUR_ACCESS_TOKEN' })
+const response = await getNote({ client, path: { noteId: 'NOTE_ID' }, throwOnError: true })
+console.log(response.data.content)
+```
+
+Use the raw reference for the full OpenAPI operation and DTO catalog.
+
+## Explore the types
+
+The type-only example makes no requests and requires no real token. Open it to
+explore autocomplete and type inspection; run real API calls only with your own
+token in a trusted local environment.
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/fork/github/hackmdio/api-client/tree/master/nodejs?file=tests/types/playground.mts)

nodejs/jest.config.ts

@@ -5,6 +5,9 @@ const customJestConfig: JestConfigWithTsJest = {
   testEnvironment: "node",
   transformIgnorePatterns: ["<rootDir>/node_modules/"],
   extensionsToTreatAsEsm: [".ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
   setupFiles: ["dotenv/config"],
   testPathIgnorePatterns: ["/node_modules/", "<rootDir>/tests/e2e/"],
 }

nodejs/jest.e2e.config.ts

@@ -6,6 +6,9 @@ const e2eJestConfig: JestConfigWithTsJest = {
   testEnvironment: "node",
   transformIgnorePatterns: ["<rootDir>/node_modules/"],
   extensionsToTreatAsEsm: [".ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
   setupFiles: ["dotenv/config"],
   testMatch: ["<rootDir>/tests/e2e/**/*.spec.ts"],
   testTimeout: 60_000,

nodejs/openapi-ts.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from '@hey-api/openapi-ts'
+
+export default defineConfig({
+  input: './spec/hackmd-openapi.json',
+  output: {
+    path: './src/generated',
+    module: { extension: '.js' },
+    postProcess: [{ command: 'node', args: ['scripts/generate-operation-registry.mjs'] }],
+  },
+  plugins: [
+    '@hey-api/client-axios',
+    '@hey-api/typescript',
+    '@hey-api/sdk',
+  ],
+})