@valon-technologies/gestalt 0.0.1-alpha.8 → 0.0.1-alpha.9

package/src/invoker.ts

@@ -0,0 +1,124 @@
+import { connect } from "node:net";
+
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+import { createClient, type Client } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { PluginInvoker as PluginInvokerService } from "../gen/v1/plugin_pb.ts";
+import type { OperationResult, Request } from "./api.ts";
+
+export const ENV_PLUGIN_INVOKER_SOCKET = "GESTALT_PLUGIN_INVOKER_SOCKET";
+
+export interface PluginInvokeOptions {
+  connection?: string;
+  instance?: string;
+}
+
+export interface PluginInvocationGrant {
+  plugin: string;
+  operations: string[];
+}
+
+export class PluginInvoker {
+  private readonly client: Client<typeof PluginInvokerService>;
+  private readonly invocationToken: string;
+
+  constructor(request: Request);
+  constructor(invocationToken: string);
+  constructor(requestOrToken: Request | string) {
+    this.invocationToken = normalizeInvocationToken(requestOrToken);
+
+    const socketPath = process.env[ENV_PLUGIN_INVOKER_SOCKET];
+    if (!socketPath) {
+      throw new Error(`plugin invoker: ${ENV_PLUGIN_INVOKER_SOCKET} is not set`);
+    }
+
+    const transport = createGrpcTransport({
+      baseUrl: "http://localhost",
+      nodeOptions: {
+        createConnection: () => connect(socketPath),
+      },
+    });
+    this.client = createClient(PluginInvokerService, transport);
+  }
+
+  async invoke(
+    plugin: string,
+    operation: string,
+    params: Record<string, unknown> = {},
+    options?: PluginInvokeOptions,
+  ): Promise<OperationResult> {
+    const response = await this.client.invoke({
+      invocationToken: this.invocationToken,
+      plugin,
+      operation,
+      params: toJsonObject(params),
+      connection: options?.connection ?? "",
+      instance: options?.instance ?? "",
+    });
+    return {
+      status: response.status,
+      body: response.body,
+    };
+  }
+
+  async exchangeInvocationToken(options?: {
+    grants?: PluginInvocationGrant[];
+    ttlSeconds?: number;
+  }): Promise<string> {
+    const response = await this.client.exchangeInvocationToken({
+      parentInvocationToken: this.invocationToken,
+      grants: (options?.grants ?? [])
+        .map((grant) => ({
+          plugin: grant.plugin.trim(),
+          operations: grant.operations
+            .map((operation) => operation.trim())
+            .filter(Boolean),
+        }))
+        .filter((grant) => grant.plugin.length > 0),
+      ttlSeconds: BigInt(Math.max(0, options?.ttlSeconds ?? 0)),
+    });
+    return response.invocationToken;
+  }
+}
+
+function normalizeInvocationToken(requestOrToken: Request | string): string {
+  const invocationToken =
+    typeof requestOrToken === "string"
+      ? requestOrToken
+      : requestOrToken.invocationToken;
+  const trimmed = invocationToken.trim();
+  if (!trimmed) {
+    throw new Error("plugin invoker: invocation token is not available");
+  }
+  return trimmed;
+}
+
+function toJsonObject(params: Record<string, unknown>): JsonObject {
+  const output: JsonObject = {};
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value === undefined) {
+      continue;
+    }
+    output[key] = toJsonValue(value);
+  }
+  return output;
+}
+
+function toJsonValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => toJsonValue(entry));
+  }
+  if (typeof value === "object") {
+    return toJsonObject(value as Record<string, unknown>);
+  }
+  throw new Error("plugin invoker: params must be JSON-serializable");
+}

package/src/plugin.ts

@@ -18,13 +18,18 @@ import {
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { Schema } from "./schema.ts";
 
+/**
+ * How a plugin provider expects to authenticate or connect.
+ */
 export type ConnectionMode =
   | "unspecified"
   | "none"
   | "user"
-  | "identity"
-  | "either";
+  | "identity";
 
+/**
+ * Metadata for a single connection parameter exposed by a provider.
+ */
 export interface ConnectionParamDefinition {
   required?: boolean;
   description?: string;
@@ -33,6 +38,9 @@ export interface ConnectionParamDefinition {
   field?: string;
 }
 
+/**
+ * Operation definition accepted by {@link operation} and {@link definePlugin}.
+ */
 export interface OperationOptions<In, Out> {
   id: string;
   method?: string;
@@ -47,16 +55,29 @@ export interface OperationOptions<In, Out> {
   handler: (input: In, request: Request) => MaybePromise<Out | Response<Out>>;
 }
 
+/**
+ * Normalized plugin operation definition.
+ */
 export interface OperationDefinition<In, Out> extends OperationOptions<
   In,
   Out
 > {}
 
+/**
+ * Session-specific catalog payload returned by a provider at runtime.
+ */
 export type SessionCatalog = Catalog | Record<string, unknown>;
+
+/**
+ * Callback used to resolve a catalog for an authenticated request context.
+ */
 export type SessionCatalogHandler = (
   request: Request,
 ) => MaybePromise<SessionCatalog | null | undefined>;
 
+/**
+ * Runtime hooks required to implement a plugin provider.
+ */
 export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   connectionMode?: ConnectionMode;
   authTypes?: string[];
@@ -66,8 +87,9 @@ export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   sessionCatalog?: SessionCatalogHandler;
 }
 
-export type IntegrationProviderOptions = PluginDefinitionOptions;
-
+/**
+ * Normalizes a plugin operation definition.
+ */
 export function operation<In, Out>(
   options: OperationOptions<In, Out>,
 ): OperationDefinition<In, Out> {
@@ -82,7 +104,31 @@ export function operation<In, Out>(
   };
 }
 
-export class IntegrationProvider extends RuntimeProvider {
+/**
+ * Plugin provider implementation consumed by the Gestalt runtime.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin, ok, operation, s } from "@valon-technologies/gestalt";
+ *
+ * export const plugin = definePlugin({
+ *   displayName: "Example Provider",
+ *   operations: [
+ *     operation({
+ *       id: "ping",
+ *       method: "GET",
+ *       readOnly: true,
+ *       input: s.object({ name: s.string({ default: "World" }) }),
+ *       output: s.object({ message: s.string() }),
+ *       async handler(input) {
+ *         return ok({ message: `Hello, ${input.name}` });
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class PluginProvider extends RuntimeProvider {
   readonly kind = "integration" as const;
   readonly iconSvg: string;
   readonly connectionMode: ConnectionMode;
@@ -90,10 +136,7 @@ export class IntegrationProvider extends RuntimeProvider {
   readonly connectionParams: Record<string, ConnectionParamDefinition>;
 
   private readonly sessionCatalogHandler: SessionCatalogHandler | undefined;
-  private readonly operations = new Map<
-    string,
-    OperationDefinition<any, any>
-  >();
+  private readonly operations = new Map<string, OperationDefinition<any, any>>();
 
   constructor(options: PluginDefinitionOptions) {
     super(options);
@@ -103,36 +146,37 @@ export class IntegrationProvider extends RuntimeProvider {
     this.connectionParams = normalizeConnectionParams(options.connectionParams);
     this.sessionCatalogHandler = options.sessionCatalog;
 
-    for (const entry of options.operations) {
-      const id = entry.id.trim();
-      if (!id) {
+    for (const rawEntry of options.operations) {
+      const entry = operation(rawEntry);
+      if (!entry.id) {
         throw new Error("operation id is required");
       }
-      if (this.operations.has(id)) {
-        throw new Error(`duplicate operation id ${JSON.stringify(id)}`);
+      if (this.operations.has(entry.id)) {
+        throw new Error(`duplicate operation id ${JSON.stringify(entry.id)}`);
       }
-      this.operations.set(id, {
-        ...entry,
-        id,
-        method: normalizeMethod(entry.method),
-        title: entry.title?.trim() ?? "",
-        description: entry.description?.trim() ?? "",
-        allowedRoles: normalizeAllowedRoles(entry.allowedRoles),
-        tags: [...(entry.tags ?? [])],
-      });
+      this.operations.set(entry.id, entry);
     }
   }
 
+  /**
+   * Reports whether the provider exposes a session-specific catalog.
+   */
   supportsSessionCatalog(): boolean {
     return this.sessionCatalogHandler !== undefined;
   }
 
+  /**
+   * Resolves a catalog for the current request context, if configured.
+   */
   async catalogForRequest(
     request: Request,
   ): Promise<SessionCatalog | null | undefined> {
     return await this.sessionCatalogHandler?.(request);
   }
 
+  /**
+   * Returns the static catalog emitted during provider startup.
+   */
   staticCatalog(): Catalog {
     const catalog: Catalog = {
       operations: [...this.operations.values()].map<CatalogOperation>(
@@ -197,14 +241,23 @@ export class IntegrationProvider extends RuntimeProvider {
     return catalog;
   }
 
+  /**
+   * Writes the provider's static catalog to disk as YAML.
+   */
   writeCatalog(path: string): void {
     writeCatalogYaml(path, this.staticCatalog());
   }
 
+  /**
+   * Returns the static catalog serialized as JSON.
+   */
   catalogJson(): string {
     return catalogToJson(this.staticCatalog());
   }
 
+  /**
+   * Executes an operation against validated input and request metadata.
+   */
   async execute(
     operationId: string,
     params: Record<string, unknown>,
@@ -244,25 +297,23 @@ export class IntegrationProvider extends RuntimeProvider {
   }
 }
 
-export const Plugin = IntegrationProvider;
-
-export function defineIntegrationProvider(
-  options: PluginDefinitionOptions,
-): IntegrationProvider {
-  return new IntegrationProvider(options);
-}
-
+/**
+ * Creates a plugin provider.
+ */
 export function definePlugin(
   options: PluginDefinitionOptions,
-): IntegrationProvider {
-  return new IntegrationProvider(options);
+): PluginProvider {
+  return new PluginProvider(options);
 }
 
-export function isIntegrationProvider(
+/**
+ * Runtime type guard for plugin providers loaded from user modules.
+ */
+export function isPluginProvider(
   value: unknown,
-): value is IntegrationProvider {
+): value is PluginProvider {
   return (
-    value instanceof IntegrationProvider ||
+    value instanceof PluginProvider ||
     (typeof value === "object" &&
       value !== null &&
       "kind" in value &&
@@ -353,6 +404,9 @@ function errorResult(status: number, message: string): OperationResult {
   };
 }
 
+/**
+ * Converts a connection mode into the shared protocol enum value.
+ */
 export function connectionModeToProtoValue(mode: ConnectionMode): number {
   switch (mode) {
     case "none":
@@ -361,14 +415,15 @@ export function connectionModeToProtoValue(mode: ConnectionMode): number {
       return 2;
     case "identity":
       return 3;
-    case "either":
-      return 4;
     case "unspecified":
     default:
       return 0;
   }
 }
 
+/**
+ * Converts a connection parameter definition into protocol wire metadata.
+ */
 export function connectionParamToProto(value: ConnectionParamDefinition): {
   required?: boolean;
   description?: string;

package/src/provider-kind.ts

@@ -0,0 +1,107 @@
+import type { ProviderKind } from "./provider.ts";
+
+type ProviderKindDefinition = {
+  readonly tokens: readonly string[];
+  readonly formatToken: string;
+  readonly defaultExportNames: readonly string[];
+  readonly label: string;
+};
+
+const PROVIDER_KIND_DEFINITIONS = {
+  integration: {
+    tokens: ["plugin"],
+    formatToken: "plugin",
+    defaultExportNames: ["provider", "plugin"],
+    label: "plugin provider",
+  },
+  authentication: {
+    tokens: ["authentication"],
+    formatToken: "authentication",
+    defaultExportNames: ["authentication", "provider"],
+    label: "authentication provider",
+  },
+  cache: {
+    tokens: ["cache"],
+    formatToken: "cache",
+    defaultExportNames: ["cache", "provider"],
+    label: "cache provider",
+  },
+  secrets: {
+    tokens: ["secrets"],
+    formatToken: "secrets",
+    defaultExportNames: ["secrets", "provider"],
+    label: "secrets provider",
+  },
+  s3: {
+    tokens: ["s3"],
+    formatToken: "s3",
+    defaultExportNames: ["s3", "provider"],
+    label: "s3 provider",
+  },
+  workflow: {
+    tokens: ["workflow"],
+    formatToken: "workflow",
+    defaultExportNames: ["workflow", "provider"],
+    label: "workflow provider",
+  },
+  telemetry: {
+    tokens: ["telemetry"],
+    formatToken: "telemetry",
+    defaultExportNames: ["telemetry", "provider"],
+    label: "telemetry provider",
+  },
+} satisfies Record<ProviderKind, ProviderKindDefinition>;
+
+const EXTERNAL_PROVIDER_KIND_TOKEN_SET = new Set<string>(
+  Object.values(PROVIDER_KIND_DEFINITIONS).flatMap(
+    (definition) => definition.tokens,
+  ),
+);
+
+const EXTERNAL_PROVIDER_KIND_MAP = new Map<string, ProviderKind>(
+  Object.entries(PROVIDER_KIND_DEFINITIONS).flatMap(([kind, definition]) =>
+    definition.tokens.map(
+      (token) => [token, kind as ProviderKind] as const,
+    ),
+  ),
+);
+
+export function isExternalProviderKindToken(value: string): boolean {
+  return EXTERNAL_PROVIDER_KIND_TOKEN_SET.has(value.trim().toLowerCase());
+}
+
+export function parseExternalProviderKind(value: string): ProviderKind {
+  const normalized = value.trim().toLowerCase();
+  const kind = EXTERNAL_PROVIDER_KIND_MAP.get(normalized);
+  if (!kind) {
+    throw new Error(`unsupported provider kind ${JSON.stringify(value)}`);
+  }
+  return kind;
+}
+
+export function formatExternalProviderKind(kind: ProviderKind): string {
+  return PROVIDER_KIND_DEFINITIONS[kind].formatToken;
+}
+
+export function providerKindLabel(kind: ProviderKind): string {
+  return PROVIDER_KIND_DEFINITIONS[kind].label;
+}
+
+export function defaultProviderExportNames(
+  kind: ProviderKind,
+): readonly string[] {
+  return PROVIDER_KIND_DEFINITIONS[kind].defaultExportNames;
+}
+
+export function resolveDefaultProviderExport(
+  module: Record<string, unknown>,
+  kind: ProviderKind,
+): unknown {
+  for (const exportName of defaultProviderExportNames(kind)) {
+    const candidate = Reflect.get(module, exportName);
+    if (candidate !== undefined && candidate !== null) {
+      return candidate;
+    }
+  }
+  return Reflect.get(module, "default");
+}

package/src/provider.ts

@@ -1,13 +1,20 @@
 import type { MaybePromise } from "./api.ts";
 
+/**
+ * Provider kinds supported by the TypeScript SDK runtime.
+ */
 export type ProviderKind =
   | "integration"
-  | "auth"
+  | "authentication"
   | "cache"
   | "secrets"
   | "s3"
+  | "workflow"
   | "telemetry";
 
+/**
+ * Runtime metadata reported to the Gestalt host during startup.
+ */
 export type ProviderMetadata = {
   kind?: ProviderKind;
   name?: string;
@@ -16,17 +23,32 @@ export type ProviderMetadata = {
   version?: string;
 };
 
+/**
+ * Optional configuration hook invoked after the host starts the provider.
+ */
 export type ConfigureHandler = (
   name: string,
   config: Record<string, unknown>,
 ) => MaybePromise<void>;
 
+/**
+ * Optional readiness probe invoked by the Gestalt host.
+ */
 export type HealthCheckHandler = () => MaybePromise<void>;
 
+/**
+ * Optional callback that returns non-fatal runtime warnings.
+ */
 export type WarningsHandler = () => MaybePromise<string[]>;
 
+/**
+ * Optional shutdown hook invoked when the provider process exits.
+ */
 export type CloseHandler = () => MaybePromise<void>;
 
+/**
+ * Shared runtime metadata and lifecycle hooks for authored providers.
+ */
 export interface RuntimeProviderOptions {
   name?: string;
   displayName?: string;
@@ -38,6 +60,9 @@ export interface RuntimeProviderOptions {
   close?: CloseHandler;
 }
 
+/**
+ * Base class shared by all TypeScript SDK provider implementations.
+ */
 export abstract class RuntimeProvider {
   abstract readonly kind: ProviderKind;
 
@@ -116,6 +141,9 @@ export abstract class RuntimeProvider {
   }
 }
 
+/**
+ * Runtime type guard for values that implement the provider base contract.
+ */
 export function isRuntimeProvider(value: unknown): value is RuntimeProvider {
   return (
     value instanceof RuntimeProvider ||
@@ -127,6 +155,9 @@ export function isRuntimeProvider(value: unknown): value is RuntimeProvider {
   );
 }
 
+/**
+ * Normalizes package and provider names into Gestalt's slug format.
+ */
 export function slugName(value: string): string {
   const normalized = value.trim().replace(/^@[^/]+\//, "");
   return normalized.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");