refactor: streamline widget and integration architecture
This commit is contained in:
1 parent
ec295fe26e
commit
425cb653a1
243 files changed
+5722
-2255
No files matched your search
@@ -0,0 +1,139 @@
|
||||
import type { AtLeastOneOf } from "@homarr/common/types";
|
||||
|
||||
import type { IntegrationCategory, IntegrationKind } from "./integration";
|
||||
|
||||
export type WidgetModuleIconName = `Icon${string}`;
|
||||
export type WidgetModuleOperationKind = "query" | "mutation" | "subscription" | "route";
|
||||
|
||||
export interface WidgetModuleClientPolicy {
|
||||
refetchIntervalSeconds?: number | null;
|
||||
staleTimeSeconds?: number;
|
||||
persist?: boolean;
|
||||
}
|
||||
|
||||
export interface WidgetModuleServerCachePolicy {
|
||||
namespace: string;
|
||||
ttlMs: number;
|
||||
staleIfErrorTtlMs?: number;
|
||||
scope: "integration" | "shared" | "private";
|
||||
}
|
||||
|
||||
export interface WidgetModuleOperation {
|
||||
name: string;
|
||||
kind?: WidgetModuleOperationKind;
|
||||
path: readonly [string, ...string[]];
|
||||
client?: WidgetModuleClientPolicy;
|
||||
serverCache?: WidgetModuleServerCachePolicy;
|
||||
}
|
||||
|
||||
type WidgetModuleIntegrationSelection =
|
||||
| {
|
||||
categories: Readonly<AtLeastOneOf<IntegrationCategory>>;
|
||||
kinds?: readonly IntegrationKind[];
|
||||
}
|
||||
| {
|
||||
categories?: readonly IntegrationCategory[];
|
||||
kinds: Readonly<AtLeastOneOf<IntegrationKind>>;
|
||||
};
|
||||
|
||||
export type WidgetModuleIntegrationCapability = WidgetModuleIntegrationSelection & {
|
||||
excludeKinds?: readonly IntegrationKind[];
|
||||
connectionOptional?: true;
|
||||
serverMaxIntegrations?: number;
|
||||
};
|
||||
|
||||
export interface WidgetModuleRouterRegistration {
|
||||
namespace: string;
|
||||
module: string;
|
||||
exportName: string;
|
||||
additionalWidgetKinds?: readonly string[];
|
||||
mcp?: true | string;
|
||||
}
|
||||
|
||||
export interface WidgetModuleDocumentation {
|
||||
slug: string;
|
||||
sourceDirectory: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure authoring contract for a vertical widget module.
|
||||
*
|
||||
* This descriptor intentionally contains import paths instead of importing
|
||||
* client or server implementations. The sync tool turns them into explicit
|
||||
* static imports for Next.js and Turbopack without crossing runtime boundaries.
|
||||
*/
|
||||
export interface WidgetModuleDefinition {
|
||||
kind: string;
|
||||
icon: WidgetModuleIconName;
|
||||
clientEntry: string;
|
||||
documentation: WidgetModuleDocumentation;
|
||||
defaultSize?: Readonly<{ width: number; height: number }>;
|
||||
displayNameFromIntegration?: true;
|
||||
integration?: WidgetModuleIntegrationCapability;
|
||||
operations?: readonly WidgetModuleOperation[];
|
||||
routers?: readonly WidgetModuleRouterRegistration[];
|
||||
}
|
||||
|
||||
export const defineWidgetModule = <const TDefinition extends WidgetModuleDefinition>(definition: TDefinition) =>
|
||||
definition;
|
||||
|
||||
export type WidgetServerPermission =
|
||||
| "public"
|
||||
| "authenticated"
|
||||
| "integration-query"
|
||||
| "integration-interact"
|
||||
| "custom";
|
||||
|
||||
export interface WidgetServerInputSchema<TInput> {
|
||||
parseAsync: (input: unknown) => Promise<TInput>;
|
||||
}
|
||||
|
||||
export interface WidgetServerContext<TServices = unknown, TAuthorization = unknown> {
|
||||
services: TServices;
|
||||
authorization: TAuthorization;
|
||||
signal: AbortSignal;
|
||||
}
|
||||
|
||||
export interface WidgetServerOperationDefinition<TInput, TOutput, TContext = WidgetServerContext> {
|
||||
kind: "query" | "mutation";
|
||||
permission: WidgetServerPermission;
|
||||
input: WidgetServerInputSchema<TInput>;
|
||||
cache?: WidgetModuleServerCachePolicy;
|
||||
resolve: (context: TContext, input: TInput) => Promise<TOutput>;
|
||||
}
|
||||
|
||||
export interface WidgetServerSubscriptionDefinition<TInput, TOutput, TContext = WidgetServerContext> {
|
||||
kind: "subscription";
|
||||
permission: WidgetServerPermission;
|
||||
input: WidgetServerInputSchema<TInput>;
|
||||
transport: "sse" | "websocket";
|
||||
subscribe: (context: TContext, input: TInput) => AsyncIterable<TOutput>;
|
||||
}
|
||||
|
||||
export interface WidgetServerRouteDefinition<TRequest = unknown, TResponse = unknown, TContext = WidgetServerContext> {
|
||||
kind: "route";
|
||||
permission: WidgetServerPermission;
|
||||
handle: (context: TContext, request: TRequest) => Promise<TResponse>;
|
||||
}
|
||||
|
||||
export const defineWidgetServerOperation = <TInput, TOutput, TContext = WidgetServerContext>(
|
||||
operation: WidgetServerOperationDefinition<TInput, TOutput, TContext>,
|
||||
) => operation;
|
||||
|
||||
export const defineWidgetServerSubscription = <TInput, TOutput, TContext = WidgetServerContext>(
|
||||
subscription: WidgetServerSubscriptionDefinition<TInput, TOutput, TContext>,
|
||||
) => subscription;
|
||||
|
||||
export const defineWidgetServerRoute = <TRequest, TResponse, TContext = WidgetServerContext>(
|
||||
route: WidgetServerRouteDefinition<TRequest, TResponse, TContext>,
|
||||
) => route;
|
||||
|
||||
export const defineWidgetServerModule = <
|
||||
const TModule extends {
|
||||
operations?: Readonly<Record<string, object>>;
|
||||
subscriptions?: Readonly<Record<string, object>>;
|
||||
routes?: Readonly<Record<string, object>>;
|
||||
},
|
||||
>(
|
||||
module: TModule,
|
||||
) => module;
|
||||
Reference in new issue
Block a user