Gestalt TypeScript SDK

This package provides the TypeScript authoring surface for executable Gestalt providers.

It is intended for source providers discovered through package.json and for packaged providers built from that same source tree.

Provider target

Point the package at the provider module with a top-level gestalt.provider property in package.json:

{
  "name": "my-provider",
  "version": "0.0.1-alpha.1",
  "dependencies": {
    "@valon-technologies/gestalt": "0.0.1-alpha.13"
  },
  "gestalt": {
    "provider": {
      "kind": "plugin",
      "target": "./provider.ts#plugin"
    }
  }
}
Copy

The target is a relative file path with an optional export suffix. The runtime accepts:

• gestalt.provider as { "kind": "...", "target": "./file.ts#export" }
• gestalt.provider as a string like "plugin:./provider.ts#plugin" or "cache:./cache.ts#provider"

Use "plugin" as the kind token for executable plugin providers.

If the export suffix is omitted, the runtime looks for provider, then plugin, then the default export.

Authoring

Use explicit runtime schemas to define plugin operation inputs and outputs:

import {
  definePlugin,
  ok,
  operation,
  response,
  s,
} from "@valon-technologies/gestalt";

export const plugin = definePlugin({
  displayName: "Example Provider",
  description: "A provider implemented with the Gestalt TypeScript SDK",
  configure(name, config) {
    console.log("configured", name, config);
  },
  sessionCatalog(request) {
    return {
      name: "example-session",
      operations: [
        {
          id: "session-ping",
          method: "GET",
        },
      ],
    };
  },
  operations: [
    operation({
      id: "greet",
      method: "GET",
      readOnly: true,
      input: s.object({
        name: s.string({ description: "Name to greet", default: "World" }),
        excited: s.optional(s.boolean()),
      }),
      output: s.object({
        message: s.string(),
      }),
      async handler(input) {
        return ok({
          message: `Hello, ${input.name}${input.excited ? "!" : "."}`,
        });
      },
    }),
  ],
});
Copy

Use ok(body) for normal responses and response(status, body) when a handler needs to set a non-200 status. Plain objects with status and body fields are treated as user data.

Authentication providers, cache providers, and secrets providers use dedicated helpers:

import {
  Cache,
  defineAuthenticationProvider,
  defineCacheProvider,
  defineSecretsProvider,
} from "@valon-technologies/gestalt";
Copy

Runtime and build entrypoints

Source-mode runtime:

gestalt-ts-runtime ROOT plugin:./provider.ts#plugin
Copy

Release build:

gestalt-ts-build ROOT cache:./cache.ts#provider OUTPUT PROVIDER_NAME GOOS GOARCH
Copy

The build entrypoint compiles a standalone executable with Bun and bundles the provider source into the result.

Regenerating protobuf code

From the repo root:

buf generate --template sdk/proto/buf.typescript.gen.yaml sdk/proto
Copy

Local checks

From sdk/typescript:

export PATH="$HOME/.bun/bin:$PATH"
bun install
bun run build:proto
bun run check
Copy