@slates/provider 1.0.0-rc.16 → 1.0.0-rc.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.16",
+  "version": "1.0.0-rc.18",
   "publishConfig": {
     "access": "public"
   },
@@ -42,4 +42,4 @@
     "typescript": "5.8.2",
     "vitest": "^3.1.2"
   }
-}
+}

package/src/action/action.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod';
-import type { SlateContext } from '../context';
+import type { SlateContext, SlatePublicContext } from '../context';
 import type { SlateActionDocsReference } from '../docs';
 import type { SlateSpecification } from '../specification/specification';
 import type { SlateAttachment } from './attachment';
@@ -29,6 +29,8 @@ export interface SlateActionParameters {
   scopes?: SlateActionScopes;
   authMethods?: string[];
   docs?: SlateActionDocsReference[];
+  adapter?: string | null;
+  isPublic?: boolean;
 }
 
 export type SlateToolInvocationHandler<
@@ -42,6 +44,14 @@ export type SlateToolInvocationHandler<
   attachments?: SlateAttachment[];
 }>;
 
+export type SlatePublicToolInvocationHandler<InputType extends {}, OutputType extends {}> = (
+  context: SlatePublicContext<InputType>
+) => Promise<{
+  output: OutputType;
+  message: string;
+  attachments?: SlateAttachment[];
+}>;
+
 export type SlateTriggerMappingHandler<
   ConfigType extends {},
   AuthType extends {},
@@ -62,15 +72,58 @@ export type SlateTriggerPollingHandler<
   updatedState?: any;
 }>;
 
+export interface SlateWebhookHttpResponseInit {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array | null;
+}
+
+export type SlateWebhookHttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'HEAD'
+  | 'OPTIONS';
+
+export interface SlateWebhookRequestMatcher {
+  method?: string;
+  hasQueryParam?: string;
+  hasHeader?: string;
+  jsonBodyField?: {
+    path: string;
+    equals?: string;
+  };
+  formBodyField?: {
+    path: string;
+    equals?: string;
+  };
+}
+
+export interface SlateWebhookHttpOptions {
+  methods?: SlateWebhookHttpMethod[];
+  sync?: {
+    mode: 'never' | 'match' | 'always';
+    match?: SlateWebhookRequestMatcher[];
+    timeoutMs?: number;
+  };
+}
+
 export type SlateTriggerWebhookRequestHandler<
   ConfigType extends {},
   AuthType extends {},
   InputType extends {}
 > = (
-  context: SlateContext<ConfigType, AuthType, { request: Request; state: any | null }>
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { request: Request; state: any | null; registrationDetails: any | null }
+  >
 ) => Promise<{
   inputs: InputType[];
   updatedState?: any;
+  response?: Response | SlateWebhookHttpResponseInit;
 }>;
 
 export type SlateTriggerWebhookAutoRegistrationHandler<
@@ -117,6 +170,7 @@ export interface SlateActionParametersTrigger<
   polling?: SlatePollingOptions;
   handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  http?: SlateWebhookHttpOptions;
   pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -214,4 +268,12 @@ export abstract class SlateAction<
   get docs() {
     return this._params.docs;
   }
+
+  get adapter() {
+    return this._params.adapter ?? null;
+  }
+
+  get isPublic() {
+    return this._params.isPublic === true;
+  }
 }

package/src/action/builder.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { SlateAuth } from '../auth';
+import { SlateConfig } from '../config';
+import { SlatePublicContext } from '../context';
+import { SlateSpecification } from '../specification/specification';
+import { SlatePublicTool } from './publicTool';
+import { SlateTool } from './tool';
+
+let createTestSpec = () => {
+  let config = SlateConfig.create(
+    z.object({
+      prefix: z.string()
+    })
+  );
+  let auth = SlateAuth.create<{ token: string }>().output(
+    z.object({
+      token: z.string()
+    })
+  );
+
+  return SlateSpecification.create({
+    key: 'demo',
+    name: 'Demo',
+    config,
+    auth
+  });
+};
+
+describe('SlateActionBuilder.lockInterface', () => {
+  it('prevents changing input and output schemas after the interface is locked', () => {
+    let spec = createTestSpec();
+    let builder = SlateTool.create(spec, {
+      key: 'send',
+      name: 'Send'
+    })
+      .input(z.object({ to: z.string() }))
+      .output(z.object({ id: z.string() }))
+      .lockInterface();
+
+    expect(() => builder.input(z.object({}))).toThrow(
+      'Adapter contract input schema cannot be changed'
+    );
+    expect(() => builder.output(z.object({}))).toThrow(
+      'Adapter contract output schema cannot be changed'
+    );
+  });
+});
+
+describe('SlatePublicTool', () => {
+  it('builds a public tool that omits config and auth from the handler context', async () => {
+    let spec = createTestSpec();
+    let tool = SlatePublicTool.create(spec, {
+      key: 'setup',
+      name: 'Setup'
+    })
+      .input(
+        z.object({
+          name: z.string()
+        })
+      )
+      .output(
+        z.object({
+          greeting: z.string()
+        })
+      )
+      .handleInvocation(async ctx => {
+        expect(ctx).not.toHaveProperty('config');
+        expect(ctx).not.toHaveProperty('auth');
+
+        return {
+          output: { greeting: `Hello ${ctx.input.name}` },
+          message: 'ok'
+        };
+      })
+      .build();
+
+    expect(tool.isPublic).toBe(true);
+    expect(tool.key).toBe('setup');
+
+    let result = await tool.handleInvocation(
+      new SlatePublicContext({ name: 'Ada' }, spec, {
+        debug: () => {},
+        error: () => {},
+        info: () => {},
+        progress: () => {},
+        warn: () => {}
+      } as any) as any
+    );
+
+    expect(result.output).toEqual({ greeting: 'Hello Ada' });
+  });
+
+  it('keeps regular tools private by default', () => {
+    let spec = createTestSpec();
+    let tool = SlateTool.create(spec, {
+      key: 'send',
+      name: 'Send'
+    })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    expect(tool.isPublic).toBe(false);
+  });
+
+  it('rejects authentication methods on public tools', () => {
+    let spec = createTestSpec();
+
+    expect(() =>
+      SlatePublicTool.create(spec, {
+        key: 'setup',
+        name: 'Setup'
+      }).authMethods(['token_auth'])
+    ).toThrow('Public tools cannot require authentication methods');
+
+    expect(() =>
+      SlatePublicTool.create(spec, {
+        key: 'setup',
+        name: 'Setup',
+        authMethods: ['token_auth']
+      })
+        .input(z.object({}))
+        .output(z.object({}))
+        .handleInvocation(async () => ({
+          output: {},
+          message: 'ok'
+        }))
+        .build()
+    ).toThrow('Public tools cannot require authentication methods');
+  });
+});

package/src/action/builder.ts

@@ -10,12 +10,14 @@ import type {
   SlateActionScopes,
   SlateActionType,
   SlatePollingOptions,
+  SlatePublicToolInvocationHandler,
   SlateToolInvocationHandler,
   SlateTriggerMappingHandler,
   SlateTriggerPollingHandler,
   SlateTriggerWebhookAutoRegistrationHandler,
   SlateTriggerWebhookAutoUnregistrationHandler,
-  SlateTriggerWebhookRequestHandler
+  SlateTriggerWebhookRequestHandler,
+  SlateWebhookHttpOptions
 } from './action';
 import { validateScopes } from './scopes';
 
@@ -25,7 +27,8 @@ export class SlateActionBuilder<
   AuthType extends {},
   InputType extends {},
   OutputType extends {},
-  Result extends SlateAction<Type, ConfigType, AuthType, any, any>
+  Result extends SlateAction<Type, ConfigType, AuthType, any, any>,
+  IsPublic extends boolean = false
 > {
   #configSchema: z.ZodType<ConfigType>;
   #authSchema: z.ZodType<AuthType>;
@@ -42,6 +45,7 @@ export class SlateActionBuilder<
     InputType,
     OutputType
   > | null = null;
+  #interfaceLocked = false;
 
   constructor(
     private readonly type: Type,
@@ -49,7 +53,8 @@ export class SlateActionBuilder<
     private readonly params: SlateActionParameters,
     private readonly factory: (
       params: SlateActionCreateParameters<any, any, any, any>
-    ) => Result
+    ) => Result,
+    private readonly isPublicTool: IsPublic = false as IsPublic
   ) {
     this.#configSchema = spec.configSchema;
     this.#authSchema = spec.authSchema;
@@ -57,21 +62,58 @@ export class SlateActionBuilder<
 
   input<NewInputType extends {}>(
     schema: z.ZodType<NewInputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, NewInputType, OutputType, Result> {
+  ): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    NewInputType,
+    OutputType,
+    Result,
+    IsPublic
+  > {
+    if (this.#interfaceLocked) {
+      throw new SlateDeclarationError('Adapter contract input schema cannot be changed');
+    }
+
     this.#inputSchema = schema as any;
     return this as any;
   }
 
   output<NewOutputType extends {}>(
     schema: z.ZodType<NewOutputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, NewOutputType, Result> {
+  ): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    InputType,
+    NewOutputType,
+    Result,
+    IsPublic
+  > {
+    if (this.#interfaceLocked) {
+      throw new SlateDeclarationError('Adapter contract output schema cannot be changed');
+    }
+
     this.#outputSchema = schema as any;
     return this as any;
   }
 
+  lockInterface(): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    InputType,
+    OutputType,
+    Result,
+    IsPublic
+  > {
+    this.#interfaceLocked = true;
+    return this;
+  }
+
   scopes(
     scopes: SlateActionScopes
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     validateScopes(scopes);
     this.#scopes = scopes;
     return this;
@@ -79,7 +121,11 @@ export class SlateActionBuilder<
 
   authMethods(
     authMethods: string[]
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
+    if (this.isPublicTool) {
+      throw new SlateDeclarationError('Public tools cannot require authentication methods');
+    }
+
     this.#authMethods = this.validateAuthMethods(authMethods);
     return this;
   }
@@ -96,15 +142,22 @@ export class SlateActionBuilder<
   }
 
   handleInvocation(
-    handler: SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+    handler: IsPublic extends true
+      ? SlatePublicToolInvocationHandler<InputType, OutputType>
+      : SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'tool') {
       throw new SlateDeclarationError('handleInvocation can only be set for tool actions');
     }
 
     this.#toolParams = {
       type: 'tool',
-      handleInvocation: handler
+      handleInvocation: handler as SlateToolInvocationHandler<
+        ConfigType,
+        AuthType,
+        InputType,
+        OutputType
+      >
     };
 
     return this;
@@ -115,7 +168,8 @@ export class SlateActionBuilder<
     handleRequest: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
     autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
     autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
-  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+    http?: SlateWebhookHttpOptions;
+  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'trigger') {
       throw new SlateDeclarationError('handleEvent can only be set for trigger actions');
     }
@@ -126,7 +180,8 @@ export class SlateActionBuilder<
       handleEvent: props.handleEvent,
       handleRequest: props.handleRequest,
       autoRegisterWebhook: props.autoRegisterWebhook,
-      autoUnregisterWebhook: props.autoUnregisterWebhook
+      autoUnregisterWebhook: props.autoUnregisterWebhook,
+      http: props.http
     };
 
     return this;
@@ -136,7 +191,7 @@ export class SlateActionBuilder<
     options?: SlatePollingOptions;
     pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
     handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
-  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'trigger') {
       throw new SlateDeclarationError('handleEvent can only be set for trigger actions');
     }
@@ -159,6 +214,10 @@ export class SlateActionBuilder<
     }
     let authMethods = this.validateAuthMethods(this.#authMethods ?? this.params.authMethods);
 
+    if (this.isPublicTool && authMethods) {
+      throw new SlateDeclarationError('Public tools cannot require authentication methods');
+    }
+
     if (!this.#inputSchema) {
       throw new SlateDeclarationError('Input schema is not defined');
     }
@@ -176,6 +235,7 @@ export class SlateActionBuilder<
       ...this.params,
       scopes,
       authMethods,
+      isPublic: this.isPublicTool === true,
       configSchema: this.#configSchema,
       authSchema: this.#authSchema,
       inputSchema: this.#inputSchema,

package/src/action/index.ts

@@ -1,5 +1,6 @@
 export * from './action';
-export type * from './builder';
+export * from './builder';
+export * from './publicTool';
 export * from './scopes';
 export * from './tool';
 export * from './trigger';

package/src/action/publicTool.ts

@@ -0,0 +1,36 @@
+import type { SlateSpecification } from '../specification/specification';
+import type { SlateActionParameters, SlatePublicToolInvocationHandler } from './action';
+import { SlateActionBuilder } from './builder';
+import { SlateTool } from './tool';
+
+export interface SlatePublicToolParameters<InputType extends {}, OutputType extends {}>
+  extends SlateActionParameters {
+  handleInvocation: SlatePublicToolInvocationHandler<InputType, OutputType>;
+}
+
+export class SlatePublicTool {
+  private constructor() {}
+
+  static create<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateActionParameters
+  ) {
+    return new SlateActionBuilder(
+      'tool',
+      spec,
+      params,
+      params => {
+        return SlateTool.fromCreateParameters(spec, {
+          ...params,
+          isPublic: true
+        });
+      },
+      true
+    );
+  }
+}
+
+export let publicTool = <ConfigType extends {}, AuthType extends {}>(
+  spec: SlateSpecification<ConfigType, AuthType>,
+  params: SlateActionParameters
+) => SlatePublicTool.create(spec, params);

package/src/action/tool.ts

@@ -24,7 +24,7 @@ export class SlateTool<
 > extends SlateAction<'tool', ConfigType, AuthType, InputType, OutputType> {
   #handleInvocation: SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>;
 
-  private constructor(
+  protected constructor(
     spec: SlateSpecification<ConfigType, AuthType>,
     inputSchema: z.ZodType<InputType>,
     outputSchema: z.ZodType<OutputType>,
@@ -40,11 +40,23 @@ export class SlateTool<
     params: SlateActionParameters
   ) {
     return new SlateActionBuilder('tool', spec, params, params => {
-      if (params.type !== 'tool') throw new Error('Invalid action type for tool');
-      return new SlateTool(spec, params.inputSchema, params.outputSchema, params);
+      return SlateTool.fromCreateParameters(spec, params);
     });
   }
 
+  static fromCreateParameters<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: {
+      type: string;
+      inputSchema: z.ZodType<any>;
+      outputSchema: z.ZodType<any>;
+      handleInvocation?: SlateToolInvocationHandler<ConfigType, AuthType, any, any>;
+    } & SlateActionParameters
+  ) {
+    if (params.type !== 'tool') throw new Error('Invalid action type for tool');
+    return new SlateTool(spec, params.inputSchema, params.outputSchema, params as any);
+  }
+
   get handleInvocation() {
     return this.#handleInvocation;
   }

package/src/action/trigger.ts

@@ -8,7 +8,8 @@ import {
   type SlateTriggerPollingHandler,
   type SlateTriggerWebhookAutoRegistrationHandler,
   type SlateTriggerWebhookAutoUnregistrationHandler,
-  type SlateTriggerWebhookRequestHandler
+  type SlateTriggerWebhookRequestHandler,
+  type SlateWebhookHttpOptions
 } from './action';
 import { SlateActionBuilder } from './builder';
 
@@ -27,6 +28,7 @@ export interface SlateTriggerParameters<
   polling?: SlatePollingOptions;
   handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  http?: SlateWebhookHttpOptions;
   pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -44,6 +46,7 @@ export class SlateTrigger<
   #polling: SlatePollingOptions;
   #handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   #handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  #http?: SlateWebhookHttpOptions;
   #pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   #autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   #autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -62,6 +65,7 @@ export class SlateTrigger<
     };
     this.#handleEvent = params.handleEvent;
     this.#handleRequest = params.handleRequest;
+    this.#http = params.http;
     this.#pollEvents = params.pollEvents;
     this.#autoRegisterWebhook = params.autoRegisterWebhook;
     this.#autoUnregisterWebhook = params.autoUnregisterWebhook;
@@ -93,6 +97,10 @@ export class SlateTrigger<
     return this.#handleRequest;
   }
 
+  get http() {
+    return this.#http;
+  }
+
   get pollEvents() {
     return this.#pollEvents;
   }

package/src/adapter/adapter.ts

@@ -0,0 +1,38 @@
+import type { SlateTool, SlateTrigger } from '../action';
+import type { SlateAdapterSpec } from './spec';
+
+export class SlateAdapter<ConfigType extends {}, AuthType extends {}> {
+  constructor(
+    private readonly _spec: SlateAdapterSpec,
+    private readonly _tools: SlateTool<ConfigType, AuthType, any, any>[],
+    private readonly _triggers: SlateTrigger<ConfigType, AuthType, any, any>[]
+  ) {}
+
+  get spec() {
+    return this._spec;
+  }
+
+  get id() {
+    return this._spec.id;
+  }
+
+  get name() {
+    return this._spec.name;
+  }
+
+  get capabilities() {
+    return this._spec.capabilities;
+  }
+
+  get tools() {
+    return this._tools;
+  }
+
+  get triggers() {
+    return this._triggers;
+  }
+
+  get actions() {
+    return [...this._triggers, ...this._tools];
+  }
+}