feat: use typedoc and config to generate API methods and types in mar…

.gitignore

@@ -26,6 +26,9 @@ pnpm-debug.log*
 Thumbs.db
 
 # Test coverage
-coverage/ 
+coverage/
 # Temporary files
 tmp/
+
+# Generated documentation
+docs/generated/

README.md

@@ -475,6 +475,48 @@ interface BaasClientConfig {
 
 If you're upgrading from v4.x, see [MIGRATION.md](MIGRATION.md) for detailed migration instructions.
 
+## Documentation Generation
+
+The SDK includes automated documentation generation using [TypeDoc](https://typedoc.org/) and [typedoc-plugin-markdown](https://www.npmjs.com/package/typedoc-plugin-markdown) to generate comprehensive markdown documentation organized into 3 separate sections (Client/Bridge, v1 API, v2 API).
+
+### Generate Documentation
+
+```bash
+pnpm docs:generate    # Generate all documentation
+pnpm docs:clean       # Clean generated docs
+```
+
+### Configuration
+
+Documentation generation is configured using three separate TypeDoc configuration files:
+
+- **`typedoc.config.mjs`** - Client/Bridge documentation
+  - Entry points: `src/node/client.ts`, `src/node/types.d.ts`
+  - Output: `docs/generated/client/`
+  - Documents: `createBaasClient()` factory and configuration types
+
+- **`typedoc.v1.config.mjs`** - v1 API documentation
+  - Entry points: `src/node/v1-methods.ts`, `src/node/types.d.ts`
+  - Output: `docs/generated/v1/`
+  - Documents: v1 methods like `joinMeeting()`, `leaveMeeting()`, etc.
+  - Excludes: v2-specific code and types
+
+- **`typedoc.v2.config.mjs`** - v2 API documentation
+  - Entry points: `src/node/v2-methods.ts`, `src/node/types.d.ts`
+  - Output: `docs/generated/v2/`
+  - Documents: v2 methods like `createBot()`, `batchCreateBots()`, etc.
+  - Excludes: v1-specific code and types
+
+### Output Structure
+
+Documentation is output to `docs/generated/` with a landing page at [INDEX.md](docs/generated/INDEX.md) showing v1 vs v2 comparisons and navigation to:
+
+- **Client/Bridge API** (`docs/generated/client/`) - How to use `createBaasClient()` with type-safe version selection
+- **v1 API Reference** (`docs/generated/v1/`) - Complete v1 API methods and types
+- **v2 API Reference** (`docs/generated/v2/`) - Complete v2 API methods and types
+
+See [ADDING_NEW_API_VERSION.md](ADDING_NEW_API_VERSION.md) for details on adding new API versions to the SDK.
+
 ## Contributing
 
 We welcome contributions! Please see [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.

package.json

@@ -41,6 +41,11 @@
     "openapi:generate:v2": "pnpm openapi:clean:v2 && orval --config orval.config.ts baasApiV2 baasZodV2",
     "openapi:rebuild": "pnpm openapi:generate && pnpm build",
     "openapi:rebuild:v2": "pnpm openapi:generate:v2 && pnpm build",
+    "docs:clean": "rm -rf docs/generated",
+    "docs:generate": "pnpm docs:clean && pnpm docs:generate:v1 && pnpm docs:generate:v2 && pnpm docs:generate:client",
+    "docs:generate:client": "typedoc --options typedoc.config.mjs",
+    "docs:generate:v1": "typedoc --options typedoc.v1.config.mjs",
+    "docs:generate:v2": "typedoc --options typedoc.v2.config.mjs",
     "prepublishOnly": "pnpm lint:fix && pnpm build"
   },
   "publishConfig": {
@@ -79,6 +84,8 @@
     "orval": "^7.9.0",
     "ts-node": "10.9.2",
     "tsup": "8.4.0",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "5.8.2",
     "vitest": "^2.1.8"
   },

typedoc.config.mjs

@@ -0,0 +1,55 @@
+/** @type {import('typedoc').TypeDocOptions} */
+export default {
+  // Entry points - Client abstraction/bridge
+  entryPoints: [
+    "./src/node/client.ts",
+    "./src/node/types.d.ts"
+  ],
+
+  out: "./docs/generated/client",
+  plugin: ["typedoc-plugin-markdown"],
+
+  // Output settings
+  outputFileStrategy: "modules",
+  readme: "none",
+
+  // Source settings
+  disableSources: true,
+  excludeExternals: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  excludeInternal: true,
+
+  // Exclude test files only
+  exclude: [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/test/**/*",
+    "**/examples/**/*"
+  ],
+
+  includeVersion: true,
+  tsconfig: "./tsconfig.json",
+
+  // Organization
+  categorizeByGroup: true,
+  defaultCategory: "Other",
+
+  sort: ["kind", "required-first", "alphabetical"],
+  sortEntryPoints: true,
+
+  kindSortOrder: [
+    "Function",
+    "Interface",
+    "TypeAlias",
+    "Enum"
+  ],
+
+  // Keep readable - don't expand too deeply
+  maxTypeConversionDepth: 4,
+
+  hideGenerator: true,
+  githubPages: false,
+
+  name: "@meeting-baas/sdk - Client API & Bridge"
+};

typedoc.v1.config.mjs

@@ -0,0 +1,55 @@
+/** @type {import('typedoc').TypeDocOptions} */
+export default {
+  // V1 API Documentation - Include methods AND types
+  entryPoints: [
+    "./src/node/v1-methods.ts",
+    "./src/node/types.d.ts"
+  ],
+
+  out: "./docs/generated/v1",
+  plugin: ["typedoc-plugin-markdown"],
+
+  // Output settings
+  outputFileStrategy: "modules",
+  readme: "none",
+
+  // Source settings
+  disableSources: true,
+  excludeExternals: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  excludeInternal: true,
+
+  // Exclude test files and v2-specific types
+  exclude: [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/test/**/*",
+    "**/src/node/v2-methods.ts",
+    "**/src/generated/v2/**/*"
+  ],
+
+  includeVersion: true,
+  tsconfig: "./tsconfig.json",
+
+  // Organization
+  categorizeByGroup: true,
+  defaultCategory: "Methods",
+
+  sort: ["kind", "required-first", "alphabetical"],
+  sortEntryPoints: true,
+
+  kindSortOrder: [
+    "Function",
+    "Interface",
+    "TypeAlias"
+  ],
+
+  // Limit depth for readability
+  maxTypeConversionDepth: 4,
+
+  hideGenerator: true,
+  githubPages: false,
+
+  name: "@meeting-baas/sdk - v1 API Reference"
+};

typedoc.v2.config.mjs

@@ -0,0 +1,55 @@
+/** @type {import('typedoc').TypeDocOptions} */
+export default {
+  // V2 API Documentation - Include methods AND types
+  entryPoints: [
+    "./src/node/v2-methods.ts",
+    "./src/node/types.d.ts"
+  ],
+
+  out: "./docs/generated/v2",
+  plugin: ["typedoc-plugin-markdown"],
+
+  // Output settings
+  outputFileStrategy: "modules",
+  readme: "none",
+
+  // Source settings
+  disableSources: true,
+  excludeExternals: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  excludeInternal: true,
+
+  // Exclude test files and v1-specific types
+  exclude: [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/test/**/*",
+    "**/src/node/v1-methods.ts",
+    "**/src/generated/v1/**/*"
+  ],
+
+  includeVersion: true,
+  tsconfig: "./tsconfig.json",
+
+  // Organization
+  categorizeByGroup: true,
+  defaultCategory: "Methods",
+
+  sort: ["kind", "required-first", "alphabetical"],
+  sortEntryPoints: true,
+
+  kindSortOrder: [
+    "Function",
+    "Interface",
+    "TypeAlias"
+  ],
+
+  // Limit depth for readability
+  maxTypeConversionDepth: 4,
+
+  hideGenerator: true,
+  githubPages: false,
+
+  name: "@meeting-baas/sdk - v2 API Reference"
+};