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

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,2 +1,3 @@
 export * from './auth';
+export * from './oauth';
 export * from './types';

package/src/auth/oauth.test.ts

@@ -0,0 +1,83 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import type { ApiServiceError } from '../error/api';
+import { getOAuthExpiresAtFromExpiresIn, normalizeOAuthTokenResponse } from './oauth';
+
+describe('OAuth auth helpers', () => {
+  it('converts expires_in seconds to an ISO expiresAt timestamp', () => {
+    expect(getOAuthExpiresAtFromExpiresIn(60, { nowMs: 0 })).toBe('1970-01-01T00:01:00.000Z');
+  });
+
+  it('normalizes token responses and preserves omitted refresh tokens', () => {
+    expect(
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          expires_in: '120'
+        },
+        {
+          nowMs: 0,
+          previousRefreshToken: 'existing-refresh-token'
+        }
+      )
+    ).toEqual({
+      token: 'access-token',
+      refreshToken: 'existing-refresh-token',
+      expiresAt: '1970-01-01T00:02:00.000Z'
+    });
+  });
+
+  it('supports falsy refresh-token fallback semantics', () => {
+    expect(
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          refresh_token: ''
+        },
+        {
+          previousRefreshToken: 'existing-refresh-token',
+          refreshTokenFallbackMode: 'falsy'
+        }
+      ).refreshToken
+    ).toBe('existing-refresh-token');
+  });
+
+  it('throws ServiceError for missing access tokens', () => {
+    let call = () =>
+      normalizeOAuthTokenResponse(
+        {
+          expires_in: 120
+        },
+        {
+          providerLabel: 'Example',
+          operation: 'token exchange'
+        }
+      );
+
+    expect(call).toThrow(ServiceError);
+
+    try {
+      call();
+    } catch (error) {
+      expect(error).toBeInstanceOf(ServiceError);
+      expect((error as ApiServiceError).data.reason).toBe('oauth_token_response');
+    }
+  });
+
+  it('can require a numeric expires_in value', () => {
+    expect(() =>
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          expires_in: '120'
+        },
+        {
+          providerLabel: 'Example',
+          operation: 'token exchange',
+          required: true,
+          expiresInType: 'number'
+        }
+      )
+    ).toThrow(ServiceError);
+  });
+});

package/src/auth/oauth.ts

@@ -0,0 +1,150 @@
+import { createApiServiceError } from '../error/api';
+
+export type OAuthTokenResponse = {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  [key: string]: unknown;
+};
+
+export type OAuthRefreshTokenFallbackMode = 'nullish' | 'falsy';
+
+export type OAuthExpiresAtOptions = {
+  nowMs?: number;
+  providerLabel?: string;
+  operation?: string;
+  required?: boolean;
+  expiresInType?: 'number' | 'numberLike';
+  message?: string;
+};
+
+export type NormalizeOAuthTokenResponseOptions = OAuthExpiresAtOptions & {
+  previousRefreshToken?: string;
+  refreshTokenFallbackMode?: OAuthRefreshTokenFallbackMode;
+  accessTokenMessage?: string;
+  expiresInMessage?: string;
+};
+
+let isOAuthTokenResponse = (value: unknown): value is OAuthTokenResponse =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let formatOAuthTokenResponseMessage = (
+  fieldLabel: string,
+  providerLabel = 'OAuth provider',
+  operation = 'token response'
+) => `${providerLabel} OAuth ${operation} did not return ${fieldLabel}.`;
+
+export let getOAuthExpiresAtFromExpiresIn = (
+  expiresIn: unknown,
+  options: OAuthExpiresAtOptions = {}
+) => {
+  let {
+    nowMs = Date.now(),
+    providerLabel,
+    operation,
+    required = false,
+    expiresInType = 'numberLike',
+    message
+  } = options;
+
+  if (expiresIn === undefined || expiresIn === null || expiresIn === '') {
+    if (required) {
+      throw createApiServiceError(
+        message ??
+          formatOAuthTokenResponseMessage(
+            'a valid expires_in value',
+            providerLabel,
+            operation
+          ),
+        { reason: 'oauth_token_response' }
+      );
+    }
+
+    return undefined;
+  }
+
+  let seconds =
+    typeof expiresIn === 'number'
+      ? expiresIn
+      : expiresInType === 'numberLike' && typeof expiresIn === 'string'
+        ? Number(expiresIn)
+        : Number.NaN;
+
+  if (!Number.isFinite(seconds)) {
+    throw createApiServiceError(
+      message ??
+        formatOAuthTokenResponseMessage('a valid expires_in value', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return new Date(nowMs + seconds * 1000).toISOString();
+};
+
+let getRefreshToken = (
+  refreshToken: unknown,
+  previousRefreshToken: string | undefined,
+  fallbackMode: OAuthRefreshTokenFallbackMode
+) => {
+  if (typeof refreshToken === 'string') {
+    if (fallbackMode === 'falsy' && !refreshToken) {
+      return previousRefreshToken;
+    }
+
+    return refreshToken;
+  }
+
+  if (fallbackMode === 'falsy' && !refreshToken) {
+    return previousRefreshToken;
+  }
+
+  return refreshToken === undefined || refreshToken === null
+    ? previousRefreshToken
+    : undefined;
+};
+
+export let normalizeOAuthTokenResponse = (
+  data: unknown,
+  options: NormalizeOAuthTokenResponseOptions = {}
+) => {
+  let {
+    providerLabel,
+    operation,
+    previousRefreshToken,
+    refreshTokenFallbackMode = 'nullish',
+    accessTokenMessage,
+    expiresInMessage,
+    ...expiresAtOptions
+  } = options;
+
+  if (!isOAuthTokenResponse(data)) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('a token response object', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  if (typeof data.access_token !== 'string' || !data.access_token) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('an access token', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return {
+    token: data.access_token,
+    refreshToken: getRefreshToken(
+      data.refresh_token,
+      previousRefreshToken,
+      refreshTokenFallbackMode
+    ),
+    expiresAt: getOAuthExpiresAtFromExpiresIn(data.expires_in, {
+      ...expiresAtOptions,
+      providerLabel,
+      operation,
+      message: expiresInMessage
+    })
+  };
+};