@slates/provider-handler 1.0.0-rc.4 → 1.0.0-rc.41

package/src/pQueue.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { resolveDefaultExport } from './pQueue';
+
+class Example {
+  value: number;
+  constructor(value: number) {
+    this.value = value;
+  }
+}
+
+describe('resolveDefaultExport', () => {
+  it('unwraps nested CJS default exports from bundlers', () => {
+    expect(resolveDefaultExport<typeof Example>({ default: { default: Example } })).toBe(
+      Example
+    );
+    expect(new (resolveDefaultExport<typeof Example>({ default: Example }))(3).value).toBe(3);
+  });
+});

package/src/pQueue.ts

@@ -0,0 +1,18 @@
+import PQueueImport from 'p-queue';
+
+export let resolveDefaultExport = <T>(value: unknown): T => {
+  let current = value;
+
+  for (let i = 0; i < 4; i++) {
+    if (typeof current === 'function') return current as T;
+    if (current && typeof current === 'object' && 'default' in current) {
+      current = (current as { default: unknown }).default;
+      continue;
+    }
+    break;
+  }
+
+  throw new TypeError('Module export is not a constructor');
+};
+
+export let PQueue = resolveDefaultExport<typeof PQueueImport>(PQueueImport);

package/src/spec.test.ts

@@ -0,0 +1,232 @@
+import { isServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  getExposedAction,
+  getExposedActions,
+  getExposedToolCategories,
+  getExposedTriggerGroups,
+  getMappableAction,
+  getTriggersForGroup,
+  isMappableTrigger,
+  mapAction,
+  mapAdapter,
+  mapAuthMethod,
+  mapToolCategory
+} from './spec';
+
+let baseAction = {
+  key: 'do_thing',
+  name: 'Do Thing',
+  description: 'desc',
+  instructions: undefined,
+  constraints: undefined,
+  tags: [],
+  metadata: {},
+  scopes: [],
+  authMethods: [],
+  docs: [],
+  adapter: undefined,
+  inputSchema: z.object({}),
+  outputSchema: z.object({})
+};
+
+let toolAction: any = { ...baseAction, type: 'tool', isPublic: false };
+
+let validTriggerGroup = { key: 'my_group', name: 'My Group' };
+let validTrigger: any = {
+  ...baseAction,
+  type: 'trigger',
+  triggerGroup: validTriggerGroup,
+  matches: () => true,
+  map: () => ({})
+};
+
+let incompatibleTrigger: any = { ...baseAction, type: 'trigger', triggerGroup: undefined };
+
+describe('isMappableTrigger', () => {
+  it('is true for tool actions', () => {
+    expect(isMappableTrigger(toolAction)).toBe(true);
+  });
+
+  it('is true for triggers with a trigger group', () => {
+    expect(isMappableTrigger(validTrigger)).toBe(true);
+  });
+
+  it('is false for triggers missing a trigger group', () => {
+    expect(isMappableTrigger(incompatibleTrigger)).toBe(false);
+  });
+});
+
+describe('mapAction', () => {
+  it('maps a well-formed trigger', () => {
+    let mapped = mapAction({} as any, validTrigger);
+    expect(mapped).toMatchObject({ type: 'action.trigger', triggerGroupId: 'my_group' });
+  });
+
+  it('includes the tool categories a tool belongs to', () => {
+    let slate = { getToolCategoryKeys: () => ['crm', 'reporting'] } as any;
+
+    expect(mapAction(slate, toolAction)).toMatchObject({
+      type: 'action.tool',
+      toolCategoryIds: ['crm', 'reporting']
+    });
+  });
+
+  it('omits categories for tools without any, including on slates that predate them', () => {
+    expect(mapAction({ getToolCategoryKeys: () => [] } as any, toolAction)).not.toHaveProperty(
+      'toolCategoryIds'
+    );
+    expect(mapAction({} as any, toolAction)).not.toHaveProperty('toolCategoryIds');
+  });
+});
+
+describe('mapToolCategory', () => {
+  it('maps the category key to the protocol id', () => {
+    expect(
+      mapToolCategory({ key: 'crm', name: 'CRM', description: 'Records' } as any)
+    ).toEqual({ id: 'crm', name: 'CRM', description: 'Records', imageUrl: undefined });
+  });
+
+  it('includes the category image when one is set', () => {
+    expect(
+      mapToolCategory({ key: 'crm', name: 'CRM', imageUrl: 'https://cdn.test/crm.svg' } as any)
+    ).toMatchObject({ id: 'crm', imageUrl: 'https://cdn.test/crm.svg' });
+  });
+});
+
+describe('getTriggersForGroup', () => {
+  it('filters out triggers missing a trigger group instead of throwing', () => {
+    let slate = { actions: [toolAction, validTrigger, incompatibleTrigger] } as any;
+
+    expect(getTriggersForGroup(slate, 'my_group')).toEqual([validTrigger]);
+    expect(getTriggersForGroup(slate, 'other_group')).toEqual([]);
+  });
+});
+
+describe('getMappableAction', () => {
+  it('returns tool and well-formed trigger actions', () => {
+    let slate = { actions: [toolAction, validTrigger] } as any;
+
+    expect(getMappableAction(slate, 'do_thing')).toBe(toolAction);
+  });
+
+  it('treats a trigger missing its group as not found instead of crashing', () => {
+    let slate = { actions: [incompatibleTrigger] } as any;
+
+    try {
+      getMappableAction(slate, 'do_thing');
+      expect.unreachable();
+    } catch (e) {
+      expect(isServiceError(e)).toBe(true);
+      expect((e as any).data.status).toBe(404);
+    }
+  });
+});
+
+describe('adapter exposure', () => {
+  let providerTool: any = { ...toolAction, key: 'provider_tool' };
+  let adapterTool: any = { ...toolAction, key: 'adapter_tool', adapter: 'chat' };
+  let providerGroup = { key: 'provider_group', name: 'Provider Group' };
+  let adapterGroup = { key: 'adapter_group', name: 'Adapter Group' };
+  let emptyGroup = { key: 'empty_group', name: 'Empty Group' };
+  let providerTrigger: any = {
+    ...validTrigger,
+    key: 'provider_trigger',
+    triggerGroup: providerGroup
+  };
+  let adapterTrigger: any = {
+    ...validTrigger,
+    key: 'adapter_trigger',
+    adapter: 'chat',
+    triggerGroup: adapterGroup
+  };
+  let slate = {
+    actions: [providerTool, adapterTool, providerTrigger, adapterTrigger],
+    triggerGroups: [providerGroup, adapterGroup, emptyGroup]
+  } as any;
+
+  it('only exposes adapter actions when adapters are enabled', () => {
+    expect(getExposedActions(slate, false)).toEqual([providerTool, providerTrigger]);
+    expect(getExposedActions(slate, true)).toEqual([
+      providerTool,
+      adapterTool,
+      providerTrigger,
+      adapterTrigger
+    ]);
+  });
+
+  it('does not expose an adapter action directly when adapters are disabled', () => {
+    expect(() => getExposedAction(slate, 'adapter_tool', false)).toThrow();
+    expect(getExposedAction(slate, 'adapter_tool', true)).toBe(adapterTool);
+  });
+
+  it('only exposes tool categories that contain an exposed tool', () => {
+    let providerCategory = { key: 'provider_category', name: 'Provider' };
+    let adapterCategory = { key: 'adapter_category', name: 'Adapter' };
+    let emptyCategory = { key: 'empty_category', name: 'Empty' };
+    let categorizedSlate = {
+      ...slate,
+      toolCategories: [providerCategory, adapterCategory, emptyCategory],
+      getToolCategoryKeys: (key: string) =>
+        key === 'provider_tool'
+          ? ['provider_category']
+          : key === 'adapter_tool'
+            ? ['adapter_category']
+            : []
+    } as any;
+
+    expect(getExposedToolCategories(categorizedSlate, false)).toEqual([providerCategory]);
+    expect(getExposedToolCategories(categorizedSlate, true)).toEqual([
+      providerCategory,
+      adapterCategory
+    ]);
+    expect(getExposedToolCategories(slate, true)).toEqual([]);
+  });
+
+  it('only exposes trigger groups that contain an exposed trigger', () => {
+    expect(getExposedTriggerGroups(slate, false)).toEqual([providerGroup]);
+    expect(getExposedTriggerGroups(slate, true)).toEqual([providerGroup, adapterGroup]);
+  });
+
+  it('treats missing adapters and trigger groups as empty collections', () => {
+    let legacySlate = { actions: [providerTool, providerTrigger] } as any;
+
+    expect(getExposedActions(legacySlate, true)).toEqual([providerTool, providerTrigger]);
+    expect(getExposedTriggerGroups(legacySlate, true)).toEqual([]);
+    expect(mapAdapter({ id: 'chat', name: 'Chat' } as any)).toEqual({
+      id: 'chat',
+      name: 'Chat',
+      capabilities: []
+    });
+  });
+});
+
+describe('mapAuthMethod', () => {
+  let slate: any = { spec: { auth: { outputSchema: z.object({ token: z.string() }) } } };
+  let oauthMethod: any = {
+    type: 'auth.oauth',
+    key: 'oauth',
+    name: 'OAuth',
+    scopes: [],
+    getAuthorizationUrl: async () => ({ url: '' }),
+    handleCallback: async () => ({ output: { token: '' } })
+  };
+
+  it('emits syncTokensAcrossConnections only when the method opts in', () => {
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, syncTokensAcrossConnections: true })
+    ).toMatchObject({ syncTokensAcrossConnections: true });
+
+    for (let method of [oauthMethod, { ...oauthMethod, syncTokensAcrossConnections: false }]) {
+      expect(mapAuthMethod(slate, method)).not.toHaveProperty('syncTokensAcrossConnections');
+    }
+  });
+
+  it('omits the adminSetup capability when undeclared so existing spec hashes stay stable', () => {
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, adminSetup: {} }).capabilities
+    ).toMatchObject({ adminSetup: { enabled: true } });
+    expect(mapAuthMethod(slate, oauthMethod).capabilities).not.toHaveProperty('adminSetup');
+  });
+});

package/src/spec.ts

@@ -1,6 +1,18 @@
 import { badRequestError, notFoundError, ServiceError } from '@lowerdeck/error';
-import { SlateAuthenticationMethod, SlatesAction } from '@slates/proto';
-import { Slate, SlateDefaultPollingIntervalSeconds } from '@slates/provider';
+import type {
+  SlateAuthenticationMethod,
+  SlatesAction,
+  SlateAdapter as SlatesAdapter,
+  SlatesToolCategory,
+  SlatesTriggerGroup
+} from '@slates/proto';
+import {
+  type Slate,
+  type SlateAdapter,
+  SlateDefaultPollingIntervalSeconds,
+  type SlateToolCategory,
+  type SlateTrigger
+} from '@slates/provider';
 import z from 'zod';
 import { toJsonSchema } from './validation';
 
@@ -8,7 +20,7 @@ export let getAuthMethod = <ConfigType extends {}, AuthType extends {}>(
   slate: Slate<ConfigType, AuthType>,
   authenticationMethodId: string
 ) => {
-  let authMethod = slate.spec.auth.authStack.find(m => m.key == authenticationMethodId);
+  let authMethod = slate.spec.auth.authStack.find(m => m.key === authenticationMethodId);
   if (!authMethod) {
     throw new ServiceError(
       badRequestError({
@@ -37,6 +49,12 @@ export let mapAuthMethod = <ConfigType extends {}, AuthType extends {}>(
         }))
       : undefined,
 
+  adapters: 'adapters' in m ? m.adapters : undefined,
+
+  ...('syncTokensAcrossConnections' in m && m.syncTokensAcrossConnections
+    ? { syncTokensAcrossConnections: true }
+    : {}),
+
   inputSchema: toJsonSchema(m.inputSchema ?? z.object({})),
   outputSchema: toJsonSchema(slate.spec.auth.outputSchema),
 
@@ -48,15 +66,18 @@ export let mapAuthMethod = <ConfigType extends {}, AuthType extends {}>(
     handleChangedInput: {
       enabled: !!m.onInputChanged
     },
-    getProfile: { enabled: !!m.getProfile }
-  }
+    getProfile: { enabled: !!m.getProfile },
+    ...('adminSetup' in m && m.adminSetup ? { adminSetup: { enabled: true } } : {})
+  },
+
+  docs: m.docs ?? []
 });
 
 export let getAction = <ConfigType extends {}, AuthType extends {}>(
   slate: Slate<ConfigType, AuthType>,
   actionId: string
 ) => {
-  let action = slate.actions.find(m => m.key == actionId);
+  let action = (slate.actions ?? []).find(m => m.key === actionId);
   if (!action) {
     throw new ServiceError(notFoundError(`action`, actionId));
   }
@@ -64,6 +85,26 @@ export let getAction = <ConfigType extends {}, AuthType extends {}>(
   return action;
 };
 
+export let getAdapter = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  adapterId: string
+) => {
+  let adapter = (slate.adapters ?? []).find(m => m.id === adapterId);
+  if (!adapter) {
+    throw new ServiceError(notFoundError(`adapter`, adapterId));
+  }
+
+  return adapter;
+};
+
+export let mapAdapter = <ConfigType extends {}, AuthType extends {}>(
+  adapter: SlateAdapter<ConfigType, AuthType>
+): SlatesAdapter => ({
+  id: adapter.id,
+  name: adapter.name,
+  capabilities: adapter.capabilities ?? []
+});
+
 export let getActionWithType = <
   Type extends 'tool' | 'trigger',
   ConfigType extends {},
@@ -74,7 +115,7 @@ export let getActionWithType = <
   actionId: string
 ): ReturnType<typeof getAction<ConfigType, AuthType>> & { type: Type } => {
   let action = getAction(slate, actionId);
-  if (action.type != type) {
+  if (action.type !== type) {
     throw new ServiceError(
       badRequestError({
         message: `Action with ID ${actionId} is not of type ${type}`
@@ -97,16 +138,24 @@ export let mapAction = <ConfigType extends {}, AuthType extends {}>(
     constraints: a.constraints,
     tags: a.tags,
     metadata: a.metadata,
+    scopes: a.scopes,
+    authMethods: a.authMethods,
+    docs: a.docs ?? [],
+    ...(a.adapter ? { adapter: a.adapter } : {}),
 
     inputSchema: toJsonSchema(a.inputSchema),
     outputSchema: toJsonSchema(a.outputSchema)
   };
 
-  if (a.type == 'tool') {
+  if (a.type === 'tool') {
+    let toolCategoryIds = slate.getToolCategoryKeys?.(a.key) ?? [];
+
     return {
       ...base,
       type: 'action.tool',
-      capabilities: {}
+      capabilities: {},
+      isPublic: a.isPublic,
+      ...(toolCategoryIds.length ? { toolCategoryIds } : {})
     };
   }
 
@@ -114,17 +163,168 @@ export let mapAction = <ConfigType extends {}, AuthType extends {}>(
     ...base,
     type: 'action.trigger',
     capabilities: {},
+    triggerGroupId: a.triggerGroup.key
+  };
+};
 
-    invocation:
-      a.source == 'polling'
-        ? {
-            type: 'polling',
-            intervalSeconds: a.polling.intervalInSeconds ?? SlateDefaultPollingIntervalSeconds
-          }
+export let isMappableTrigger = <ConfigType extends {}, AuthType extends {}>(
+  action: Slate<ConfigType, AuthType>['actions'][number]
+): boolean => action.type !== 'trigger' || !!action.triggerGroup;
+
+export let getMappableAction = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  actionId: string
+) => {
+  let action = getAction(slate, actionId);
+  if (!isMappableTrigger(action)) {
+    throw new ServiceError(notFoundError(`action`, actionId));
+  }
+
+  return action;
+};
+
+export let getExposedActions = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  includeAdapterActions: boolean
+) =>
+  (slate.actions ?? []).filter(
+    action => isMappableTrigger(action) && (includeAdapterActions || !action.adapter)
+  );
+
+export let getExposedAction = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  actionId: string,
+  includeAdapterActions: boolean
+) => {
+  let action = getMappableAction(slate, actionId);
+  if (action.adapter && !includeAdapterActions) {
+    throw new ServiceError(notFoundError(`action`, actionId));
+  }
+
+  return action;
+};
+
+export let getTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  triggerGroupId: string
+) => {
+  let group = (slate.triggerGroups ?? []).find(g => g.key === triggerGroupId);
+  if (!group) {
+    throw new ServiceError(notFoundError(`trigger_group`, triggerGroupId));
+  }
+
+  return group;
+};
+
+export let getTriggersForGroup = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  triggerGroupId: string
+): SlateTrigger<ConfigType, AuthType, any, any>[] =>
+  (slate.actions ?? []).filter(
+    (action): action is SlateTrigger<ConfigType, AuthType, any, any> =>
+      action.type === 'trigger' && action.triggerGroup?.key === triggerGroupId
+  );
+
+export let getExposedTriggerGroups = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  includeAdapterActions: boolean
+) => {
+  let triggerGroupIds = new Set(
+    getExposedActions(slate, includeAdapterActions).flatMap(action =>
+      action.type === 'trigger' && action.triggerGroup ? [action.triggerGroup.key] : []
+    )
+  );
+
+  return (slate.triggerGroups ?? []).filter(group => triggerGroupIds.has(group.key));
+};
+
+export let evaluateTriggerMatches = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  triggerGroupId: string,
+  payload: unknown
+): string[] =>
+  getTriggersForGroup(slate, triggerGroupId)
+    .filter(trigger => trigger.matches(payload))
+    .map(trigger => trigger.key);
+
+export let getWebhookAutoRegistration = <ConfigType extends {}, AuthType extends {}>(
+  group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
+) => {
+  if (group.source !== 'webhook' || !group.webhook?.autoRegistration) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Trigger group does not support webhook auto-registration: ${group.key}`
+      })
+    );
+  }
+
+  return group.webhook.autoRegistration;
+};
+
+export let getWebhookManualRegistration = <ConfigType extends {}, AuthType extends {}>(
+  group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
+) => {
+  if (group.source !== 'webhook' || !group.webhook?.manualRegistration) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Trigger group does not support manual webhook registration: ${group.key}`
+      })
+    );
+  }
+
+  return group.webhook.manualRegistration;
+};
+
+export let mapToolCategory = (category: SlateToolCategory): SlatesToolCategory => ({
+  id: category.key,
+  name: category.name,
+  description: category.description,
+  imageUrl: category.imageUrl
+});
+
+// Like trigger groups, a category is only listed when the hub can see one of its tools.
+export let getExposedToolCategories = <ConfigType extends {}, AuthType extends {}>(
+  slate: Slate<ConfigType, AuthType>,
+  includeAdapterActions: boolean
+) => {
+  let exposedCategoryKeys = new Set(
+    getExposedActions(slate, includeAdapterActions)
+      .filter(action => action.type === 'tool')
+      .flatMap(action => slate.getToolCategoryKeys?.(action.key) ?? [])
+  );
+
+  return (slate.toolCategories ?? []).filter(category =>
+    exposedCategoryKeys.has(category.key)
+  );
+};
+
+export let mapTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
+  group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
+): SlatesTriggerGroup => ({
+  id: group.key,
+  name: group.name,
+  description: group.description,
+  metadata: group.metadata,
+  invocation:
+    group.source === 'polling'
+      ? {
+          type: 'polling',
+          intervalSeconds: group.polling?.intervalSeconds ?? SlateDefaultPollingIntervalSeconds
+        }
+      : group.source === 'gateway'
+        ? { type: 'gateway' }
         : {
             type: 'webhook',
-            autoRegistration: !!a.autoRegisterWebhook,
-            autoUnregistration: !!a.autoUnregisterWebhook
+            registration: group.webhook?.manualRegistration
+              ? {
+                  mode: 'manual',
+                  userConfigSchema: toJsonSchema(
+                    group.webhook.manualRegistration.userConfigSchema
+                  ),
+                  fullConfigSchema: toJsonSchema(
+                    group.webhook.manualRegistration.fullConfigSchema
+                  )
+                }
+              : { mode: 'auto' }
           }
-  };
-};
+});

package/src/validation.ts

@@ -1,5 +1,5 @@
 import { ServiceError, validationError } from '@lowerdeck/error';
-import z from 'zod';
+import type z from 'zod';
 
 export let zodToValidationError = (entity: string, message: string, e: z.ZodError) => {
   return validationError({

package/src/webhook.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import {
+  SLATE_WEBHOOK_RESPONSE_MAX_BODY_BYTES,
+  serializeWebhookHttpResponse
+} from './webhook';
+
+describe('serializeWebhookHttpResponse', () => {
+  it('serializes a Response with status, headers, and body', async () => {
+    await expect(
+      serializeWebhookHttpResponse(
+        new Response('created', {
+          status: 201,
+          headers: {
+            'content-type': 'text/plain',
+            'x-webhook-result': 'accepted'
+          }
+        })
+      )
+    ).resolves.toEqual({
+      status: 201,
+      headers: {
+        'content-type': 'text/plain',
+        'x-webhook-result': 'accepted'
+      },
+      body: {
+        encoding: 'base64',
+        content: Buffer.from('created').toString('base64')
+      }
+    });
+  });
+
+  it('applies defaults to a plain response init', async () => {
+    await expect(serializeWebhookHttpResponse({ body: 'ok' })).resolves.toEqual({
+      status: 200,
+      headers: {},
+      body: {
+        encoding: 'base64',
+        content: Buffer.from('ok').toString('base64')
+      }
+    });
+  });
+
+  it('serializes binary response bodies without changing their bytes', async () => {
+    await expect(
+      serializeWebhookHttpResponse({
+        status: 202,
+        body: new Uint8Array([0, 127, 128, 255])
+      })
+    ).resolves.toMatchObject({
+      status: 202,
+      body: {
+        encoding: 'base64',
+        content: Buffer.from([0, 127, 128, 255]).toString('base64')
+      }
+    });
+  });
+
+  it('rejects bodies larger than one MiB', async () => {
+    await expect(
+      serializeWebhookHttpResponse({
+        body: new Uint8Array(SLATE_WEBHOOK_RESPONSE_MAX_BODY_BYTES + 1)
+      })
+    ).rejects.toThrow('Webhook response body exceeds');
+  });
+});