@valon-technologies/gestalt 0.0.1-alpha.1 → 0.0.1-alpha.11

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, "");