chore: add dedicated TypeDoc configs for markdown documentation, add typedoc-plugin-frontmatter (#397)

andrew-kowalczyk-cb · web-flow · commit e98a66590037 · 2025-08-21T14:42:08.000-07:00
diff --git a/typescript/TYPEDOC-README.md b/typescript/TYPEDOC-README.md
diff --git a/typescript/package.json b/typescript/package.json
@@ -12,7 +12,13 @@
     "check:auth-crypto-imports": "tsx scripts/check-auth-crypto-imports.ts",
     "clean": "rm -rf src/_esm src/_cjs src/_types",
     "docs": "typedoc --options ./typedoc.json",
-    "docs:md": "typedoc --plugin typedoc-plugin-markdown --out ./docs-md",
+    "docs:md": "npm run docs:index && npm run docs:auth && npm run docs:evm && npm run docs:solana && npm run docs:policies && npm run docs:client",
+    "docs:index": "typedoc --options ./typedoc.index.json",
+    "docs:auth": "typedoc --options ./typedoc.auth.json",
+    "docs:evm": "typedoc --options ./typedoc.evm.json",
+    "docs:solana": "typedoc --options ./typedoc.solana.json",
+    "docs:policies": "typedoc --options ./typedoc.policies.json",
+    "docs:client": "typedoc --options ./typedoc.client.json",
     "format": "prettier -c .prettierrc --write \"**/*.{ts,js,cjs,json,md}\" && tsx scripts/sort-msw-index.ts",
     "format:check": "prettier -c .prettierrc --check \"**/*.{ts,js,cjs,json,md}\"",
     "lint": "eslint -c .eslintrc.json \"src/**/*.ts\"",
@@ -47,6 +53,7 @@
     "prettier": "^3.2.5",
     "tsx": "^4.19.3",
     "typedoc": "^0.28.7",
+    "typedoc-plugin-frontmatter": "^1.3.0",
     "typedoc-plugin-markdown": "^4.8.0",
     "typescript": "^5.4.5",
     "uuid": "^11.1.0",
diff --git a/typescript/pnpm-lock.yaml b/typescript/pnpm-lock.yaml
diff --git a/typescript/src/accounts/evm/types.ts b/typescript/src/accounts/evm/types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Accounts
+ */
+
 import {
   ListTokenBalancesNetworks,
   RequestFaucetNetworks,
@@ -59,8 +63,8 @@ import type {
   WaitForTransactionReceiptParameters,
 } from "viem";
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type DistributedOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;
+/** @internal */
+export type DistributedOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never; // eslint-disable-line @typescript-eslint/no-explicit-any
 
 /**
  * Base type for any Ethereum account with signing capabilities.
@@ -88,6 +92,8 @@ export type EvmAccount = {
 
 /**
  * Known EVM networks supported by the SDK.
+ *
+ * @internal
  */
 export type KnownEvmNetworks =
   | "base"
@@ -104,6 +110,8 @@ export type KnownEvmNetworks =
 
 /**
  * Network input that accepts known networks or RPC URLs
+ *
+ * @internal
  */
 export type NetworkOrRpcUrl = KnownEvmNetworks | (string & {});
 
@@ -174,6 +182,8 @@ export type EvmSmartAccount = Prettify<EvmSmartAccountProperties & SmartAccountA
 
 /**
  * Helper type for network-specific smart account actions
+ *
+ * @internal
  */
 export type NetworkSpecificSmartAccountActions<Network extends string> = Prettify<
   // Always include sendUserOperation, waitForUserOperation and getUserOperation
@@ -257,6 +267,8 @@ export type NetworkSpecificSmartAccountActions<Network extends string> = Prettif
 
 /**
  * A network-scoped smart account
+ *
+ * @internal
  */
 export type NetworkScopedEvmSmartAccount<Network extends string = string> = Prettify<
   Omit<EvmSmartAccountProperties, "useNetwork"> &
@@ -274,6 +286,8 @@ type EmptyObject = {};
 
 /**
  * Conditional account actions based on network
+ *
+ * @internal
  */
 export type NetworkSpecificAccountActions<Network extends string> = Prettify<
   // Always include sendTransaction, transfer and waitForTransactionReceipt
@@ -349,6 +363,8 @@ export type NetworkSpecificAccountActions<Network extends string> = Prettify<
 
 /**
  * A network-scoped server-managed ethereum account
+ *
+ * @internal
  */
 export type NetworkScopedEvmServerAccount<Network extends string = string> = Prettify<
   Omit<EvmServerAccount, keyof AccountActions | "useNetwork"> &
diff --git a/typescript/src/accounts/solana/types.ts b/typescript/src/accounts/solana/types.ts
@@ -1,13 +1,22 @@
+/**
+ * @module Accounts
+ */
+
 import { AccountActions } from "../../actions/solana/types.js";
 import { SolanaAccount as OpenAPISolanaAccount } from "../../openapi-client/index.js";
 import { Prettify } from "../../types/utils.js";
 
 /**
  * A base Solana account.
+ *
+ * @internal
  */
 export type Account = OpenAPISolanaAccount;
 
 /**
  * A Solana account with actions.
+ *
+ * @see {@link OpenAPISolanaAccount}
+ * @see {@link AccountActions}
  */
 export type SolanaAccount = Prettify<OpenAPISolanaAccount & AccountActions>;
diff --git a/typescript/src/actions/evm/spend-permissions/types.ts b/typescript/src/actions/evm/spend-permissions/types.ts
@@ -7,7 +7,7 @@ import type { SpendPermission } from "../../../spend-permissions/types.js";
 export type UseSpendPermissionOptions = {
   /** The spend permission to use */
   spendPermission: SpendPermission;
-  /** The amount to spend (must be <= allowance) */
+  /** The amount to spend (must be &le; allowance) */
   value: bigint;
   /** The network to execute the transaction on */
   network: SpendPermissionNetwork;
diff --git a/typescript/src/actions/evm/types.ts b/typescript/src/actions/evm/types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Actions
+ */
+
 import { FundOperationResult } from "../types.js";
 import {
   WaitForFundOperationOptions,
diff --git a/typescript/src/actions/solana/types.ts b/typescript/src/actions/solana/types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Actions
+ */
+
 import { TransferOptions } from "./transfer.js";
 import {
   RequestFaucetOptions,
diff --git a/typescript/src/auth/errors.ts b/typescript/src/auth/errors.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Errors
+ */
+
 /**
  * A class of errors for capturing stack traces.
  */
diff --git a/typescript/src/auth/hooks/axios/withAuth.ts b/typescript/src/auth/hooks/axios/withAuth.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Axios
+ */
+
 import { AxiosInstance, AxiosHeaders } from "axios";
 
 import { convertBigIntsToStrings } from "../../../utils/bigint.js";
diff --git a/typescript/src/auth/utils/hash.ts b/typescript/src/auth/utils/hash.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Hash
+ */
+
 import { subtle } from "uncrypto";
 
 /**
diff --git a/typescript/src/auth/utils/http.ts b/typescript/src/auth/utils/http.ts
@@ -1,3 +1,7 @@
+/**
+ * @module HTTP
+ */
+
 import { generateWalletJwt, generateJwt } from "./jwt.js";
 import { version } from "../../version.js";
 
diff --git a/typescript/src/auth/utils/jwt.ts b/typescript/src/auth/utils/jwt.ts
@@ -1,3 +1,7 @@
+/**
+ * @module JWT
+ */
+
 import { SignJWT, importPKCS8, importJWK, JWTPayload } from "jose";
 import { getRandomValues } from "uncrypto";
 
diff --git a/typescript/src/auth/utils/ws.ts b/typescript/src/auth/utils/ws.ts
@@ -1,3 +1,7 @@
+/**
+ * @module WebSocket
+ */
+
 import { getCorrelationData } from "./http.js";
 import { generateJwt } from "./jwt.js";
 
diff --git a/typescript/src/client/evm/evm.ts b/typescript/src/client/evm/evm.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Client
+ */
+
 import { constants, publicEncrypt } from "crypto";
 
 import { type Address, getTypesForEIP712Domain } from "viem";
diff --git a/typescript/src/client/evm/evm.types.ts b/typescript/src/client/evm/evm.types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Types
+ */
+
 import type {
   EvmAccount as Account,
   EvmServerAccount as ServerAccount,
diff --git a/typescript/src/client/policies/policies.ts b/typescript/src/client/policies/policies.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Client
+ */
+
 import {
   PoliciesClientInterface,
   CreatePolicyOptions,
diff --git a/typescript/src/client/policies/policies.types.ts b/typescript/src/client/policies/policies.types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Types
+ */
+
 import { OpenApiPoliciesMethods } from "../../openapi-client/index.js";
 import { CreatePolicyBody, Policy, PolicyScope, UpdatePolicyBody } from "../../policies/types.js";
 
diff --git a/typescript/src/client/solana/solana.ts b/typescript/src/client/solana/solana.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Client
+ */
+
 import { constants, publicEncrypt } from "crypto";
 
 import bs58 from "bs58";
diff --git a/typescript/src/client/solana/solana.types.ts b/typescript/src/client/solana/solana.types.ts
@@ -1,3 +1,7 @@
+/**
+ * @module Types
+ */
+
 import { Account, SolanaAccount } from "../../accounts/solana/types.js";
 import {
   ListSolanaTokenBalancesNetwork,
diff --git a/typescript/ts-frontmatter.mjs b/typescript/ts-frontmatter.mjs
@@ -0,0 +1,26 @@
+// @ts-check
+import { MarkdownPageEvent } from "typedoc-plugin-markdown";
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  app.renderer.on(
+    MarkdownPageEvent.BEGIN,
+    /** @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page */
+    page => {
+      /**
+       * Update page.frontmatter object using information from the page model
+       */
+
+      // Set the frontmatter title to just the name
+      page.frontmatter = {
+        // Just use the plain name
+        title: page.model?.name || "",
+        sidebarTitle: page.model?.name || "",
+        // spread the existing frontmatter
+        ...page.frontmatter,
+      };
+    },
+  );
+}
diff --git a/typescript/typedoc.auth.json b/typescript/typedoc.auth.json
@@ -0,0 +1,50 @@
+{
+  "entryPoints": [
+    "./src/auth/hooks/axios/withAuth.ts",
+    "./src/auth/utils/hash.ts",
+    "./src/auth/utils/http.ts",
+    "./src/auth/utils/jwt.ts",
+    "./src/auth/utils/ws.ts",
+    "./src/auth/errors.ts"
+  ],
+  "entryPointStrategy": "resolve",
+  "out": "./docs-md/auth",
+  "flattenOutputFiles": true,
+  "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-frontmatter"],
+  "excludePrivate": true,
+  "excludeInternal": true,
+  "excludeProtected": false,
+  "readme": "./src/auth/README.md",
+  "name": "index",
+  "includeVersion": true,
+  "sort": ["kind"],
+  "kindSortOrder": ["Function", "Class", "Interface", "TypeAlias", "Enum", "Variable"],
+  "categorizeByGroup": true,
+  "exclude": [
+    "**/tests/**/*",
+    "**/*.test.ts",
+    "**/node_modules/**/*",
+    "**/_cjs/**/*",
+    "**/_esm/**/*",
+    "**/_types/**/*",
+    "**/openapi-client/**/*"
+  ],
+  "skipErrorChecking": false,
+  "treatWarningsAsErrors": false,
+  "validation": {
+    "notExported": true,
+    "invalidLink": true,
+    "notDocumented": false
+  },
+  "fileExtension": ".mdx",
+  "entryFileName": "index",
+  "mergeReadme": true,
+  "hidePageHeader": true,
+  "hideBreadcrumbs": true,
+  "hidePageTitle": true,
+  "useCodeBlocks": true,
+  "publicPath": "/sdks/cdp-sdks-v2/typescript/auth",
+  "expandObjects": true,
+  "expandParameters": true,
+  "router": "module"
+}
diff --git a/typescript/typedoc.client.json b/typescript/typedoc.client.json
diff --git a/typescript/typedoc.evm.json b/typescript/typedoc.evm.json
diff --git a/typescript/typedoc.index.json b/typescript/typedoc.index.json
diff --git a/typescript/typedoc.policies.json b/typescript/typedoc.policies.json
diff --git a/typescript/typedoc.solana.json b/typescript/typedoc.solana.json

-Original file line number
+Diff line change
@@ @@ -1,3 +1,7 @@ @@
 +/**
 + * @module Errors
 + */
++
 /**
  * A class of errors for capturing stack traces.
  */