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

package/README.md

@@ -21,7 +21,7 @@ property in `package.json`:
   "gestalt": {
     "provider": {
       "kind": "plugin",
-      "target": "./provider.ts#provider"
+      "target": "./provider.ts#plugin"
     }
   }
 }
@@ -31,11 +31,9 @@ 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`
+- `gestalt.provider` as a string like `"plugin:./provider.ts#plugin"` or `"cache:./cache.ts#provider"`
 
-Use `"plugin"` as the kind token for executable integration providers. The
-older `"integration"` spelling is still accepted for compatibility.
+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.
@@ -46,14 +44,14 @@ Use explicit runtime schemas to define plugin operation inputs and outputs:
 
 ```ts
 import {
-  defineIntegrationProvider,
+  definePlugin,
   ok,
   operation,
   response,
   s,
 } from "@valon-technologies/gestalt";
 
-export const provider = defineIntegrationProvider({
+export const plugin = definePlugin({
   displayName: "Example Provider",
   description: "A provider implemented with the Gestalt TypeScript SDK",
   configure(name, config) {
@@ -96,12 +94,12 @@ 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:
+Authentication providers, cache providers, and secrets providers use dedicated helpers:
 
 ```ts
 import {
   Cache,
-  defineAuthProvider,
+  defineAuthenticationProvider,
   defineCacheProvider,
   defineSecretsProvider,
 } from "@valon-technologies/gestalt";
@@ -112,7 +110,7 @@ import {
 Source-mode runtime:
 
 ```sh
-gestalt-ts-runtime ROOT plugin:./provider.ts#provider
+gestalt-ts-runtime ROOT plugin:./provider.ts#plugin
 ```
 
 Release build:
@@ -142,19 +140,3 @@ 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 → authentication_pb.ts}

@@ -1,5 +1,5 @@
 // @generated by protoc-gen-es v2.11.0 with parameter "target=ts"
-// @generated from file v1/auth.proto (package gestalt.provider.v1, syntax proto3)
+// @generated from file v1/authentication.proto (package gestalt.provider.v1, syntax proto3)
 /* eslint-disable */
 
 import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
@@ -9,12 +9,15 @@ import { file_google_protobuf_empty } from "@bufbuild/protobuf/wkt";
 import type { Message } from "@bufbuild/protobuf";
 
 /**
- * Describes the file v1/auth.proto.
+ * Describes the file v1/authentication.proto.
  */
-export const file_v1_auth: GenFile = /*@__PURE__*/
-  fileDesc("Cg12MS9hdXRoLnByb3RvEhNnZXN0YWx0LnByb3ZpZGVyLnYxIugBChFBdXRoZW50aWNhdGVkVXNlchIPCgdzdWJqZWN0GAEgASgJEg0KBWVtYWlsGAIgASgJEhYKDmVtYWlsX3ZlcmlmaWVkGAMgASgIEhQKDGRpc3BsYXlfbmFtZRgEIAEoCRISCgphdmF0YXJfdXJsGAUgASgJEkIKBmNsYWltcxgGIAMoCzIyLmdlc3RhbHQucHJvdmlkZXIudjEuQXV0aGVudGljYXRlZFVzZXIuQ2xhaW1zRW50cnkaLQoLQ2xhaW1zRW50cnkSCwoDa2V5GAEgASgJEg0KBXZhbHVlGAIgASgJOgI4ASLDAQoRQmVnaW5Mb2dpblJlcXVlc3QSFAoMY2FsbGJhY2tfdXJsGAEgASgJEhIKCmhvc3Rfc3RhdGUYAiABKAkSDgoGc2NvcGVzGAMgAygJEkQKB29wdGlvbnMYBCADKAsyMy5nZXN0YWx0LnByb3ZpZGVyLnYxLkJlZ2luTG9naW5SZXF1ZXN0Lk9wdGlvbnNFbnRyeRouCgxPcHRpb25zRW50cnkSCwoDa2V5GAEgASgJEg0KBXZhbHVlGAIgASgJOgI4ASJHChJCZWdpbkxvZ2luUmVzcG9uc2USGQoRYXV0aG9yaXphdGlvbl91cmwYASABKAkSFgoOcHJvdmlkZXJfc3RhdGUYAiABKAwitwEKFENvbXBsZXRlTG9naW5SZXF1ZXN0EkMKBXF1ZXJ5GAEgAygLMjQuZ2VzdGFsdC5wcm92aWRlci52MS5Db21wbGV0ZUxvZ2luUmVxdWVzdC5RdWVyeUVudHJ5EhYKDnByb3ZpZGVyX3N0YXRlGAIgASgMEhQKDGNhbGxiYWNrX3VybBgDIAEoCRosCgpRdWVyeUVudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAEiLQocVmFsaWRhdGVFeHRlcm5hbFRva2VuUmVxdWVzdBINCgV0b2tlbhgBIAEoCSIyChNBdXRoU2Vzc2lvblNldHRpbmdzEhsKE3Nlc3Npb25fdHRsX3NlY29uZHMYASABKAMynQMKDEF1dGhQcm92aWRlchJdCgpCZWdpbkxvZ2luEiYuZ2VzdGFsdC5wcm92aWRlci52MS5CZWdpbkxvZ2luUmVxdWVzdBonLmdlc3RhbHQucHJvdmlkZXIudjEuQmVnaW5Mb2dpblJlc3BvbnNlEmIKDUNvbXBsZXRlTG9naW4SKS5nZXN0YWx0LnByb3ZpZGVyLnYxLkNvbXBsZXRlTG9naW5SZXF1ZXN0GiYuZ2VzdGFsdC5wcm92aWRlci52MS5BdXRoZW50aWNhdGVkVXNlchJyChVWYWxpZGF0ZUV4dGVybmFsVG9rZW4SMS5nZXN0YWx0LnByb3ZpZGVyLnYxLlZhbGlkYXRlRXh0ZXJuYWxUb2tlblJlcXVlc3QaJi5nZXN0YWx0LnByb3ZpZGVyLnYxLkF1dGhlbnRpY2F0ZWRVc2VyElYKEkdldFNlc3Npb25TZXR0aW5ncxIWLmdvb2dsZS5wcm90b2J1Zi5FbXB0eRooLmdlc3RhbHQucHJvdmlkZXIudjEuQXV0aFNlc3Npb25TZXR0aW5nc0I7WjlnaXRodWIuY29tL3ZhbG9uLXRlY2hub2xvZ2llcy9nZXN0YWx0L3Nkay9nby9nZW4vdjE7cHJvdG9iBnByb3RvMw", [file_google_protobuf_empty]);
+export const file_v1_authentication: GenFile = /*@__PURE__*/
+  fileDesc("Chd2MS9hdXRoZW50aWNhdGlvbi5wcm90bxITZ2VzdGFsdC5wcm92aWRlci52MSLoAQoRQXV0aGVudGljYXRlZFVzZXISDwoHc3ViamVjdBgBIAEoCRINCgVlbWFpbBgCIAEoCRIWCg5lbWFpbF92ZXJpZmllZBgDIAEoCBIUCgxkaXNwbGF5X25hbWUYBCABKAkSEgoKYXZhdGFyX3VybBgFIAEoCRJCCgZjbGFpbXMYBiADKAsyMi5nZXN0YWx0LnByb3ZpZGVyLnYxLkF1dGhlbnRpY2F0ZWRVc2VyLkNsYWltc0VudHJ5Gi0KC0NsYWltc0VudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAEiwwEKEUJlZ2luTG9naW5SZXF1ZXN0EhQKDGNhbGxiYWNrX3VybBgBIAEoCRISCgpob3N0X3N0YXRlGAIgASgJEg4KBnNjb3BlcxgDIAMoCRJECgdvcHRpb25zGAQgAygLMjMuZ2VzdGFsdC5wcm92aWRlci52MS5CZWdpbkxvZ2luUmVxdWVzdC5PcHRpb25zRW50cnkaLgoMT3B0aW9uc0VudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAEiRwoSQmVnaW5Mb2dpblJlc3BvbnNlEhkKEWF1dGhvcml6YXRpb25fdXJsGAEgASgJEhYKDnByb3ZpZGVyX3N0YXRlGAIgASgMIrcBChRDb21wbGV0ZUxvZ2luUmVxdWVzdBJDCgVxdWVyeRgBIAMoCzI0Lmdlc3RhbHQucHJvdmlkZXIudjEuQ29tcGxldGVMb2dpblJlcXVlc3QuUXVlcnlFbnRyeRIWCg5wcm92aWRlcl9zdGF0ZRgCIAEoDBIUCgxjYWxsYmFja191cmwYAyABKAkaLAoKUXVlcnlFbnRyeRILCgNrZXkYASABKAkSDQoFdmFsdWUYAiABKAk6AjgBIi0KHFZhbGlkYXRlRXh0ZXJuYWxUb2tlblJlcXVlc3QSDQoFdG9rZW4YASABKAkiMgoTQXV0aFNlc3Npb25TZXR0aW5ncxIbChNzZXNzaW9uX3R0bF9zZWNvbmRzGAEgASgDMqcDChZBdXRoZW50aWNhdGlvblByb3ZpZGVyEl0KCkJlZ2luTG9naW4SJi5nZXN0YWx0LnByb3ZpZGVyLnYxLkJlZ2luTG9naW5SZXF1ZXN0GicuZ2VzdGFsdC5wcm92aWRlci52MS5CZWdpbkxvZ2luUmVzcG9uc2USYgoNQ29tcGxldGVMb2dpbhIpLmdlc3RhbHQucHJvdmlkZXIudjEuQ29tcGxldGVMb2dpblJlcXVlc3QaJi5nZXN0YWx0LnByb3ZpZGVyLnYxLkF1dGhlbnRpY2F0ZWRVc2VyEnIKFVZhbGlkYXRlRXh0ZXJuYWxUb2tlbhIxLmdlc3RhbHQucHJvdmlkZXIudjEuVmFsaWRhdGVFeHRlcm5hbFRva2VuUmVxdWVzdBomLmdlc3RhbHQucHJvdmlkZXIudjEuQXV0aGVudGljYXRlZFVzZXISVgoSR2V0U2Vzc2lvblNldHRpbmdzEhYuZ29vZ2xlLnByb3RvYnVmLkVtcHR5GiguZ2VzdGFsdC5wcm92aWRlci52MS5BdXRoU2Vzc2lvblNldHRpbmdzQjtaOWdpdGh1Yi5jb20vdmFsb24tdGVjaG5vbG9naWVzL2dlc3RhbHQvc2RrL2dvL2dlbi92MTtwcm90b2IGcHJvdG8z", [file_google_protobuf_empty]);
 
 /**
+ * AuthenticatedUser is the normalized user identity returned by an authentication
+ * provider after a login or token-validation flow.
+ *
  * @generated from message gestalt.provider.v1.AuthenticatedUser
  */
 export type AuthenticatedUser = Message<"gestalt.provider.v1.AuthenticatedUser"> & {
@@ -54,28 +57,39 @@ export type AuthenticatedUser = Message<"gestalt.provider.v1.AuthenticatedUser">
  * Use `create(AuthenticatedUserSchema)` to create a new message.
  */
 export const AuthenticatedUserSchema: GenMessage<AuthenticatedUser> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 0);
+  messageDesc(file_v1_authentication, 0);
 
 /**
+ * BeginLoginRequest starts an interactive login flow.
+ *
  * @generated from message gestalt.provider.v1.BeginLoginRequest
  */
 export type BeginLoginRequest = Message<"gestalt.provider.v1.BeginLoginRequest"> & {
   /**
+   * callback_url is the host-managed URL the provider should redirect back to.
+   *
    * @generated from field: string callback_url = 1;
    */
   callbackUrl: string;
 
   /**
+   * host_state is opaque state generated by the host and echoed back on
+   * completion.
+   *
    * @generated from field: string host_state = 2;
    */
   hostState: string;
 
   /**
+   * scopes are the provider-specific scopes the host is requesting.
+   *
    * @generated from field: repeated string scopes = 3;
    */
   scopes: string[];
 
   /**
+   * options carries provider-specific login parameters.
+   *
    * @generated from field: map<string, string> options = 4;
    */
   options: { [key: string]: string };
@@ -86,9 +100,12 @@ export type BeginLoginRequest = Message<"gestalt.provider.v1.BeginLoginRequest">
  * Use `create(BeginLoginRequestSchema)` to create a new message.
  */
 export const BeginLoginRequestSchema: GenMessage<BeginLoginRequest> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 1);
+  messageDesc(file_v1_authentication, 1);
 
 /**
+ * BeginLoginResponse returns the provider-managed authorization URL and opaque
+ * provider state that must be preserved until completion.
+ *
  * @generated from message gestalt.provider.v1.BeginLoginResponse
  */
 export type BeginLoginResponse = Message<"gestalt.provider.v1.BeginLoginResponse"> & {
@@ -108,23 +125,32 @@ export type BeginLoginResponse = Message<"gestalt.provider.v1.BeginLoginResponse
  * Use `create(BeginLoginResponseSchema)` to create a new message.
  */
 export const BeginLoginResponseSchema: GenMessage<BeginLoginResponse> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 2);
+  messageDesc(file_v1_authentication, 2);
 
 /**
+ * CompleteLoginRequest finishes an interactive login flow.
+ *
  * @generated from message gestalt.provider.v1.CompleteLoginRequest
  */
 export type CompleteLoginRequest = Message<"gestalt.provider.v1.CompleteLoginRequest"> & {
   /**
+   * query contains the callback URL query parameters returned by the identity
+   * provider.
+   *
    * @generated from field: map<string, string> query = 1;
    */
   query: { [key: string]: string };
 
   /**
+   * provider_state is the opaque state returned from BeginLoginResponse.
+   *
    * @generated from field: bytes provider_state = 2;
    */
   providerState: Uint8Array;
 
   /**
+   * callback_url is the fully qualified callback URL used by the host.
+   *
    * @generated from field: string callback_url = 3;
    */
   callbackUrl: string;
@@ -135,9 +161,12 @@ export type CompleteLoginRequest = Message<"gestalt.provider.v1.CompleteLoginReq
  * Use `create(CompleteLoginRequestSchema)` to create a new message.
  */
 export const CompleteLoginRequestSchema: GenMessage<CompleteLoginRequest> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 3);
+  messageDesc(file_v1_authentication, 3);
 
 /**
+ * ValidateExternalTokenRequest asks the provider to validate a token minted
+ * outside the interactive login flow.
+ *
  * @generated from message gestalt.provider.v1.ValidateExternalTokenRequest
  */
 export type ValidateExternalTokenRequest = Message<"gestalt.provider.v1.ValidateExternalTokenRequest"> & {
@@ -152,9 +181,11 @@ export type ValidateExternalTokenRequest = Message<"gestalt.provider.v1.Validate
  * Use `create(ValidateExternalTokenRequestSchema)` to create a new message.
  */
 export const ValidateExternalTokenRequestSchema: GenMessage<ValidateExternalTokenRequest> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 4);
+  messageDesc(file_v1_authentication, 4);
 
 /**
+ * AuthSessionSettings configures how the host persists authenticated sessions.
+ *
  * @generated from message gestalt.provider.v1.AuthSessionSettings
  */
 export type AuthSessionSettings = Message<"gestalt.provider.v1.AuthSessionSettings"> & {
@@ -169,14 +200,17 @@ export type AuthSessionSettings = Message<"gestalt.provider.v1.AuthSessionSettin
  * Use `create(AuthSessionSettingsSchema)` to create a new message.
  */
 export const AuthSessionSettingsSchema: GenMessage<AuthSessionSettings> = /*@__PURE__*/
-  messageDesc(file_v1_auth, 5);
+  messageDesc(file_v1_authentication, 5);
 
 /**
- * @generated from service gestalt.provider.v1.AuthProvider
+ * AuthenticationProvider models the shared Gestalt authentication-provider
+ * protocol.
+ *
+ * @generated from service gestalt.provider.v1.AuthenticationProvider
  */
-export const AuthProvider: GenService<{
+export const AuthenticationProvider: GenService<{
   /**
-   * @generated from rpc gestalt.provider.v1.AuthProvider.BeginLogin
+   * @generated from rpc gestalt.provider.v1.AuthenticationProvider.BeginLogin
    */
   beginLogin: {
     methodKind: "unary";
@@ -184,7 +218,7 @@ export const AuthProvider: GenService<{
     output: typeof BeginLoginResponseSchema;
   },
   /**
-   * @generated from rpc gestalt.provider.v1.AuthProvider.CompleteLogin
+   * @generated from rpc gestalt.provider.v1.AuthenticationProvider.CompleteLogin
    */
   completeLogin: {
     methodKind: "unary";
@@ -192,7 +226,7 @@ export const AuthProvider: GenService<{
     output: typeof AuthenticatedUserSchema;
   },
   /**
-   * @generated from rpc gestalt.provider.v1.AuthProvider.ValidateExternalToken
+   * @generated from rpc gestalt.provider.v1.AuthenticationProvider.ValidateExternalToken
    */
   validateExternalToken: {
     methodKind: "unary";
@@ -200,7 +234,7 @@ export const AuthProvider: GenService<{
     output: typeof AuthenticatedUserSchema;
   },
   /**
-   * @generated from rpc gestalt.provider.v1.AuthProvider.GetSessionSettings
+   * @generated from rpc gestalt.provider.v1.AuthenticationProvider.GetSessionSettings
    */
   getSessionSettings: {
     methodKind: "unary";
@@ -208,5 +242,5 @@ export const AuthProvider: GenService<{
     output: typeof AuthSessionSettingsSchema;
   },
 }> = /*@__PURE__*/
-  serviceDesc(file_v1_auth, 0);
+  serviceDesc(file_v1_authentication, 0);