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,11 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../README.md) / hooks/useControllerHealth
+
+# hooks/useControllerHealth
+
+## Functions
+
+- [useControllerHealth](functions/useControllerHealth.md)
@@ -0,0 +1,65 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/useControllerHealth](../README.md) / useControllerHealth
+
+# Function: useControllerHealth()
+
+> **useControllerHealth**(`autoRefresh?`, `refreshIntervalMs?`): `object`
+
+Defined in: [src/hooks/useControllerHealth.ts:30](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useControllerHealth.ts#L30)
+
+Custom hook for monitoring controller health
+
+Automatically checks controller health on mount and can optionally
+refresh at a specified interval.
+
+## Parameters
+
+### autoRefresh?
+
+`boolean` = `false`
+
+Whether to automatically refresh health status
+
+### refreshIntervalMs?
+
+`number` = `30000`
+
+Refresh interval in milliseconds (default: 30000ms = 30s)
+
+## Returns
+
+`object`
+
+Object with health status, loading state, and manual refresh function
+
+### health
+
+> **health**: [`ControllerHealthStatus`](../../../lib/controller/interfaces/ControllerHealthStatus.md)
+
+### loading
+
+> **loading**: `boolean`
+
+### refresh()
+
+> **refresh**: () => `Promise`\<`void`\> = `fetchHealth`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+## Example
+
+```ts
+// Manual refresh only
+const { health, loading, refresh } = useControllerHealth();
+
+// Auto-refresh every 30 seconds
+const { health, loading } = useControllerHealth(true, 30000);
+
+// Auto-refresh every 10 seconds
+const { health, loading } = useControllerHealth(true, 10000);
+```
@@ -0,0 +1,14 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../README.md) / hooks/usePermissions
+
+# hooks/usePermissions
+
+## Functions
+
+- [usePermissions](functions/usePermissions.md)
+- [usePermission](functions/usePermission.md)
+- [useHasWriteAccess](functions/useHasWriteAccess.md)
+- [useIsReadOnly](functions/useIsReadOnly.md)
@@ -0,0 +1,47 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/usePermissions](../README.md) / useHasWriteAccess
+
+# Function: useHasWriteAccess()
+
+> **useHasWriteAccess**(`namespace?`): `object`
+
+Defined in: [src/hooks/usePermissions.ts:104](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/usePermissions.ts#L104)
+
+Hook to check if user has any write permissions
+
+Returns true if user can create, update, or delete.
+Useful for showing/hiding entire sections of UI.
+
+## Parameters
+
+### namespace?
+
+`string`
+
+Optional namespace to check
+
+## Returns
+
+`object`
+
+Object with loading state and hasWriteAccess flag
+
+### loading
+
+> **loading**: `boolean`
+
+### hasWriteAccess
+
+> **hasWriteAccess**: `boolean`
+
+## Example
+
+```ts
+const { loading, hasWriteAccess } = useHasWriteAccess('default');
+if (hasWriteAccess) {
+  // Show management UI
+}
+```
@@ -0,0 +1,46 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/usePermissions](../README.md) / useIsReadOnly
+
+# Function: useIsReadOnly()
+
+> **useIsReadOnly**(`namespace?`): `object`
+
+Defined in: [src/hooks/usePermissions.ts:127](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/usePermissions.ts#L127)
+
+Hook to check if user has read-only access
+
+Returns true if user can read/list but cannot create/update/delete.
+
+## Parameters
+
+### namespace?
+
+`string`
+
+Optional namespace to check
+
+## Returns
+
+`object`
+
+Object with loading state and isReadOnly flag
+
+### loading
+
+> **loading**: `boolean`
+
+### isReadOnly
+
+> **isReadOnly**: `boolean`
+
+## Example
+
+```ts
+const { loading, isReadOnly } = useIsReadOnly('default');
+if (isReadOnly) {
+  // Show read-only warning
+}
+```
@@ -0,0 +1,53 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/usePermissions](../README.md) / usePermission
+
+# Function: usePermission()
+
+> **usePermission**(`namespace`, `permission`): `object`
+
+Defined in: [src/hooks/usePermissions.ts:79](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/usePermissions.ts#L79)
+
+Hook to check a specific permission
+
+Useful when you only need to check one permission (e.g., canCreate)
+instead of fetching all permissions.
+
+## Parameters
+
+### namespace
+
+`string`
+
+Optional namespace to check
+
+### permission
+
+keyof [`ResourcePermissions`](../../../lib/rbac/interfaces/ResourcePermissions.md)
+
+Permission key to check
+
+## Returns
+
+`object`
+
+Object with loading state and allowed flag
+
+### loading
+
+> **loading**: `boolean`
+
+### allowed
+
+> **allowed**: `boolean`
+
+## Example
+
+```ts
+const { loading, allowed } = usePermission('default', 'canCreate');
+if (allowed) {
+  // Show create button
+}
+```
@@ -0,0 +1,51 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/usePermissions](../README.md) / usePermissions
+
+# Function: usePermissions()
+
+> **usePermissions**(`namespace?`): `object`
+
+Defined in: [src/hooks/usePermissions.ts:26](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/usePermissions.ts#L26)
+
+Hook to check SealedSecret permissions for a namespace
+
+Automatically fetches permissions on mount and when namespace changes.
+Returns loading state and permissions.
+
+## Parameters
+
+### namespace?
+
+`string`
+
+Optional namespace to check (cluster-wide if omitted)
+
+## Returns
+
+`object`
+
+Object with loading state, permissions, and error
+
+### loading
+
+> **loading**: `boolean`
+
+### permissions
+
+> **permissions**: [`ResourcePermissions`](../../../lib/rbac/interfaces/ResourcePermissions.md)
+
+### error
+
+> **error**: `string`
+
+## Example
+
+```ts
+const { loading, permissions, error } = usePermissions('default');
+if (!loading && permissions?.canCreate) {
+  // Show create button
+}
+```
@@ -0,0 +1,16 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../README.md) / hooks/useSealedSecretEncryption
+
+# hooks/useSealedSecretEncryption
+
+## Interfaces
+
+- [EncryptionRequest](interfaces/EncryptionRequest.md)
+- [EncryptionResult](interfaces/EncryptionResult.md)
+
+## Functions
+
+- [useSealedSecretEncryption](functions/useSealedSecretEncryption.md)
@@ -0,0 +1,57 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/useSealedSecretEncryption](../README.md) / useSealedSecretEncryption
+
+# Function: useSealedSecretEncryption()
+
+> **useSealedSecretEncryption**(): `object`
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:73](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L73)
+
+Custom hook for SealedSecret encryption
+
+Provides encryption functionality with built-in validation, error handling,
+and user notifications.
+
+## Returns
+
+`object`
+
+Object with encrypt function and encrypting state
+
+### encrypt()
+
+> **encrypt**: (`request`) => [`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`EncryptionResult`](../interfaces/EncryptionResult.md), `string`\>
+
+#### Parameters
+
+##### request
+
+[`EncryptionRequest`](../interfaces/EncryptionRequest.md)
+
+#### Returns
+
+[`AsyncResult`](../../../types/type-aliases/AsyncResult.md)\<[`EncryptionResult`](../interfaces/EncryptionResult.md), `string`\>
+
+### encrypting
+
+> **encrypting**: `boolean`
+
+## Example
+
+```ts
+const { encrypt, encrypting } = useSealedSecretEncryption();
+
+const result = await encrypt({
+  name: 'my-secret',
+  namespace: 'default',
+  scope: 'strict',
+  keyValues: [{ key: 'password', value: 'secret123' }]
+});
+
+if (result.ok) {
+  // Use result.value.sealedSecretData
+}
+```
@@ -0,0 +1,59 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/useSealedSecretEncryption](../README.md) / EncryptionRequest
+
+# Interface: EncryptionRequest
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:30](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L30)
+
+Request parameters for encryption
+
+## Properties
+
+### name
+
+> **name**: `string`
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:32](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L32)
+
+Name of the SealedSecret to create
+
+***
+
+### namespace
+
+> **namespace**: `string`
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:34](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L34)
+
+Namespace to create the SealedSecret in
+
+***
+
+### scope
+
+> **scope**: [`SealedSecretScope`](../../../types/type-aliases/SealedSecretScope.md)
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:36](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L36)
+
+Encryption scope (strict, namespace-wide, cluster-wide)
+
+***
+
+### keyValues
+
+> **keyValues**: `object`[]
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:38](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L38)
+
+Key-value pairs to encrypt
+
+#### key
+
+> **key**: `string`
+
+#### value
+
+> **value**: `string`
@@ -0,0 +1,31 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [hooks/useSealedSecretEncryption](../README.md) / EncryptionResult
+
+# Interface: EncryptionResult
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:44](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L44)
+
+Result of successful encryption
+
+## Properties
+
+### sealedSecretData
+
+> **sealedSecretData**: `any`
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:46](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L46)
+
+The complete SealedSecret object ready to apply
+
+***
+
+### certificateInfo?
+
+> `optional` **certificateInfo**: [`CertificateInfo`](../../../types/interfaces/CertificateInfo.md)
+
+Defined in: [src/hooks/useSealedSecretEncryption.ts:48](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/hooks/useSealedSecretEncryption.ts#L48)
+
+Information about the certificate used