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

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';

package/src/adapter/spec.ts

@@ -0,0 +1,154 @@
+import {
+  type SlateActionParameters,
+  SlatePublicTool,
+  SlateTool,
+  SlateTrigger
+} from '../action';
+import { SlateDeclarationError } from '../error';
+import type { SlateSpecification } from '../specification/specification';
+import { SlateAdapter } from './adapter';
+
+export interface SlateAdapterCapability {
+  id: string;
+  value: any;
+}
+
+export interface SlateAdapterSpecParameters {
+  id: string;
+  name: string;
+  capabilities?: SlateAdapterCapability[];
+}
+
+export class SlateAdapterSpec {
+  private constructor(
+    private readonly _params: {
+      id: string;
+      name: string;
+      capabilities: SlateAdapterCapability[];
+    }
+  ) {}
+
+  static create(params: SlateAdapterSpecParameters): SlateAdapterSpec {
+    let id = params.id?.trim();
+    let name = params.name?.trim();
+
+    if (!id) {
+      throw new SlateDeclarationError('Adapter id must be a non-empty string');
+    }
+    if (!name) {
+      throw new SlateDeclarationError('Adapter name must be a non-empty string');
+    }
+
+    return new SlateAdapterSpec({
+      id,
+      name,
+      capabilities: validateCapabilities(params.capabilities ?? [])
+    });
+  }
+
+  get id() {
+    return this._params.id;
+  }
+
+  get name() {
+    return this._params.name;
+  }
+
+  get capabilities() {
+    return this._params.capabilities;
+  }
+
+  get parameters() {
+    return this._params;
+  }
+
+  tool<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateActionParameters
+  ) {
+    return SlateTool.create(spec, this.linkAction(params));
+  }
+
+  publicTool<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateActionParameters
+  ) {
+    return SlatePublicTool.create(spec, this.linkAction(params));
+  }
+
+  trigger<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateActionParameters
+  ) {
+    return SlateTrigger.create(spec, this.linkAction(params));
+  }
+
+  register<ConfigType extends {}, AuthType extends {}>(params: {
+    tools: SlateTool<ConfigType, AuthType, any, any>[];
+    triggers: SlateTrigger<ConfigType, AuthType, any, any>[];
+  }): SlateAdapter<ConfigType, AuthType> {
+    let actions = [...params.tools, ...params.triggers];
+    let seenKeys = new Set<string>();
+
+    for (let action of actions) {
+      if (action.adapter && action.adapter !== this.id) {
+        throw new SlateDeclarationError(
+          `Action "${action.key}" is linked to adapter "${action.adapter}", not "${this.id}"`
+        );
+      }
+
+      if (!action.adapter) {
+        throw new SlateDeclarationError(
+          `Action "${action.key}" must be created with this adapter's tool(), publicTool(), or trigger() helpers`
+        );
+      }
+
+      if (seenKeys.has(action.key)) {
+        throw new SlateDeclarationError(
+          `Adapter "${this.id}" already has an action with key "${action.key}"`
+        );
+      }
+
+      seenKeys.add(action.key);
+    }
+
+    return new SlateAdapter(this, params.tools, params.triggers);
+  }
+
+  private linkAction(params: SlateActionParameters): SlateActionParameters {
+    if (params.adapter != null && params.adapter !== this.id) {
+      throw new SlateDeclarationError(
+        `Action "${params.key}" cannot be linked to adapter "${this.id}" because it is already linked to "${params.adapter}"`
+      );
+    }
+
+    return {
+      ...params,
+      adapter: this.id
+    };
+  }
+}
+
+export let adapterSpec = (params: SlateAdapterSpecParameters) =>
+  SlateAdapterSpec.create(params);
+
+let validateCapabilities = (capabilities: SlateAdapterCapability[]) => {
+  let seenIds = new Set<string>();
+
+  return capabilities.map(capability => {
+    let id = capability.id?.trim();
+    if (!id) {
+      throw new SlateDeclarationError('Adapter capability ids must be non-empty strings');
+    }
+    if (seenIds.has(id)) {
+      throw new SlateDeclarationError(`Adapter capability "${id}" is defined more than once`);
+    }
+
+    seenIds.add(id);
+
+    return {
+      id,
+      value: capability.value
+    };
+  });
+};

package/src/auth/index.ts

@@ -1,3 +1,4 @@
 export * from './auth';
 export * from './oauth';
+export * from './redact';
 export * from './types';

package/src/auth/redact.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import type { SlateAttachment } from '../action/attachment';
+import { AuthConfigSecretRedactor, redactUrlAttachmentSecrets } from './redact';
+
+describe('AuthConfigSecretRedactor', () => {
+  let authConfig = { token: '123SECRET', nested: { token2: 'also_secret' } };
+
+  it('redacts values that match a secret to placeholders', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+
+    expect(
+      redactor.redact({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: 'also_secret' }
+      })
+    ).toEqual({
+      headers: { Authorization: 'Bearer 123SECRET' }, // whole-value match only, not substring
+      query: { key: '$$MT$secret$authConfig$nested.token2' }
+    });
+  });
+
+  it('redacts a bare string value', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact('123SECRET')).toBe('$$MT$secret$authConfig$token');
+  });
+
+  it('leaves non-secret strings untouched', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact('https://example.com/file.pdf')).toBe(
+      'https://example.com/file.pdf'
+    );
+  });
+
+  it('recurses through arrays and nested objects', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact({ list: ['also_secret', 'plain'] })).toEqual({
+      list: ['$$MT$secret$authConfig$nested.token2', 'plain']
+    });
+  });
+
+  it('never registers an empty-string secret', () => {
+    let redactor = new AuthConfigSecretRedactor({ token: '' });
+    expect(redactor.redact({ a: '', b: '' })).toEqual({ a: '', b: '' });
+  });
+
+  it('is a no-op when there is no auth config', () => {
+    let redactor = new AuthConfigSecretRedactor(undefined);
+    expect(redactor.redact({ a: 'b' })).toEqual({ a: 'b' });
+  });
+});
+
+describe('redactUrlAttachmentSecrets', () => {
+  let authConfig = { token: '123SECRET', nested: { token2: 'also_secret' } };
+
+  let urlAttachment = (
+    overrides: Partial<Extract<SlateAttachment['content'], { type: 'url' }>> = {}
+  ): SlateAttachment => ({
+    mimeType: 'application/pdf',
+    content: { type: 'url', url: 'https://example.com/file.pdf', ...overrides }
+  });
+
+  it('redacts headers and query on url attachments', () => {
+    let attachments: SlateAttachment[] = [
+      urlAttachment({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: 'also_secret' }
+      })
+    ];
+
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual([
+      urlAttachment({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: '$$MT$secret$authConfig$nested.token2' }
+      })
+    ]);
+  });
+
+  it('leaves url attachments with no headers/query untouched', () => {
+    let attachments = [urlAttachment()];
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
+  });
+
+  it('leaves content and upload_reference attachments untouched', () => {
+    let attachments: SlateAttachment[] = [
+      {
+        mimeType: 'text/plain',
+        content: { type: 'content', encoding: 'utf-8', content: 'hi' }
+      },
+      { content: { type: 'upload_reference', referenceId: 'ref_1' } }
+    ];
+
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
+  });
+
+  it('is a no-op when there is no auth config', () => {
+    let attachments = [urlAttachment({ headers: { Authorization: 'Bearer 123SECRET' } })];
+    expect(redactUrlAttachmentSecrets(attachments, undefined)).toBe(attachments);
+  });
+
+  it('passes an undefined attachment list through unchanged', () => {
+    expect(redactUrlAttachmentSecrets(undefined, authConfig)).toBeUndefined();
+  });
+});

package/src/auth/redact.ts

@@ -0,0 +1,111 @@
+import type { SlateAttachment } from '../action/attachment';
+
+/**
+ * Placeholder prefix used to mark a redacted auth-config secret. Must match the hub's
+ * AuthConfigSecretSerializer (oss/src/slates/apps/hub/src/lib/secretSerializer.ts) exactly --
+ * the hub resolves these placeholders back to live secret values when it proxies an attachment.
+ */
+export let AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX = '$$MT$secret$authConfig$';
+
+/**
+ * Walks an auth config object and replaces any string value that exactly matches one of its
+ * leaf values with a `$$MT$secret$authConfig$<path>` placeholder. Literal, whole-value
+ * substitution only -- not a substring scan, and not a heuristic key-name/value-shape guess
+ * like the http trace redactor in '../axios/trace'.
+ */
+export class AuthConfigSecretRedactor {
+  private readonly secretToPlaceholder = new Map<string, string>();
+
+  public constructor(authConfig: Record<string, unknown> | undefined) {
+    if (authConfig) this.buildSecretMap(authConfig);
+  }
+
+  public redact<T>(value: T): T {
+    return this.transform(value, stringValue => {
+      return this.secretToPlaceholder.get(stringValue) ?? stringValue;
+    });
+  }
+
+  private buildSecretMap(value: unknown, path: string[] = []): void {
+    if (typeof value === 'string') {
+      // Never register "" -- it would replace every empty header/query value with a placeholder.
+      if (value.length === 0) return;
+
+      this.secretToPlaceholder.set(
+        value,
+        `${AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX}${path.join('.')}`
+      );
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        this.buildSecretMap(item, [...path, String(index)]);
+      });
+
+      return;
+    }
+
+    if (this.isPlainObject(value)) {
+      Object.entries(value).forEach(([key, nestedValue]) => {
+        this.buildSecretMap(nestedValue, [...path, key]);
+      });
+    }
+  }
+
+  private transform<T>(value: T, transformString: (value: string) => string): T {
+    if (typeof value === 'string') {
+      return transformString(value) as T;
+    }
+
+    if (Array.isArray(value)) {
+      return value.map(item => this.transform(item, transformString)) as T;
+    }
+
+    if (this.isPlainObject(value)) {
+      let result: Record<string, unknown> = {};
+
+      Object.entries(value).forEach(([key, nestedValue]) => {
+        result[key] = this.transform(nestedValue, transformString);
+      });
+
+      return result as T;
+    }
+
+    return value;
+  }
+
+  private isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+}
+
+/**
+ * Applied to every finalized attachment list right before it's sent over
+ * `slates/action.tool.invoke` (see @slates/provider-handler). Only `type: 'url'` attachments
+ * carry headers/query -- content/upload_reference attachments pass through untouched.
+ */
+export let redactUrlAttachmentSecrets = (
+  attachments: SlateAttachment[] | undefined,
+  authConfig: Record<string, unknown> | undefined
+): SlateAttachment[] | undefined => {
+  if (!authConfig || !attachments) return attachments;
+
+  let redactor = new AuthConfigSecretRedactor(authConfig);
+
+  return attachments.map(attachment => {
+    if (attachment.content.type !== 'url') return attachment;
+    if (!attachment.content.headers && !attachment.content.query) return attachment;
+
+    return {
+      ...attachment,
+      content: {
+        ...attachment.content,
+        headers: attachment.content.headers
+          ? redactor.redact(attachment.content.headers)
+          : undefined,
+        query: attachment.content.query ? redactor.redact(attachment.content.query) : undefined
+      }
+    };
+  });
+};

package/src/auth/types.ts

@@ -19,7 +19,6 @@ export type SlateAuthWithOauth<
   scopes: {
     title: string;
     description?: string;
-    defaultChecked?: boolean;
     scope: string;
   }[];