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

package/src/action/builder.ts

@@ -10,6 +10,7 @@ import type {
   SlateActionScopes,
   SlateActionType,
   SlatePollingOptions,
+  SlatePublicToolInvocationHandler,
   SlateToolInvocationHandler,
   SlateTriggerMappingHandler,
   SlateTriggerPollingHandler,
@@ -26,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>;
@@ -43,6 +45,7 @@ export class SlateActionBuilder<
     InputType,
     OutputType
   > | null = null;
+  #interfaceLocked = false;
 
   constructor(
     private readonly type: Type,
@@ -50,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;
@@ -58,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;
@@ -80,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;
   }
@@ -97,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;
@@ -117,7 +169,7 @@ export class SlateActionBuilder<
     autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
     autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
     http?: SlateWebhookHttpOptions;
-  }): 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');
     }
@@ -139,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');
     }
@@ -162,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');
     }
@@ -179,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/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];
+  }
+}

package/src/adapter/index.test.ts

@@ -0,0 +1,322 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { SlateTool } from '../action/tool';
+import { SlateAuth } from '../auth';
+import { SlateConfig } from '../config';
+import { Slate } from '../specification/slate';
+import { SlateSpecification } from '../specification/specification';
+import { SlateAdapterSpec } from './spec';
+
+let createTestSpec = () => {
+  let config = SlateConfig.create(z.object({}));
+  let auth = SlateAuth.create<{}>().output(z.object({}));
+
+  return SlateSpecification.create({
+    key: 'demo',
+    name: 'Demo',
+    config,
+    auth
+  });
+};
+
+describe('SlateAdapterSpec', () => {
+  it('creates adapter tools and triggers linked to the adapter, then registers them', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail',
+      capabilities: [{ id: 'send_email', value: true }]
+    });
+
+    let sendEmailTool = gmailAdapterSpec
+      .tool(spec, {
+        key: 'send_email',
+        name: 'Send Email'
+      })
+      .input(z.object({ to: z.string() }))
+      .output(z.object({ id: z.string() }))
+      .handleInvocation(async () => ({
+        output: { id: 'msg_1' },
+        message: 'sent'
+      }))
+      .build();
+
+    let emailReceivedTrigger = gmailAdapterSpec
+      .trigger(spec, {
+        key: 'email_received',
+        name: 'Email Received'
+      })
+      .input(z.object({ messageId: z.string() }))
+      .output(z.object({ type: z.literal('email.received') }))
+      .polling({
+        handleEvent: async ctx => ({
+          type: 'email.received',
+          id: ctx.input.messageId,
+          output: { type: 'email.received' as const }
+        })
+      })
+      .build();
+
+    expect(sendEmailTool.adapter).toBe('gmail');
+    expect(emailReceivedTrigger.adapter).toBe('gmail');
+
+    let gmailAdapter = gmailAdapterSpec.register({
+      tools: [sendEmailTool],
+      triggers: [emailReceivedTrigger]
+    });
+
+    expect(gmailAdapter.id).toBe('gmail');
+    expect(gmailAdapter.name).toBe('Gmail');
+    expect(gmailAdapter.capabilities).toEqual([{ id: 'send_email', value: true }]);
+    expect(gmailAdapter.tools).toEqual([sendEmailTool]);
+    expect(gmailAdapter.triggers).toEqual([emailReceivedTrigger]);
+
+    let providerTool = SlateTool.create(spec, {
+      key: 'list_labels',
+      name: 'List Labels'
+    })
+      .input(z.object({}))
+      .output(z.object({ labels: z.array(z.string()) }))
+      .handleInvocation(async () => ({
+        output: { labels: [] },
+        message: 'ok'
+      }))
+      .build();
+
+    let slate = Slate.create({
+      spec,
+      tools: [providerTool, sendEmailTool],
+      triggers: [emailReceivedTrigger],
+      adapters: [gmailAdapter]
+    });
+
+    expect(slate.actions.map(action => action.key)).toEqual([
+      'email_received',
+      'list_labels',
+      'send_email'
+    ]);
+    expect(slate.adapters).toEqual([gmailAdapter]);
+    expect(slate.actions.filter(action => !action.adapter).map(action => action.key)).toEqual([
+      'list_labels'
+    ]);
+  });
+
+  it('includes adapter actions in the slate even when they are only passed via the adapter', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail'
+    });
+
+    let sendEmailTool = gmailAdapterSpec
+      .tool(spec, {
+        key: 'send_email',
+        name: 'Send Email'
+      })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    let gmailAdapter = gmailAdapterSpec.register({
+      tools: [sendEmailTool],
+      triggers: []
+    });
+
+    let slate = Slate.create({
+      spec,
+      tools: [],
+      triggers: [],
+      adapters: [gmailAdapter]
+    });
+
+    expect(slate.actions).toEqual([sendEmailTool]);
+    expect(slate.actions[0]!.adapter).toBe('gmail');
+  });
+
+  it('rejects tools created for a different adapter', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail'
+    });
+    let outlookAdapterSpec = SlateAdapterSpec.create({
+      id: 'outlook',
+      name: 'Outlook'
+    });
+
+    let outlookTool = outlookAdapterSpec
+      .tool(spec, {
+        key: 'send_email',
+        name: 'Send Email'
+      })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    expect(() =>
+      gmailAdapterSpec.register({
+        tools: [outlookTool],
+        triggers: []
+      })
+    ).toThrow('Action "send_email" is linked to adapter "outlook", not "gmail"');
+  });
+
+  it('rejects provider tools that were not created through the adapter helpers', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail'
+    });
+
+    let providerTool = SlateTool.create(spec, {
+      key: 'send_email',
+      name: 'Send Email'
+    })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    expect(() =>
+      gmailAdapterSpec.register({
+        tools: [providerTool],
+        triggers: []
+      })
+    ).toThrow(
+      'Action "send_email" must be created with this adapter\'s tool(), publicTool(), or trigger() helpers'
+    );
+  });
+
+  it('rejects duplicate adapter action keys and duplicate adapter ids', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail'
+    });
+
+    let sendEmailTool = gmailAdapterSpec
+      .tool(spec, {
+        key: 'send_email',
+        name: 'Send Email'
+      })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    let sendEmailTrigger = gmailAdapterSpec
+      .trigger(spec, {
+        key: 'send_email',
+        name: 'Send Email Trigger'
+      })
+      .input(z.object({}))
+      .output(z.object({ type: z.string() }))
+      .polling({
+        handleEvent: async () => ({
+          type: 'email.sent',
+          id: '1',
+          output: { type: 'email.sent' }
+        })
+      })
+      .build();
+
+    expect(() =>
+      gmailAdapterSpec.register({
+        tools: [sendEmailTool],
+        triggers: [sendEmailTrigger]
+      })
+    ).toThrow('Adapter "gmail" already has an action with key "send_email"');
+
+    let adapter = gmailAdapterSpec.register({
+      tools: [sendEmailTool],
+      triggers: []
+    });
+
+    expect(() =>
+      Slate.create({
+        spec,
+        tools: [],
+        triggers: [],
+        adapters: [adapter, adapter]
+      })
+    ).toThrow('Adapter "gmail" is registered more than once');
+  });
+
+  it('rejects empty adapter ids and duplicate capability ids', () => {
+    expect(() =>
+      SlateAdapterSpec.create({
+        id: '  ',
+        name: 'Gmail'
+      })
+    ).toThrow('Adapter id must be a non-empty string');
+
+    expect(() =>
+      SlateAdapterSpec.create({
+        id: 'gmail',
+        name: 'Gmail',
+        capabilities: [
+          { id: 'send_email', value: true },
+          { id: 'send_email', value: false }
+        ]
+      })
+    ).toThrow('Adapter capability "send_email" is defined more than once');
+  });
+
+  it('creates public adapter tools that remain linked and public', () => {
+    let spec = createTestSpec();
+    let gmailAdapterSpec = SlateAdapterSpec.create({
+      id: 'gmail',
+      name: 'Gmail'
+    });
+
+    let setupTool = gmailAdapterSpec
+      .publicTool(spec, {
+        key: 'setup',
+        name: 'Setup'
+      })
+      .input(z.object({}))
+      .output(z.object({ ok: z.boolean() }))
+      .handleInvocation(async ctx => {
+        expect(ctx).not.toHaveProperty('config');
+        expect(ctx).not.toHaveProperty('auth');
+        return {
+          output: { ok: true },
+          message: 'ok'
+        };
+      })
+      .build();
+
+    expect(setupTool.adapter).toBe('gmail');
+    expect(setupTool.isPublic).toBe(true);
+
+    let gmailAdapter = gmailAdapterSpec.register({
+      tools: [setupTool],
+      triggers: []
+    });
+
+    let slate = Slate.create({
+      spec,
+      tools: [setupTool],
+      triggers: [],
+      adapters: [gmailAdapter]
+    });
+
+    expect(slate.actions.map(action => action.key)).toEqual(['setup']);
+    expect(slate.actions[0]!.isPublic).toBe(true);
+    expect(slate.actions[0]!.adapter).toBe('gmail');
+  });
+});

package/src/adapter/index.ts

@@ -0,0 +1,2 @@
+export * from './adapter';
+export * from './spec';