diff --git a/docs/docs/api/appkit/Interface.CacheConfig.md b/docs/docs/api/appkit/Interface.CacheConfig.md index e1a62e23..52e9ad95 100644 --- a/docs/docs/api/appkit/Interface.CacheConfig.md +++ b/docs/docs/api/appkit/Interface.CacheConfig.md @@ -1,6 +1,6 @@ # Interface: CacheConfig -Configuration for caching +Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. ## Indexable diff --git a/docs/docs/api/appkit/Interface.StreamExecutionSettings.md b/docs/docs/api/appkit/Interface.StreamExecutionSettings.md index dedcdd0d..1ad88793 100644 --- a/docs/docs/api/appkit/Interface.StreamExecutionSettings.md +++ b/docs/docs/api/appkit/Interface.StreamExecutionSettings.md @@ -1,6 +1,6 @@ # Interface: StreamExecutionSettings -Configuration for streaming execution with default and user-scoped settings +Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. ## Properties diff --git a/docs/docs/api/appkit/TypeAlias.PluginData.md b/docs/docs/api/appkit/TypeAlias.PluginData.md index 9dadfd09..7efbc34c 100644 --- a/docs/docs/api/appkit/TypeAlias.PluginData.md +++ b/docs/docs/api/appkit/TypeAlias.PluginData.md @@ -8,6 +8,8 @@ type PluginData = { }; ``` +Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. + ## Type Parameters | Type Parameter | diff --git a/docs/docs/api/appkit/TypeAlias.ToPlugin.md b/docs/docs/api/appkit/TypeAlias.ToPlugin.md index 4217499d..f7cd3906 100644 --- a/docs/docs/api/appkit/TypeAlias.ToPlugin.md +++ b/docs/docs/api/appkit/TypeAlias.ToPlugin.md @@ -4,6 +4,8 @@ type ToPlugin = (config?: U) => PluginData; ``` +Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. + ## Type Parameters | Type Parameter | diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md index 20e6af2d..b5fb7ce0 100644 --- a/docs/docs/api/appkit/index.md +++ b/docs/docs/api/appkit/index.md @@ -31,7 +31,7 @@ plugin architecture, and React integration. | Interface | Description | | ------ | ------ | | [BasePluginConfig](Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins | -| [CacheConfig](Interface.CacheConfig.md) | Configuration for caching | +| [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. | | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection | | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials | | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. | @@ -42,7 +42,7 @@ plugin architecture, and React integration. | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. | | [ResourceFieldEntry](Interface.ResourceFieldEntry.md) | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key). | | [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union. | -| [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Configuration for streaming execution with default and user-scoped settings | +| [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. | | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications | | [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. | @@ -52,9 +52,9 @@ plugin architecture, and React integration. | ------ | ------ | | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. | | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration | -| [PluginData](TypeAlias.PluginData.md) | - | +| [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. | | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. | -| [ToPlugin](TypeAlias.ToPlugin.md) | - | +| [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. | ## Variables diff --git a/packages/appkit/src/telemetry/config.ts b/packages/appkit/src/telemetry/config.ts index 894ffe7a..38a002f9 100644 --- a/packages/appkit/src/telemetry/config.ts +++ b/packages/appkit/src/telemetry/config.ts @@ -6,6 +6,7 @@ export interface TelemetryProviderConfig { logs: boolean; } +/** Converts a TelemetryOptions value (boolean, object, or undefined) into a fully resolved config with explicit traces/metrics/logs flags. Defaults to all enabled. */ export function normalizeTelemetryOptions( config?: TelemetryOptions, ): TelemetryProviderConfig { diff --git a/packages/shared/src/cache.ts b/packages/shared/src/cache.ts index 485b568b..5506acdd 100644 --- a/packages/shared/src/cache.ts +++ b/packages/shared/src/cache.ts @@ -32,7 +32,7 @@ export interface CacheStorage { close(): Promise; } -/** Configuration for caching */ +/** Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. */ export interface CacheConfig { /** Whether caching is enabled */ enabled?: boolean; diff --git a/packages/shared/src/execute.ts b/packages/shared/src/execute.ts index 85718aa9..9221ea2f 100644 --- a/packages/shared/src/execute.ts +++ b/packages/shared/src/execute.ts @@ -1,5 +1,6 @@ import type { CacheConfig } from "./cache"; +/** SSE stream configuration for `executeStream()`. Controls buffer sizes, heartbeat interval, and cleanup behavior. */ export interface StreamConfig { userSignal?: AbortSignal; streamId?: string; @@ -12,6 +13,7 @@ export interface StreamConfig { maxActiveStreams?: number; } +/** Retry configuration for the RetryInterceptor. Uses exponential backoff between attempts. */ export interface RetryConfig { enabled?: boolean; attempts?: number; @@ -19,12 +21,14 @@ export interface RetryConfig { maxDelay?: number; } +/** Telemetry configuration for the TelemetryInterceptor. Controls span creation and custom attributes. */ export interface TelemetryConfig { enabled?: boolean; spanName?: string; attributes?: Record; } +/** Options passed to `Plugin.execute()` and `Plugin.executeStream()` to configure the interceptor chain (cache, retry, telemetry, timeout). */ export interface PluginExecuteConfig { cache?: CacheConfig; retry?: RetryConfig; @@ -35,17 +39,18 @@ export interface PluginExecuteConfig { [key: string]: unknown; } +/** Default and user-scoped execution settings for a plugin. The `user` config, when present, overrides `default` for on-behalf-of requests. */ export interface PluginExecutionSettings { default: PluginExecuteConfig; user?: PluginExecuteConfig; } -// stream execute handler can be a promise or a generator +/** Handler function for `executeStream()`. Can return a Promise (single result) or an AsyncGenerator (chunked streaming). */ export type StreamExecuteHandler = | ((signal?: AbortSignal) => Promise) | ((signal?: AbortSignal) => AsyncGenerator); -/** Configuration for streaming execution with default and user-scoped settings */ +/** Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. */ export interface StreamExecutionSettings { default: PluginExecuteConfig; user?: PluginExecuteConfig; diff --git a/packages/shared/src/plugin.ts b/packages/shared/src/plugin.ts index 0020f616..761bdce6 100644 --- a/packages/shared/src/plugin.ts +++ b/packages/shared/src/plugin.ts @@ -186,7 +186,9 @@ export type PluginMap< >; }; +/** Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. */ export type PluginData = { plugin: T; config: U; name: N }; +/** Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. */ export type ToPlugin = ( config?: U, ) => PluginData;