@slates/provider-handler 1.0.0-rc.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@slates/provider-handler",
+  "version": "1.0.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Tobias Herber",
+  "license": "Apache 2",
+  "type": "module",
+  "source": "src/index.ts",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.module.js",
+    "default": "./dist/index.module.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.module.js",
+  "types": "dist/index.d.ts",
+  "unpkg": "./dist/index.umd.js",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "lint": "prettier src/**/*.ts --check",
+    "build": "microbundle"
+  },
+  "dependencies": {
+    "@lowerdeck/error": "^1.0.8",
+    "@slates/proto": "^1.0.0-rc.1",
+    "@slates/provider": "^1.0.0-rc.1",
+    "@slates/provider-handler": "^1.0.0-rc.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "microbundle": "^0.15.1",
+    "@slates/tsconfig": "^1.0.0",
+    "typescript": "5.8.2",
+    "vitest": "^3.1.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,512 @@
+import { badRequestError, preconditionFailedError, ServiceError } from '@lowerdeck/error';
+import { createSlatesProviderProtoHandler, SlatesParticipant } from '@slates/proto';
+import { Slate, SlateContext, SlateLogger, SlateLogListener } from '@slates/provider';
+import { getAction, getActionWithType, getAuthMethod, mapAction, mapAuthMethod } from './spec';
+import { State } from './state';
+import { validate } from './validation';
+
+export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  listeners: SlateLogListener[]
+) =>
+  createSlatesProviderProtoHandler(async manager => {
+    let protocol = new State<string | null>(null);
+    let participants = new State<SlatesParticipant[] | null>(null);
+
+    let auth = new State<{ authenticationMethodId: string; output: AuthType } | null>(null);
+    let config = new State<{ value: ConfigType } | null>(null);
+
+    let session = new State<{ id: string; state: any } | null>(null);
+
+    let logger = new SlateLogger(listeners);
+
+    let getContextBasic = () => {
+      let currentProtocol = protocol.get();
+      let currentParticipants = participants.get();
+
+      if (!currentProtocol || !currentParticipants) {
+        throw new ServiceError(
+          preconditionFailedError({
+            message: 'Connection context has not been initialized'
+          })
+        );
+      }
+
+      return {
+        protocol: currentProtocol,
+        participants: currentParticipants
+      };
+    };
+
+    let getContextFull = () => {
+      let basic = getContextBasic();
+
+      let currentConfig = config.get();
+      let currentSession = session.get();
+      let currentAuth = auth.get();
+
+      if (
+        !currentConfig ||
+        !currentSession ||
+        (!currentAuth && slate.spec.auth.authStack.length > 0)
+      ) {
+        throw new ServiceError(
+          preconditionFailedError({
+            message: 'Session context has not been initialized'
+          })
+        );
+      }
+
+      return {
+        ...basic,
+        config: currentConfig.value,
+        session: currentSession,
+        auth: currentAuth
+      };
+    };
+
+    manager.onNotification('slates/hello', async ({ params }) => {
+      protocol.set(params.protocol);
+    });
+
+    manager.onNotification('slates/participant.set', async ({ params }) => {
+      if (!protocol.get()) {
+        throw new ServiceError(
+          preconditionFailedError({ message: 'Connection protocol has not been initialized' })
+        );
+      }
+
+      participants.set(params.participants);
+    });
+
+    manager.onNotification('slates/auth.set', async ({ params }) => {
+      getContextBasic();
+      getAuthMethod(slate, params.authenticationMethodId); // validate method ID
+
+      let valRes = validate(
+        slate.spec.authSchema,
+        params.output,
+        'auth',
+        `Invalid authentication output for method ID: ${params.authenticationMethodId}`
+      );
+
+      auth.set({
+        authenticationMethodId: params.authenticationMethodId,
+        output: valRes
+      });
+    });
+
+    manager.onNotification('slates/config.set', async ({ params }) => {
+      getContextBasic();
+
+      let value = validate(
+        slate.spec.configSchema,
+        params.config,
+        'config',
+        'Invalid configuration'
+      );
+
+      config.set({ value });
+    });
+
+    manager.onNotification('slates/session.start', async ({ params }) => {
+      getContextBasic();
+
+      session.set({
+        id: params.sessionId,
+        state: params.state
+      });
+    });
+
+    manager.onRequest('slates/config.changed', async ({ params }) => {
+      getContextBasic();
+
+      let newConfig = validate(
+        slate.spec.config.configSchema,
+        params.newConfig,
+        'config',
+        'Invalid configuration'
+      );
+
+      let configChanged = slate.spec.config.handlers.configChanged;
+      if (!configChanged) {
+        return { success: true, config: newConfig };
+      }
+
+      let updatedConfig = await configChanged({
+        previousConfig: params.previousConfig as ConfigType | null,
+        newConfig
+      });
+
+      return { success: true, config: updatedConfig?.config ?? newConfig };
+    });
+
+    manager.onRequest('slates/config.get_default', async ({ params }) => {
+      getContextBasic();
+
+      let getDefaultConfig = slate.spec.config.handlers.getDefaultConfig;
+      if (!getDefaultConfig) {
+        return { config: null };
+      }
+
+      let defaultConfig = await getDefaultConfig();
+      return { config: defaultConfig };
+    });
+
+    manager.onRequest('slates/config.schema.get', async ({ params }) => {
+      getContextBasic();
+
+      return { schema: slate.spec.configSchema.toJSONSchema() };
+    });
+
+    manager.onRequest('slates/provider.identify', async ({ params }) => {
+      getContextBasic();
+
+      return {
+        protocol: 'slates@2026-01-01',
+        provider: {
+          type: 'provider',
+          id: slate.spec.key,
+          name: slate.spec.name,
+          description: slate.spec.description,
+          metadata: slate.spec.parameters.metadata
+        }
+      };
+    });
+
+    manager.onRequest('slates/auth.methods.list', async ({ params }) => {
+      getContextBasic();
+
+      return {
+        authenticationMethods: slate.spec.auth.authStack.map(m => mapAuthMethod(slate, m))
+      };
+    });
+
+    manager.onRequest('slates/auth.method.get', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      return {
+        authenticationMethod: mapAuthMethod(slate, authMethod)
+      };
+    });
+
+    manager.onRequest('slates/auth.input.get_default', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if (!authMethod.getDefaultInput) {
+        return { input: null };
+      }
+
+      return { input: await authMethod.getDefaultInput() };
+    });
+
+    manager.onRequest('slates/auth.input.changed', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if (!authMethod.onInputChanged) {
+        return { success: true, input: params.newInput };
+      }
+
+      let updatedInput = await authMethod.onInputChanged({
+        previousInput: params.previousInput as any | null,
+        newInput: params.newInput
+      });
+
+      return { success: true, input: updatedInput?.input ?? params.newInput };
+    });
+
+    manager.onRequest('slates/auth.output.get', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      let input = params.input;
+
+      if (authMethod.inputSchema) {
+        input = validate(
+          authMethod.inputSchema,
+          input,
+          'auth',
+          `Invalid authentication input for method ID: ${params.authenticationMethodId}`
+        );
+      }
+
+      if ('getOutput' in authMethod) {
+        let outputRes = await authMethod.getOutput({ input });
+        return { output: outputRes.output };
+      }
+
+      return { output: input as any };
+    });
+
+    manager.onRequest('slates/auth.authorization_callback.handle', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if ('handleCallback' in authMethod) {
+        let callbackRes = await authMethod.handleCallback({
+          code: params.code,
+          state: params.state,
+          redirectUri: params.redirectUri,
+          input: params.input,
+          clientId: params.clientId,
+          clientSecret: params.clientSecret,
+          scopes: params.scopes
+        });
+
+        return {
+          output: callbackRes.output,
+          input: callbackRes.input
+        };
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support authorization callback handling: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/auth.authorization_url.get', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if ('getAuthorizationUrl' in authMethod) {
+        let urlRes = await authMethod.getAuthorizationUrl({
+          redirectUri: params.redirectUri,
+          state: params.state,
+          input: params.input,
+          clientId: params.clientId,
+          clientSecret: params.clientSecret,
+          scopes: params.scopes
+        });
+
+        return {
+          authorizationUrl: urlRes.url,
+          input: urlRes.input
+        };
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/auth.profile.get', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if (authMethod.getProfile) {
+        let profileRes = await authMethod.getProfile({
+          output: params.output as any,
+          input: params.input,
+          scopes: params.scopes
+        });
+
+        return {
+          profile: profileRes.profile
+        };
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support profile retrieval: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/auth.token_refresh.handle', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if ('handleTokenRefresh' in authMethod && authMethod.handleTokenRefresh) {
+        let refreshRes = await authMethod.handleTokenRefresh({
+          output: params.output as any,
+          input: params.input,
+          clientId: params.clientId,
+          clientSecret: params.clientSecret,
+          scopes: params.scopes
+        });
+
+        return {
+          output: refreshRes.output,
+          input: refreshRes.input
+        };
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support token refresh handling: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/actions.list', async ({ params }) => {
+      getContextBasic();
+
+      return {
+        actions: slate.actions.map(a => mapAction(slate, a))
+      };
+    });
+
+    manager.onRequest('slates/action.get', async ({ params }) => {
+      getContextBasic();
+      let action = getAction(slate, params.actionId);
+
+      return {
+        action: mapAction(slate, action)
+      };
+    });
+
+    manager.onRequest('slates/action.tool.invoke', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'tool', params.actionId);
+
+      let input = validate(
+        action.inputSchema,
+        params.input,
+        'input',
+        `Invalid input for tool ID: ${params.actionId}`
+      );
+
+      let res = await action.handleInvocation(
+        new SlateContext(ctx.config, input, ctx.auth?.output!, slate.spec, logger)
+      );
+
+      return { output: res.output, message: res.message };
+    });
+
+    manager.onRequest('slates/action.trigger.map_event', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'trigger', params.actionId);
+
+      let input = validate(
+        action.inputSchema,
+        params.input,
+        'input',
+        `Invalid event for trigger ID: ${params.actionId}`
+      );
+
+      let res = await action.handleEvent(
+        new SlateContext(ctx.config, input, ctx.auth?.output!, slate.spec, logger)
+      );
+
+      return { id: res.id, type: res.type, output: res.output };
+    });
+
+    manager.onRequest('slates/action.trigger.poll_events', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'trigger', params.actionId);
+
+      if (!action.pollEvents) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger action does not support polling: ${params.actionId}`
+          })
+        );
+      }
+
+      let res = await action.pollEvents(
+        new SlateContext(
+          ctx.config,
+          { state: params.state },
+          ctx.auth?.output!,
+          slate.spec,
+          logger
+        )
+      );
+
+      return { inputs: res.inputs, updatedState: res.updatedState };
+    });
+
+    manager.onRequest('slates/action.trigger.webhook_handle', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'trigger', params.actionId);
+
+      if (!action.handleRequest) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger action does not support webhook requests: ${params.actionId}`
+          })
+        );
+      }
+
+      let req = new Request(params.url, {
+        method: params.method,
+        headers: params.headers,
+        body: params.body
+          ? Uint8Array.from(atob(params.body.content), c => c.charCodeAt(0))
+          : null
+      });
+
+      let res = await action.handleRequest(
+        new SlateContext(
+          ctx.config,
+          { request: req, state: params.state },
+          ctx.auth?.output!,
+          slate.spec,
+          logger
+        )
+      );
+
+      return { inputs: res.inputs, updatedState: res.updatedState };
+    });
+
+    manager.onRequest('slates/action.trigger.webhook_register', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'trigger', params.actionId);
+
+      if (!action.autoRegisterWebhook) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger action does not support webhook auto-registration: ${params.actionId}`
+          })
+        );
+      }
+
+      let res = await action.autoRegisterWebhook(
+        new SlateContext(
+          ctx.config,
+          { webhookBaseUrl: params.webhookBaseUrl },
+          ctx.auth?.output!,
+          slate.spec,
+          logger
+        )
+      );
+
+      return { registrationDetails: res.registrationDetails, state: res.state };
+    });
+
+    manager.onRequest('slates/action.trigger.webhook_unregister', async ({ params }) => {
+      let ctx = getContextFull();
+      let action = getActionWithType(slate, 'trigger', params.actionId);
+
+      if (!action.autoUnregisterWebhook) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger action does not support webhook auto-unregistration: ${params.actionId}`
+          })
+        );
+      }
+
+      await action.autoUnregisterWebhook(
+        new SlateContext(
+          ctx.config,
+          {
+            webhookBaseUrl: params.webhookBaseUrl,
+            registrationDetails: params.registrationDetails,
+            state: params.state
+          },
+          ctx.auth?.output!,
+          slate.spec,
+          logger
+        )
+      );
+
+      return {};
+    });
+  });

package/src/spec.ts

@@ -0,0 +1,129 @@
+import { badRequestError, notFoundError, ServiceError } from '@lowerdeck/error';
+import { SlateAuthenticationMethod, SlatesAction } from '@slates/proto';
+import { Slate, SlateDefaultPollingIntervalSeconds } from '@slates/provider';
+import z from 'zod';
+
+export let getAuthMethod = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  authenticationMethodId: string
+) => {
+  let authMethod = slate.spec.auth.authStack.find(m => m.key == authenticationMethodId);
+  if (!authMethod) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Invalid authentication method ID: ${authenticationMethodId}`
+      })
+    );
+  }
+
+  return authMethod;
+};
+
+export let mapAuthMethod = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  m: ReturnType<typeof getAuthMethod<ConfigType, AuthType>>
+): SlateAuthenticationMethod => ({
+  id: m.key,
+  name: m.name,
+  type: m.type,
+
+  scopes:
+    'scopes' in m
+      ? m.scopes.map(s => ({
+          id: s.scope,
+          title: s.title,
+          description: s.description
+        }))
+      : undefined,
+
+  inputSchema: (m.inputSchema ?? z.object({})).toJSONSchema(),
+  outputSchema: slate.spec.auth.outputSchema.toJSONSchema(),
+
+  capabilities: {
+    getDefaultInput: { enabled: !!('getDefaultInput' in m && m.getDefaultInput) },
+    handleTokenRefresh: {
+      enabled: !!('handleTokenRefresh' in m && m.handleTokenRefresh)
+    },
+    handleChangedInput: {
+      enabled: !!m.onInputChanged
+    },
+    getProfile: { enabled: !!m.getProfile }
+  }
+});
+
+export let getAction = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  actionId: string
+) => {
+  let action = slate.actions.find(m => m.key == actionId);
+  if (!action) {
+    throw new ServiceError(notFoundError(`action`, actionId));
+  }
+
+  return action;
+};
+
+export let getActionWithType = <
+  Type extends 'tool' | 'trigger',
+  ConfigType extends {},
+  AuthType extends {}
+>(
+  slate: Slate<ConfigType, AuthType>,
+  type: Type,
+  actionId: string
+): ReturnType<typeof getAction<ConfigType, AuthType>> & { type: Type } => {
+  let action = getAction(slate, actionId);
+  if (action.type != type) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Action with ID ${actionId} is not of type ${type}`
+      })
+    );
+  }
+
+  return action as any;
+};
+
+export let mapAction = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  a: ReturnType<typeof getAction<ConfigType, AuthType>>
+): SlatesAction => {
+  let base = {
+    id: a.key,
+    name: a.name,
+    description: a.description,
+    instructions: a.instructions,
+    constraints: a.constraints,
+    tags: a.tags,
+    metadata: a.metadata,
+
+    inputSchema: a.inputSchema.toJSONSchema(),
+    outputSchema: a.outputSchema.toJSONSchema()
+  };
+
+  if (a.type == 'tool') {
+    return {
+      ...base,
+      type: 'action.tool',
+      capabilities: {}
+    };
+  }
+
+  return {
+    ...base,
+    type: 'action.trigger',
+    capabilities: {},
+
+    invocation:
+      a.source == 'polling'
+        ? {
+            type: 'polling',
+            intervalSeconds: a.polling.intervalInSeconds ?? SlateDefaultPollingIntervalSeconds
+          }
+        : {
+            type: 'webhook',
+            autoRegistration: !!a.autoRegisterWebhook,
+            autoUnregistration: !!a.autoUnregisterWebhook
+          }
+  };
+};

package/src/state.ts

@@ -0,0 +1,19 @@
+export class State<T> {
+  #value: T;
+
+  get value() {
+    return this.#value;
+  }
+
+  get() {
+    return this.#value;
+  }
+
+  set(value: T) {
+    this.#value = value;
+  }
+
+  constructor(initialValue: T) {
+    this.#value = initialValue;
+  }
+}

package/src/validation.ts

@@ -0,0 +1,27 @@
+import { ServiceError, validationError } from '@lowerdeck/error';
+import z from 'zod';
+
+export let zodToValidationError = (entity: string, message: string, e: z.ZodError) => {
+  return validationError({
+    message,
+    entity,
+    errors: e.issues.map(i => ({
+      ...i,
+      path: i.path.map(p => String(p))
+    }))
+  });
+};
+
+export let validate = <T>(
+  schema: z.ZodType<T>,
+  data: unknown,
+  entity: string,
+  message: string
+): T => {
+  let result = schema.safeParse(data);
+  if (!result.success) {
+    throw new ServiceError(zodToValidationError(entity, message, result.error));
+  }
+
+  return result.data;
+};

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@slates/tsconfig/base.json",
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "outDir": "dist"
+  }
+}