docs: implement Phase 2 - API documentation with TypeDoc

Set up TypeDoc to auto-generate comprehensive API reference documentation from TypeScript source code. Changes: - Installed typedoc and typedoc-plugin-markdown (v0.2.0 plugins) - Created typedoc.json configuration with 9 entry points - Added docs:api and docs:watch npm scripts - Fixed test file imports (validateNamespace → isValidNamespace) - Updated tsconfig.json to exclude test files from compilation - Generated markdown API documentation in docs/api-reference/generated/ Generated API documentation: - 9 modules documented (lib/, hooks/, types/) - lib/crypto - 14 encryption/certificate functions - lib/controller - 5 Kubernetes API functions - lib/validators - 6 validation functions - lib/retry - Exponential backoff utilities - lib/rbac - RBAC permission checking - types - Result types, branded types, interfaces - hooks/useSealedSecretEncryption - Encryption React hook - hooks/usePermissions - RBAC React hooks - hooks/useControllerHealth - Health monitoring hook Benefits: - Auto-generated from TypeScript source (stays in sync) - Markdown format for easy integration - Type signatures and JSDoc included - Function parameters and return types documented - Links between related types and functions Phase 2 deliverables (2-3 days estimated, completed in 1 session): ✅ TypeDoc installed and configured ✅ Entry points identified for all core modules ✅ API documentation generated (9 modules, 40+ functions) ✅ npm scripts added for docs generation ✅ Test files excluded from documentation Next: Phase 3 - User tutorials and guides Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
2026-02-11 23:27:18 -05:00
parent bdf19cd3bf
commit ebbdb42c05
98 changed files with 2951 additions and 5702 deletions
@@ -0,0 +1,21 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../README.md) / lib/controller
+
+# lib/controller
+
+## Interfaces
+
+- [ControllerHealthStatus](interfaces/ControllerHealthStatus.md)
+
+## Functions
+
+- [getControllerProxyURL](functions/getControllerProxyURL.md)
+- [fetchPublicCertificate](functions/fetchPublicCertificate.md)
+- [verifySealedSecret](functions/verifySealedSecret.md)
+- [rotateSealedSecret](functions/rotateSealedSecret.md)
+- [getPluginConfig](functions/getPluginConfig.md)
+- [savePluginConfig](functions/savePluginConfig.md)
+- [checkControllerHealth](functions/checkControllerHealth.md)
@@ -0,0 +1,30 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / checkControllerHealth
+
+# Function: checkControllerHealth()
+
+> **checkControllerHealth**(`config`): [`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`ControllerHealthStatus`](../interfaces/ControllerHealthStatus.md), `string`\>
+
+Defined in: [src/lib/controller.ts:185](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L185)
+
+Check controller health and reachability
+
+Attempts to reach the controller's health endpoint (/healthz) with a 5-second timeout.
+Returns health status including latency and version information if available.
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+Plugin configuration
+
+## Returns
+
+[`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`ControllerHealthStatus`](../interfaces/ControllerHealthStatus.md), `string`\>
+
+Result containing health status (never fails - returns status even if unreachable)
@@ -0,0 +1,33 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / fetchPublicCertificate
+
+# Function: fetchPublicCertificate()
+
+> **fetchPublicCertificate**(`config`): [`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`PEMCertificate`](../../../types/type-aliases/PEMCertificate.md), `string`\>
+
+Defined in: [src/lib/controller.ts:70](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L70)
+
+Fetch the controller's public certificate with retry logic
+
+Automatically retries on network errors with exponential backoff:
+- Max 3 attempts
+- Initial delay: 1s
+- Max delay: 10s
+- Exponential backoff with jitter
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+Plugin configuration
+
+## Returns
+
+[`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`PEMCertificate`](../../../types/type-aliases/PEMCertificate.md), `string`\>
+
+Result containing PEM-encoded certificate (branded type) or error message
@@ -0,0 +1,27 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / getControllerProxyURL
+
+# Function: getControllerProxyURL()
+
+> **getControllerProxyURL**(`config`, `path`): `string`
+
+Defined in: [src/lib/controller.ts:30](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L30)
+
+Build the controller proxy URL
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+### path
+
+`string`
+
+## Returns
+
+`string`
@@ -0,0 +1,17 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / getPluginConfig
+
+# Function: getPluginConfig()
+
+> **getPluginConfig**(): [`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+Defined in: [src/lib/controller.ts:151](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L151)
+
+Get plugin configuration from localStorage
+
+## Returns
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
@@ -0,0 +1,33 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / rotateSealedSecret
+
+# Function: rotateSealedSecret()
+
+> **rotateSealedSecret**(`config`, `sealedSecretYaml`): [`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<`string`, `string`\>
+
+Defined in: [src/lib/controller.ts:119](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L119)
+
+Rotate (re-encrypt) a SealedSecret with the current active key
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+Plugin configuration
+
+### sealedSecretYaml
+
+`string`
+
+YAML or JSON of the SealedSecret
+
+## Returns
+
+[`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<`string`, `string`\>
+
+Result containing the re-encrypted SealedSecret or error message
@@ -0,0 +1,23 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / savePluginConfig
+
+# Function: savePluginConfig()
+
+> **savePluginConfig**(`config`): `void`
+
+Defined in: [src/lib/controller.ts:172](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L172)
+
+Save plugin configuration to localStorage
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+## Returns
+
+`void`
@@ -0,0 +1,33 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / verifySealedSecret
+
+# Function: verifySealedSecret()
+
+> **verifySealedSecret**(`config`, `sealedSecretYaml`): [`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<`boolean`, `string`\>
+
+Defined in: [src/lib/controller.ts:87](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L87)
+
+Verify that a SealedSecret can be decrypted by the controller
+
+## Parameters
+
+### config
+
+[`PluginConfig`](../../../types/interfaces/PluginConfig.md)
+
+Plugin configuration
+
+### sealedSecretYaml
+
+`string`
+
+YAML or JSON of the SealedSecret
+
+## Returns
+
+[`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<`boolean`, `string`\>
+
+Result containing verification status or error message
@@ -0,0 +1,61 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/controller](../README.md) / ControllerHealthStatus
+
+# Interface: ControllerHealthStatus
+
+Defined in: [src/lib/controller.ts:14](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L14)
+
+Controller health status information
+
+## Properties
+
+### healthy
+
+> **healthy**: `boolean`
+
+Defined in: [src/lib/controller.ts:16](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L16)
+
+Whether the controller is healthy and responding
+
+***
+
+### reachable
+
+> **reachable**: `boolean`
+
+Defined in: [src/lib/controller.ts:18](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L18)
+
+Whether the controller is reachable
+
+***
+
+### version?
+
+> `optional` **version**: `string`
+
+Defined in: [src/lib/controller.ts:20](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L20)
+
+Controller version if available
+
+***
+
+### latencyMs?
+
+> `optional` **latencyMs**: `number`
+
+Defined in: [src/lib/controller.ts:22](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L22)
+
+Response latency in milliseconds
+
+***
+
+### error?
+
+> `optional` **error**: `string`
+
+Defined in: [src/lib/controller.ts:24](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/controller.ts#L24)
+
+Error message if not healthy