@valon-technologies/gestalt 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,160 @@
+# 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`:
+
+```json
+{
+  "name": "my-provider",
+  "version": "0.0.1-alpha.1",
+  "dependencies": {
+    "@valon-technologies/gestalt": "0.0.1-alpha.1"
+  },
+  "gestalt": {
+    "provider": {
+      "kind": "plugin",
+      "target": "./provider.ts#provider"
+    }
+  }
+}
+```
+
+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#provider"` or `"cache:./cache.ts#provider"`
+- legacy integration-only `gestalt.plugin`
+
+Use `"plugin"` as the kind token for executable integration providers. The
+older `"integration"` spelling is still accepted for compatibility.
+
+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:
+
+```ts
+import {
+  defineIntegrationProvider,
+  ok,
+  operation,
+  response,
+  s,
+} from "@valon-technologies/gestalt";
+
+export const provider = defineIntegrationProvider({
+  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 ? "!" : "."}`,
+        });
+      },
+    }),
+  ],
+});
+```
+
+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.
+
+Auth providers, cache providers, and secrets providers use dedicated helpers:
+
+```ts
+import {
+  Cache,
+  defineAuthProvider,
+  defineCacheProvider,
+  defineSecretsProvider,
+} from "@valon-technologies/gestalt";
+```
+
+## Runtime and build entrypoints
+
+Source-mode runtime:
+
+```sh
+gestalt-ts-runtime ROOT plugin:./provider.ts#provider
+```
+
+Release build:
+
+```sh
+gestalt-ts-build ROOT cache:./cache.ts#provider OUTPUT PROVIDER_NAME GOOS GOARCH
+```
+
+The build entrypoint compiles a standalone executable with Bun and bundles the
+provider source into the result.
+
+## Regenerating protobuf code
+
+From the repo root:
+
+```sh
+buf generate --template sdk/proto/buf.typescript.gen.yaml sdk/proto
+```
+
+## Local checks
+
+From `sdk/typescript`:
+
+```sh
+export PATH="$HOME/.bun/bin:$PATH"
+bun install
+bun run build:proto
+bun run check
+```
+
+## Publishing
+
+The SDK is published to npm as `@valon-technologies/gestalt`.
+
+Release tags stay aligned with the repo's SDK tag convention:
+
+- `sdk/typescript/v0.0.1`
+- `sdk/typescript/v0.0.1-alpha.1`
+- `sdk/typescript/v0.0.1-beta.1`
+- `sdk/typescript/v0.0.1-rc.1`
+
+The release workflow uses Bun for installation and validation, then publishes
+with npm Trusted Publishing from GitHub Actions. Stable releases use the
+default `latest` dist-tag; prereleases are published under `alpha`, `beta`, or
+`rc`.

package/gen/v1/auth_pb.ts

@@ -0,0 +1,212 @@
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts"
+// @generated from file v1/auth.proto (package gestalt.provider.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
+import type { EmptySchema } from "@bufbuild/protobuf/wkt";
+import { file_google_protobuf_empty } from "@bufbuild/protobuf/wkt";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file v1/auth.proto.
+ */
+export const file_v1_auth: GenFile = /*@__PURE__*/
+  fileDesc("Cg12MS9hdXRoLnByb3RvEhNnZXN0YWx0LnByb3ZpZGVyLnYxIugBChFBdXRoZW50aWNhdGVkVXNlchIPCgdzdWJqZWN0GAEgASgJEg0KBWVtYWlsGAIgASgJEhYKDmVtYWlsX3ZlcmlmaWVkGAMgASgIEhQKDGRpc3BsYXlfbmFtZRgEIAEoCRISCgphdmF0YXJfdXJsGAUgASgJEkIKBmNsYWltcxgGIAMoCzIyLmdlc3RhbHQucHJvdmlkZXIudjEuQXV0aGVudGljYXRlZFVzZXIuQ2xhaW1zRW50cnkaLQoLQ2xhaW1zRW50cnkSCwoDa2V5GAEgASgJEg0KBXZhbHVlGAIgASgJOgI4ASLDAQoRQmVnaW5Mb2dpblJlcXVlc3QSFAoMY2FsbGJhY2tfdXJsGAEgASgJEhIKCmhvc3Rfc3RhdGUYAiABKAkSDgoGc2NvcGVzGAMgAygJEkQKB29wdGlvbnMYBCADKAsyMy5nZXN0YWx0LnByb3ZpZGVyLnYxLkJlZ2luTG9naW5SZXF1ZXN0Lk9wdGlvbnNFbnRyeRouCgxPcHRpb25zRW50cnkSCwoDa2V5GAEgASgJEg0KBXZhbHVlGAIgASgJOgI4ASJHChJCZWdpbkxvZ2luUmVzcG9uc2USGQoRYXV0aG9yaXphdGlvbl91cmwYASABKAkSFgoOcHJvdmlkZXJfc3RhdGUYAiABKAwitwEKFENvbXBsZXRlTG9naW5SZXF1ZXN0EkMKBXF1ZXJ5GAEgAygLMjQuZ2VzdGFsdC5wcm92aWRlci52MS5Db21wbGV0ZUxvZ2luUmVxdWVzdC5RdWVyeUVudHJ5EhYKDnByb3ZpZGVyX3N0YXRlGAIgASgMEhQKDGNhbGxiYWNrX3VybBgDIAEoCRosCgpRdWVyeUVudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAEiLQocVmFsaWRhdGVFeHRlcm5hbFRva2VuUmVxdWVzdBINCgV0b2tlbhgBIAEoCSIyChNBdXRoU2Vzc2lvblNldHRpbmdzEhsKE3Nlc3Npb25fdHRsX3NlY29uZHMYASABKAMynQMKDEF1dGhQcm92aWRlchJdCgpCZWdpbkxvZ2luEiYuZ2VzdGFsdC5wcm92aWRlci52MS5CZWdpbkxvZ2luUmVxdWVzdBonLmdlc3RhbHQucHJvdmlkZXIudjEuQmVnaW5Mb2dpblJlc3BvbnNlEmIKDUNvbXBsZXRlTG9naW4SKS5nZXN0YWx0LnByb3ZpZGVyLnYxLkNvbXBsZXRlTG9naW5SZXF1ZXN0GiYuZ2VzdGFsdC5wcm92aWRlci52MS5BdXRoZW50aWNhdGVkVXNlchJyChVWYWxpZGF0ZUV4dGVybmFsVG9rZW4SMS5nZXN0YWx0LnByb3ZpZGVyLnYxLlZhbGlkYXRlRXh0ZXJuYWxUb2tlblJlcXVlc3QaJi5nZXN0YWx0LnByb3ZpZGVyLnYxLkF1dGhlbnRpY2F0ZWRVc2VyElYKEkdldFNlc3Npb25TZXR0aW5ncxIWLmdvb2dsZS5wcm90b2J1Zi5FbXB0eRooLmdlc3RhbHQucHJvdmlkZXIudjEuQXV0aFNlc3Npb25TZXR0aW5nc0I7WjlnaXRodWIuY29tL3ZhbG9uLXRlY2hub2xvZ2llcy9nZXN0YWx0L3Nkay9nby9nZW4vdjE7cHJvdG9iBnByb3RvMw", [file_google_protobuf_empty]);
+
+/**
+ * @generated from message gestalt.provider.v1.AuthenticatedUser
+ */
+export type AuthenticatedUser = Message<"gestalt.provider.v1.AuthenticatedUser"> & {
+  /**
+   * @generated from field: string subject = 1;
+   */
+  subject: string;
+
+  /**
+   * @generated from field: string email = 2;
+   */
+  email: string;
+
+  /**
+   * @generated from field: bool email_verified = 3;
+   */
+  emailVerified: boolean;
+
+  /**
+   * @generated from field: string display_name = 4;
+   */
+  displayName: string;
+
+  /**
+   * @generated from field: string avatar_url = 5;
+   */
+  avatarUrl: string;
+
+  /**
+   * @generated from field: map<string, string> claims = 6;
+   */
+  claims: { [key: string]: string };
+};
+
+/**
+ * Describes the message gestalt.provider.v1.AuthenticatedUser.
+ * Use `create(AuthenticatedUserSchema)` to create a new message.
+ */
+export const AuthenticatedUserSchema: GenMessage<AuthenticatedUser> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 0);
+
+/**
+ * @generated from message gestalt.provider.v1.BeginLoginRequest
+ */
+export type BeginLoginRequest = Message<"gestalt.provider.v1.BeginLoginRequest"> & {
+  /**
+   * @generated from field: string callback_url = 1;
+   */
+  callbackUrl: string;
+
+  /**
+   * @generated from field: string host_state = 2;
+   */
+  hostState: string;
+
+  /**
+   * @generated from field: repeated string scopes = 3;
+   */
+  scopes: string[];
+
+  /**
+   * @generated from field: map<string, string> options = 4;
+   */
+  options: { [key: string]: string };
+};
+
+/**
+ * Describes the message gestalt.provider.v1.BeginLoginRequest.
+ * Use `create(BeginLoginRequestSchema)` to create a new message.
+ */
+export const BeginLoginRequestSchema: GenMessage<BeginLoginRequest> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 1);
+
+/**
+ * @generated from message gestalt.provider.v1.BeginLoginResponse
+ */
+export type BeginLoginResponse = Message<"gestalt.provider.v1.BeginLoginResponse"> & {
+  /**
+   * @generated from field: string authorization_url = 1;
+   */
+  authorizationUrl: string;
+
+  /**
+   * @generated from field: bytes provider_state = 2;
+   */
+  providerState: Uint8Array;
+};
+
+/**
+ * Describes the message gestalt.provider.v1.BeginLoginResponse.
+ * Use `create(BeginLoginResponseSchema)` to create a new message.
+ */
+export const BeginLoginResponseSchema: GenMessage<BeginLoginResponse> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 2);
+
+/**
+ * @generated from message gestalt.provider.v1.CompleteLoginRequest
+ */
+export type CompleteLoginRequest = Message<"gestalt.provider.v1.CompleteLoginRequest"> & {
+  /**
+   * @generated from field: map<string, string> query = 1;
+   */
+  query: { [key: string]: string };
+
+  /**
+   * @generated from field: bytes provider_state = 2;
+   */
+  providerState: Uint8Array;
+
+  /**
+   * @generated from field: string callback_url = 3;
+   */
+  callbackUrl: string;
+};
+
+/**
+ * Describes the message gestalt.provider.v1.CompleteLoginRequest.
+ * Use `create(CompleteLoginRequestSchema)` to create a new message.
+ */
+export const CompleteLoginRequestSchema: GenMessage<CompleteLoginRequest> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 3);
+
+/**
+ * @generated from message gestalt.provider.v1.ValidateExternalTokenRequest
+ */
+export type ValidateExternalTokenRequest = Message<"gestalt.provider.v1.ValidateExternalTokenRequest"> & {
+  /**
+   * @generated from field: string token = 1;
+   */
+  token: string;
+};
+
+/**
+ * Describes the message gestalt.provider.v1.ValidateExternalTokenRequest.
+ * Use `create(ValidateExternalTokenRequestSchema)` to create a new message.
+ */
+export const ValidateExternalTokenRequestSchema: GenMessage<ValidateExternalTokenRequest> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 4);
+
+/**
+ * @generated from message gestalt.provider.v1.AuthSessionSettings
+ */
+export type AuthSessionSettings = Message<"gestalt.provider.v1.AuthSessionSettings"> & {
+  /**
+   * @generated from field: int64 session_ttl_seconds = 1;
+   */
+  sessionTtlSeconds: bigint;
+};
+
+/**
+ * Describes the message gestalt.provider.v1.AuthSessionSettings.
+ * Use `create(AuthSessionSettingsSchema)` to create a new message.
+ */
+export const AuthSessionSettingsSchema: GenMessage<AuthSessionSettings> = /*@__PURE__*/
+  messageDesc(file_v1_auth, 5);
+
+/**
+ * @generated from service gestalt.provider.v1.AuthProvider
+ */
+export const AuthProvider: GenService<{
+  /**
+   * @generated from rpc gestalt.provider.v1.AuthProvider.BeginLogin
+   */
+  beginLogin: {
+    methodKind: "unary";
+    input: typeof BeginLoginRequestSchema;
+    output: typeof BeginLoginResponseSchema;
+  },
+  /**
+   * @generated from rpc gestalt.provider.v1.AuthProvider.CompleteLogin
+   */
+  completeLogin: {
+    methodKind: "unary";
+    input: typeof CompleteLoginRequestSchema;
+    output: typeof AuthenticatedUserSchema;
+  },
+  /**
+   * @generated from rpc gestalt.provider.v1.AuthProvider.ValidateExternalToken
+   */
+  validateExternalToken: {
+    methodKind: "unary";
+    input: typeof ValidateExternalTokenRequestSchema;
+    output: typeof AuthenticatedUserSchema;
+  },
+  /**
+   * @generated from rpc gestalt.provider.v1.AuthProvider.GetSessionSettings
+   */
+  getSessionSettings: {
+    methodKind: "unary";
+    input: typeof EmptySchema;
+    output: typeof AuthSessionSettingsSchema;
+  },
+}> = /*@__PURE__*/
+  serviceDesc(file_v1_auth, 0);
+