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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.8",
+  "version": "0.0.1-alpha.9",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {
@@ -29,6 +29,10 @@
   },
   "scripts": {
     "build:proto": "buf generate --template ../proto/buf.typescript.gen.yaml ../proto",
+    "docs:lint": "eslint --max-warnings=0 \"src/**/*.ts\" \"docs/entrypoints/**/*.ts\"",
+    "docs:build": "typedoc --options typedoc.json --out docs/_build/html",
+    "docs:build:deploy": "typedoc --options typedoc.json --out ../../docs/public/api/typescript",
+    "docs:check": "bun run docs:lint && bun run docs:build",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "check": "bun test && tsc --noEmit"
@@ -40,7 +44,11 @@
     "yaml": "2.8.1"
   },
   "devDependencies": {
+    "@typescript-eslint/parser": "8.46.1",
     "@types/bun": "1.3.2",
+    "eslint": "9.38.0",
+    "eslint-plugin-tsdoc": "0.4.0",
+    "typedoc": "0.28.14",
     "typescript": "5.9.3"
   },
   "peerDependencies": {

package/src/api.ts

@@ -1,3 +1,6 @@
+/**
+ * Common request and response types shared across authored Gestalt providers.
+ */
 export interface Subject {
   id: string;
   kind: string;
@@ -5,6 +8,9 @@ export interface Subject {
   authSource: string;
 }
 
+/**
+ * Describes the credential Gestalt used to authorize the current request.
+ */
 export interface Credential {
   mode: string;
   subjectId: string;
@@ -12,34 +18,59 @@ export interface Credential {
   instance: string;
 }
 
+/**
+ * Describes the access policy and effective role for the current request.
+ */
 export interface Access {
   policy: string;
   role: string;
 }
 
+/**
+ * Request metadata forwarded to provider handlers by the Gestalt runtime.
+ */
 export interface Request {
   token: string;
   connectionParams: Record<string, string>;
   subject: Subject;
   credential: Credential;
   access: Access;
+  // Workflow callback metadata uses a JSON-style lowerCamelCase object such as
+  // runId, target.pluginName, trigger.scheduleId, and trigger.event.specVersion.
+  workflow: Record<string, unknown>;
+  invocationToken: string;
 }
 
+/**
+ * Internal discriminator used by {@link response} and {@link ok}.
+ */
 export const responseBrand: unique symbol = Symbol("gestalt.response");
 
+/**
+ * Explicit handler response with an optional HTTP status override.
+ */
 export interface Response<T> {
   readonly [responseBrand]: true;
   status?: number;
   body: T;
 }
 
+/**
+ * Serialized operation result returned by the protocol runtime.
+ */
 export interface OperationResult {
   status: number;
   body: string;
 }
 
+/**
+ * Value or promise-like return accepted by provider handlers.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Wraps a handler result with an explicit status code.
+ */
 export function response<T>(status: number, body: T): Response<T> {
   return {
     [responseBrand]: true,
@@ -48,16 +79,31 @@ export function response<T>(status: number, body: T): Response<T> {
   };
 }
 
+/**
+ * Wraps a handler result with the default `200` status code.
+ */
 export function ok<T>(body: T): Response<T> {
   return response(200, body);
 }
 
+/**
+ * Creates a request object for local testing or direct provider invocation.
+ *
+ * @example
+ * ```ts
+ * import { request } from "@valon-technologies/gestalt";
+ *
+ * const input = request("token", { region: "us-east-1" }, { id: "usr_123" });
+ * ```
+ */
 export function request(
   token = "",
   connectionParams: Record<string, string> = {},
   subject: Partial<Subject> = {},
   credential: Partial<Credential> = {},
   access: Partial<Access> = {},
+  workflow: Record<string, unknown> = {},
+  invocationToken = "",
 ): Request {
   return {
     token,
@@ -80,9 +126,16 @@ export function request(
       policy: access.policy ?? "",
       role: access.role ?? "",
     },
+    workflow: {
+      ...workflow,
+    },
+    invocationToken,
   };
 }
 
+/**
+ * Looks up a single connection parameter from a request.
+ */
 export function connectionParam(
   input: Request | undefined,
   name: string,
@@ -90,6 +143,9 @@ export function connectionParam(
   return input?.connectionParams[name];
 }
 
+/**
+ * Normalizes unknown thrown values into a readable error message.
+ */
 export function errorMessage(error: unknown): string {
   if (error instanceof Error && error.message) {
     return error.message;

package/src/auth.ts

@@ -1,6 +1,10 @@
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { MaybePromise } from "./api.ts";
 
+/**
+ * Identity payload returned by an authentication provider after a successful
+ * login.
+ */
 export interface AuthenticatedUser {
   subject: string;
   email?: string;
@@ -10,6 +14,9 @@ export interface AuthenticatedUser {
   claims?: Record<string, string>;
 }
 
+/**
+ * Input passed to an authentication provider's `beginLogin` handler.
+ */
 export interface BeginLoginRequest {
   callbackUrl: string;
   hostState: string;
@@ -17,22 +24,35 @@ export interface BeginLoginRequest {
   options: Record<string, string>;
 }
 
+/**
+ * Response returned by an authentication provider's `beginLogin` handler.
+ */
 export interface BeginLoginResponse {
   authorizationUrl: string;
   providerState?: Uint8Array;
 }
 
+/**
+ * Callback payload passed to an authentication provider's `completeLogin`
+ * handler.
+ */
 export interface CompleteLoginRequest {
   query: Record<string, string>;
   providerState: Uint8Array;
   callbackUrl: string;
 }
 
-export interface AuthSessionSettings {
+/**
+ * Session TTL hints exposed by an authentication provider.
+ */
+export interface AuthenticationSessionSettings {
   sessionTtlSeconds: number | bigint;
 }
 
-export interface AuthProviderOptions extends RuntimeProviderOptions {
+/**
+ * Runtime hooks required to implement a Gestalt authentication provider.
+ */
+export interface AuthenticationProviderOptions extends RuntimeProviderOptions {
   beginLogin: (
     request: BeginLoginRequest,
   ) => MaybePromise<BeginLoginResponse>;
@@ -42,18 +62,21 @@ export interface AuthProviderOptions extends RuntimeProviderOptions {
   validateExternalToken?: (
     token: string,
   ) => MaybePromise<AuthenticatedUser | null | undefined>;
-  sessionSettings?: () => MaybePromise<AuthSessionSettings>;
+  sessionSettings?: () => MaybePromise<AuthenticationSessionSettings>;
 }
 
-export class AuthProvider extends RuntimeProvider {
-  readonly kind = "auth" as const;
+/**
+ * Authentication provider implementation consumed by the Gestalt runtime.
+ */
+export class AuthenticationProvider extends RuntimeProvider {
+  readonly kind = "authentication" as const;
 
-  private readonly beginLoginHandler: AuthProviderOptions["beginLogin"];
-  private readonly completeLoginHandler: AuthProviderOptions["completeLogin"];
-  private readonly validateExternalTokenHandler: AuthProviderOptions["validateExternalToken"];
-  private readonly sessionSettingsHandler: AuthProviderOptions["sessionSettings"];
+  private readonly beginLoginHandler: AuthenticationProviderOptions["beginLogin"];
+  private readonly completeLoginHandler: AuthenticationProviderOptions["completeLogin"];
+  private readonly validateExternalTokenHandler: AuthenticationProviderOptions["validateExternalToken"];
+  private readonly sessionSettingsHandler: AuthenticationProviderOptions["sessionSettings"];
 
-  constructor(options: AuthProviderOptions) {
+  constructor(options: AuthenticationProviderOptions) {
     super(options);
     this.beginLoginHandler = options.beginLogin;
     this.completeLoginHandler = options.completeLogin;
@@ -81,22 +104,50 @@ export class AuthProvider extends RuntimeProvider {
     return this.sessionSettingsHandler !== undefined;
   }
 
-  async sessionSettings(): Promise<AuthSessionSettings | undefined> {
+  async sessionSettings(): Promise<AuthenticationSessionSettings | undefined> {
     return await this.sessionSettingsHandler?.();
   }
 }
 
-export function defineAuthProvider(options: AuthProviderOptions): AuthProvider {
-  return new AuthProvider(options);
+/**
+ * Creates an authentication provider with the standard Gestalt runtime
+ * contract.
+ *
+ * @example
+ * ```ts
+ * import { defineAuthenticationProvider } from "@valon-technologies/gestalt";
+ *
+ * export const authentication = defineAuthenticationProvider({
+ *   displayName: "Example Authentication",
+ *   async beginLogin(request) {
+ *     return {
+ *       authorizationUrl: new URL("/login", request.callbackUrl).toString(),
+ *     };
+ *   },
+ *   async completeLogin() {
+ *     return { subject: "usr_123", email: "user@example.com" };
+ *   },
+ * });
+ * ```
+ */
+export function defineAuthenticationProvider(
+  options: AuthenticationProviderOptions,
+): AuthenticationProvider {
+  return new AuthenticationProvider(options);
 }
 
-export function isAuthProvider(value: unknown): value is AuthProvider {
+/**
+ * Runtime type guard for authentication providers loaded from user modules.
+ */
+export function isAuthenticationProvider(
+  value: unknown,
+): value is AuthenticationProvider {
   return (
-    value instanceof AuthProvider ||
+    value instanceof AuthenticationProvider ||
     (typeof value === "object" &&
       value !== null &&
       "kind" in value &&
-      (value as { kind?: unknown }).kind === "auth" &&
+      String((value as { kind?: unknown }).kind ?? "") === "authentication" &&
       "beginLogin" in value &&
       "completeLogin" in value)
   );

package/src/build.ts

@@ -3,11 +3,18 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
+import { defaultProviderExportNames } from "./provider-kind.ts";
 import { parseProviderTarget, resolveProviderModulePath, type ProviderTarget } from "./target.ts";
 
+/**
+ * Command-line usage for the bundled build entrypoint.
+ */
 export const USAGE =
   "usage: bun run build.ts ROOT PROVIDER_TARGET OUTPUT PROVIDER_NAME GOOS GOARCH";
 
+/**
+ * Parsed arguments for the build entrypoint.
+ */
 export type BuildArgs = {
   root: string;
   target: string;
@@ -15,8 +22,12 @@ export type BuildArgs = {
   providerName: string;
   goos: string;
   goarch: string;
+  compileTarget?: string;
 };
 
+/**
+ * CLI entrypoint that compiles a provider into a standalone Bun executable.
+ */
 export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
   const args = parseBuildArgs(argv);
   if (!args) {
@@ -27,6 +38,9 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   return 0;
 }
 
+/**
+ * Parses `gestalt-ts-build` CLI arguments.
+ */
 export function parseBuildArgs(argv: string[]): BuildArgs | undefined {
   if (argv.length !== 6) {
     return undefined;
@@ -41,6 +55,9 @@ export function parseBuildArgs(argv: string[]): BuildArgs | undefined {
   };
 }
 
+/**
+ * Bundles a provider into a standalone executable for the requested target.
+ */
 export function buildProviderBinary(args: BuildArgs): void {
   const root = resolve(args.root);
   const outputPath = resolve(args.outputPath);
@@ -49,7 +66,13 @@ export function buildProviderBinary(args: BuildArgs): void {
 
   try {
     const wrapperPath = writeBundledWrapper(workDir, root, target, args.providerName);
-    const bunCommand = bunBuildCommand(wrapperPath, outputPath, args.goos, args.goarch);
+    const bunCommand = bunBuildCommand(
+      wrapperPath,
+      outputPath,
+      args.goos,
+      args.goarch,
+      args.compileTarget,
+    );
     const result = spawnSync(bunCommand.command, bunCommand.args, {
       cwd: root,
       stdio: "inherit",
@@ -65,13 +88,15 @@ export function buildProviderBinary(args: BuildArgs): void {
   }
 }
 
-export const buildPluginBinary = buildProviderBinary;
-
+/**
+ * Constructs the Bun command used to compile a provider binary.
+ */
 export function bunBuildCommand(
   wrapperPath: string,
   outputPath: string,
   goos: string,
   goarch: string,
+  compileTarget = bunTarget(goos, goarch),
 ): { command: string; args: string[] } {
   return {
     command: resolveBunExecutable(),
@@ -79,7 +104,7 @@ export function bunBuildCommand(
       "build",
       "--compile",
       "--target",
-      bunTarget(goos, goarch),
+      compileTarget,
       "--outfile",
       outputPath,
       wrapperPath,
@@ -87,6 +112,9 @@ export function bunBuildCommand(
   };
 }
 
+/**
+ * Maps a Go-style `GOOS` / `GOARCH` target into Bun's compile target format.
+ */
 export function bunTarget(goos: string, goarch: string): string {
   const key = `${goos}/${goarch}`;
   switch (key) {
@@ -95,9 +123,9 @@ export function bunTarget(goos: string, goarch: string): string {
     case "darwin/arm64":
       return "bun-darwin-arm64";
     case "linux/amd64":
-      return "bun-linux-x64";
+      return "bun-linux-x64-musl";
     case "linux/arm64":
-      return "bun-linux-arm64";
+      return "bun-linux-arm64-musl";
     case "windows/amd64":
       return "bun-windows-x64";
     case "windows/arm64":
@@ -133,21 +161,9 @@ await runBundledProvider(candidate, ${JSON.stringify(target.kind)}, ${JSON.strin
 }
 
 function defaultBundledCandidateExpression(kind: ProviderTarget["kind"]): string {
-  switch (kind) {
-    case "integration":
-      return "bundledModule.provider ?? bundledModule.plugin ?? bundledModule.default";
-    case "auth":
-      return "bundledModule.auth ?? bundledModule.provider ?? bundledModule.default";
-    case "cache":
-      return "bundledModule.cache ?? bundledModule.provider ?? bundledModule.default";
-    case "secrets":
-      return "bundledModule.secrets ?? bundledModule.provider ?? bundledModule.default";
-    case "s3":
-      return "bundledModule.s3 ?? bundledModule.provider ?? bundledModule.default";
-    case "telemetry":
-      return "bundledModule.telemetry ?? bundledModule.provider ?? bundledModule.default";
-  }
-  throw new Error(`unsupported provider kind: ${kind satisfies never}`);
+  return [...defaultProviderExportNames(kind), "default"]
+    .map((exportName) => `Reflect.get(bundledModule, ${JSON.stringify(exportName)})`)
+    .join(" ?? ");
 }
 
 function resolveBunExecutable(): string {

package/src/cache.ts

@@ -9,15 +9,24 @@ import type { MaybePromise } from "./api.ts";
 
 const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
 
+/**
+ * Single cache entry used by batch cache APIs.
+ */
 export interface CacheEntry {
   key: string;
   value: Uint8Array;
 }
 
+/**
+ * Optional TTL applied when setting cache values.
+ */
 export interface CacheSetOptions {
   ttlMs?: number;
 }
 
+/**
+ * Runtime hooks required to implement a Gestalt cache provider.
+ */
 export interface CacheProviderOptions extends RuntimeProviderOptions {
   get: (key: string) => MaybePromise<Uint8Array | null | undefined>;
   set: (
@@ -35,6 +44,9 @@ export interface CacheProviderOptions extends RuntimeProviderOptions {
   deleteMany?: (keys: string[]) => MaybePromise<number | bigint>;
 }
 
+/**
+ * Returns the environment variable name used to discover a cache socket.
+ */
 export function cacheSocketEnv(name?: string): string {
   const trimmed = name?.trim() ?? "";
   if (!trimmed) {
@@ -43,6 +55,17 @@ export function cacheSocketEnv(name?: string): string {
   return `${ENV_CACHE_SOCKET}_${trimmed.replace(/[^A-Za-z0-9]/gu, "_").toUpperCase()}`;
 }
 
+/**
+ * Client for invoking a host-provided cache over the Gestalt transport.
+ *
+ * @example
+ * ```ts
+ * import { Cache } from "@valon-technologies/gestalt";
+ *
+ * const cache = new Cache();
+ * await cache.set("session", new TextEncoder().encode("hello"));
+ * ```
+ */
 export class Cache {
   private readonly client: Client<typeof CacheService>;
 
@@ -127,6 +150,9 @@ export class Cache {
   }
 }
 
+/**
+ * Cache provider implementation consumed by the Gestalt runtime.
+ */
 export class CacheProvider extends RuntimeProvider {
   readonly kind = "cache" as const;
 
@@ -219,10 +245,16 @@ export class CacheProvider extends RuntimeProvider {
   }
 }
 
+/**
+ * Creates a cache provider from standard CRUD handlers.
+ */
 export function defineCacheProvider(options: CacheProviderOptions): CacheProvider {
   return new CacheProvider(options);
 }
 
+/**
+ * Runtime type guard for cache providers loaded from user modules.
+ */
 export function isCacheProvider(value: unknown): value is CacheProvider {
   return (
     value instanceof CacheProvider ||

package/src/catalog.ts

@@ -4,6 +4,9 @@ import YAML from "yaml";
 
 import type { Schema } from "./schema.ts";
 
+/**
+ * Query-style parameter metadata derived from a Gestalt schema.
+ */
 export interface CatalogParameter {
   name: string;
   type: string;
@@ -12,6 +15,9 @@ export interface CatalogParameter {
   default?: unknown;
 }
 
+/**
+ * JSON-schema-like description used in provider catalogs.
+ */
 export interface CatalogSchema {
   type: string;
   description?: string;
@@ -21,6 +27,9 @@ export interface CatalogSchema {
   items?: CatalogSchema;
 }
 
+/**
+ * Static operation metadata emitted by a provider catalog.
+ */
 export interface CatalogOperation {
   id: string;
   method: string;
@@ -35,6 +44,9 @@ export interface CatalogOperation {
   allowedRoles?: string[];
 }
 
+/**
+ * Static provider catalog emitted to the Gestalt host.
+ */
 export interface Catalog {
   name?: string;
   displayName?: string;
@@ -43,6 +55,9 @@ export interface Catalog {
   operations: CatalogOperation[];
 }
 
+/**
+ * Extracts top-level parameter metadata from an object schema.
+ */
 export function schemaToParameters(
   schema: Schema<unknown> | undefined,
 ): CatalogParameter[] {
@@ -67,6 +82,9 @@ export function schemaToParameters(
   });
 }
 
+/**
+ * Converts a runtime schema into catalog-friendly metadata.
+ */
 export function schemaToCatalogSchema(
   schema: Schema<unknown> | undefined,
 ): CatalogSchema | undefined {
@@ -102,6 +120,9 @@ export function schemaToCatalogSchema(
   return output;
 }
 
+/**
+ * Serializes a catalog to JSON for host consumption.
+ */
 export function catalogToJson(
   catalog: Catalog | Record<string, unknown> | null | undefined,
 ): string {
@@ -111,12 +132,18 @@ export function catalogToJson(
   return JSON.stringify(toCatalogJsonObject(catalog));
 }
 
+/**
+ * Serializes a catalog to YAML for release artifacts.
+ */
 export function catalogToYaml(
   catalog: Catalog | Record<string, unknown>,
 ): string {
   return YAML.stringify(toCatalogJsonObject(catalog));
 }
 
+/**
+ * Writes a catalog to disk as YAML.
+ */
 export function writeCatalogYaml(
   path: string,
   catalog: Catalog | Record<string, unknown>,