@slates/provider-handler 1.0.0-rc.43 → 1.0.0-rc.44

package/src/index.ts

@@ -9,8 +9,12 @@ import {
   SLATES_PROTOCOL_VERSION,
   type SlatesMessageAuthAdminCallbackHandleRequest,
   type SlatesMessageAuthAuthorizationUrlGetRequest,
+  type SlatesMessageTriggerGroupWebhookProcessRequest,
   type SlatesParticipant,
-  type SlatesRuntimeInfo
+  type SlatesRuntimeInfo,
+  slatesTriggerGroupWebhookDeliveryAuthentication,
+  slatesTriggerGroupWebhookExpansionResult,
+  slatesTriggerGroupWebhookRegistrationResult
 } from '@slates/proto';
 import {
   AuthConfigSecretRedactor,
@@ -24,6 +28,7 @@ import {
   type SlateLogListener,
   SlatePublicContext,
   type SlateRuntimeInfo,
+  type SlateTriggerGroup,
   uploadAttachmentDirect
 } from '@slates/provider';
 import { PQueue } from './pQueue';
@@ -38,6 +43,7 @@ import {
   getExposedTriggerGroups,
   getTriggerGroup,
   getWebhookAutoRegistration,
+  getWebhookDeliveryConfig,
   getWebhookManualRegistration,
   isMappableTrigger,
   mapAction,
@@ -52,6 +58,39 @@ import { serializeWebhookHttpResponse } from './webhook';
 
 let DEFAULT_MAX_ATTACHMENT_SIZE_BYTES = 100_000_000;
 
+let validateTriggerGroupSelection = (
+  group: SlateTriggerGroup<any, any>,
+  selection: Record<string, any> | undefined
+) =>
+  group.selectionSchema
+    ? validate(
+        group.selectionSchema,
+        selection === undefined ? {} : selection,
+        'trigger_group.selection',
+        `Invalid selection for trigger group "${group.key}"`
+      )
+    : (selection ?? {});
+
+let validateWebhookRegistration = (result: unknown) =>
+  validate(
+    slatesTriggerGroupWebhookRegistrationResult,
+    result,
+    'trigger_group.webhook.registration',
+    'Webhook registration returned an invalid result'
+  );
+
+let toWebhookRequest = (
+  params: Pick<
+    SlatesMessageTriggerGroupWebhookProcessRequest['params'],
+    'url' | 'method' | 'headers' | 'body'
+  >
+) =>
+  new Request(params.url, {
+    method: params.method,
+    headers: params.headers,
+    body: params.body ? Uint8Array.from(atob(params.body.content), c => c.charCodeAt(0)) : null
+  });
+
 let routeAttachmentsThroughDirectUpload = async (
   attachments: SlateAttachment[] | undefined,
   live: SlateLiveInvocationInfo | null
@@ -1278,7 +1317,10 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
 
       let context = createContext(
         ctx.config,
-        { pageToken: params.pageToken ?? null },
+        {
+          pageToken: params.pageToken ?? null,
+          selection: validateTriggerGroupSelection(group, params.selection)
+        },
         ctx.auth?.output!
       );
       let res = await traceProviderCall(
@@ -1318,7 +1360,10 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
         {
           webhookTargetIdentifier: params.webhookTargetIdentifier,
           webhookTargetPayload: params.webhookTargetPayload,
-          webhookUrl: params.webhookUrl
+          webhookUrl: params.webhookUrl,
+          operationId: params.operationId,
+          selection: validateTriggerGroupSelection(group, params.selection),
+          deliveryConfig: params.deliveryConfig
         },
         ctx.auth?.output!
       );
@@ -1335,13 +1380,58 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
             webhookTargetIdentifier: params.webhookTargetIdentifier
           }
         },
-        () => runWithContext(context, () => autoRegistration.webhookRegister(context))
+        () =>
+          runWithContext(context, async () =>
+            validateWebhookRegistration(await autoRegistration.webhookRegister(context))
+          )
       );
 
-      return withRequestTraces(context, {
-        webhookRegistrationIdentifier: res.webhookRegistrationIdentifier,
-        webhookRegistrationPayload: res.webhookRegistrationPayload
-      });
+      return withRequestTraces(context, res);
+    });
+
+    manager.onRequest('slates/trigger_group.webhook.renew', async ({ params }) => {
+      let ctx = getContextFull();
+      let group = getTriggerGroup(slate, params.triggerGroupId);
+      let autoRegistration = getWebhookAutoRegistration(group);
+      let renew = autoRegistration.webhookRenew;
+      if (!renew) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger group does not support webhook renewal: ${params.triggerGroupId}`
+          })
+        );
+      }
+
+      let context = createContext(
+        ctx.config,
+        {
+          webhookRegistrationIdentifier: params.webhookRegistrationIdentifier,
+          webhookRegistrationPayload: params.webhookRegistrationPayload,
+          webhookUrl: params.webhookUrl,
+          webhookTargetIdentifier: params.webhookTargetIdentifier,
+          webhookTargetPayload: params.webhookTargetPayload,
+          operationId: params.operationId,
+          selection: validateTriggerGroupSelection(group, params.selection),
+          deliveryConfig: params.deliveryConfig
+        },
+        ctx.auth?.output!
+      );
+      let res = await traceProviderCall(
+        {
+          component: 'action',
+          functionName: 'webhookRenew',
+          message: `Renewing webhook for trigger group ${formatEntityLabel(group.name, group.key)}`,
+          successMessage: `Renewed webhook for trigger group ${formatEntityLabel(group.name, group.key)}`,
+          errorMessage: `Trigger group ${formatEntityLabel(group.name, group.key)} failed while renewing a webhook`,
+          metadata: { triggerGroupId: group.key, triggerGroupName: group.name }
+        },
+        () =>
+          runWithContext(context, async () =>
+            validateWebhookRegistration(await renew(context))
+          )
+      );
+
+      return withRequestTraces(context, res);
     });
 
     manager.onRequest('slates/trigger_group.webhook.unregister', async ({ params }) => {
@@ -1455,18 +1545,10 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
         );
       }
 
-      let req = new Request(params.url, {
-        method: params.method,
-        headers: params.headers,
-        body: params.body
-          ? Uint8Array.from(atob(params.body.content), c => c.charCodeAt(0))
-          : null
-      });
-
       let context = createContext(
         {},
         {
-          request: req,
+          request: toWebhookRequest(params),
           webhookRegistrationPayload: params.webhookRegistrationPayload
         },
         {}
@@ -1514,13 +1596,121 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
           matchers: event.matchers,
           payload: event.payload,
           idempotencyKey: event.idempotencyKey,
-          triggerIds: evaluateTriggerMatches(slate, group.key, event.payload)
+          triggerIds: group.webhook?.expandWebhook
+            ? []
+            : evaluateTriggerMatches(slate, group.key, event.payload)
         })),
+        ...(group.webhook?.expandWebhook ? { requiresExpansion: true } : {}),
         response,
         skipped: res.skipped ?? null
       });
     });
 
+    manager.onRequest(
+      'slates/trigger_group.webhook.delivery_authenticate',
+      async ({ params }) => {
+        let group = getTriggerGroup(slate, params.triggerGroupId);
+        let deliveryConfig = getWebhookDeliveryConfig(group);
+
+        let context = createContext(
+          {},
+          {
+            request: toWebhookRequest(params),
+            deliveryConfig: params.deliveryConfig
+          },
+          {}
+        );
+        let res = await traceProviderCall(
+          {
+            component: 'action',
+            functionName: 'webhookDeliveryAuthenticate',
+            message: `Authenticating a delivery for trigger group ${formatEntityLabel(group.name, group.key)}`,
+            successMessage: result =>
+              result.rejected
+                ? `Rejected a delivery with status ${result.rejected.status} for trigger group ${formatEntityLabel(group.name, group.key)}`
+                : `Authenticated a delivery for ${result.routingKeys.length} routing key(s) for trigger group ${formatEntityLabel(group.name, group.key)}`,
+            errorMessage: `Trigger group ${formatEntityLabel(group.name, group.key)} failed while authenticating a delivery`,
+            metadata: {
+              triggerGroupId: group.key,
+              triggerGroupName: group.name,
+              requestMethod: params.method,
+              hasRequestBody: !!params.body
+            },
+            onSuccess: result => ({
+              routingKeyCount: result.routingKeys.length,
+              rejectedStatus: result.rejected?.status ?? null
+            })
+          },
+          () =>
+            runWithContext(context, async () => {
+              let authentication = await deliveryConfig.authenticate(context);
+              return validate(
+                slatesTriggerGroupWebhookDeliveryAuthentication,
+                authentication.rejected
+                  ? { routingKeys: [], rejected: authentication.rejected }
+                  : { routingKeys: authentication.routingKeys, rejected: null },
+                'trigger_group.webhook.delivery_authentication',
+                'Webhook delivery authentication returned an invalid result'
+              );
+            })
+        );
+
+        return withRequestTraces(context, res);
+      }
+    );
+
+    manager.onRequest('slates/trigger_group.webhook.expand', async ({ params }) => {
+      let ctx = getContextFull();
+      let group = getTriggerGroup(slate, params.triggerGroupId);
+      let expand = group.source === 'webhook' ? group.webhook?.expandWebhook : undefined;
+      if (!expand) {
+        throw new ServiceError(
+          badRequestError({
+            message: `Trigger group does not support webhook expansion: ${params.triggerGroupId}`
+          })
+        );
+      }
+
+      let context = createContext(
+        ctx.config,
+        {
+          payload: params.payload,
+          state: params.state ?? null,
+          selection: validateTriggerGroupSelection(group, params.selection),
+          deliveryId: params.deliveryId,
+          webhookRegistrationPayload: params.webhookRegistrationPayload
+        },
+        ctx.auth?.output!
+      );
+      let res = await traceProviderCall(
+        {
+          component: 'action',
+          functionName: 'expandWebhook',
+          message: `Expanding webhook delivery for trigger group ${formatEntityLabel(group.name, group.key)}`,
+          successMessage: `Expanded webhook delivery for trigger group ${formatEntityLabel(group.name, group.key)}`,
+          errorMessage: `Trigger group ${formatEntityLabel(group.name, group.key)} failed while expanding a webhook delivery`,
+          metadata: { triggerGroupId: group.key, triggerGroupName: group.name }
+        },
+        () =>
+          runWithContext(context, async () =>
+            validate(
+              slatesTriggerGroupWebhookExpansionResult,
+              await expand(context),
+              'trigger_group.webhook.expansion',
+              'Webhook expansion returned an invalid result'
+            )
+          )
+      );
+
+      return withRequestTraces(context, {
+        ...(res.updatedState !== undefined ? { updatedState: res.updatedState } : {}),
+        events: res.events.map(event => ({
+          ...event,
+          triggerIds: evaluateTriggerMatches(slate, group.key, event.payload)
+        }))
+      });
+    });
+
     manager.onRequest('slates/trigger_group.routing_matchers.get', async ({ params }) => {
       let ctx = getContextFull();
       let group = getTriggerGroup(slate, params.triggerGroupId);
@@ -1559,7 +1749,14 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
         );
       }
 
-      let context = createContext(ctx.config, { state: params.state }, ctx.auth?.output!);
+      let context = createContext(
+        ctx.config,
+        {
+          state: params.state,
+          selection: validateTriggerGroupSelection(group, params.selection)
+        },
+        ctx.auth?.output!
+      );
       let res = await traceProviderCall(
         {
           component: 'action',

package/src/spec.test.ts

@@ -1,4 +1,5 @@
 import { isServiceError } from '@lowerdeck/error';
+import { slatesTriggerGroup } from '@slates/proto';
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
 import {
@@ -8,11 +9,14 @@ import {
   getExposedTriggerGroups,
   getMappableAction,
   getTriggersForGroup,
+  getWebhookDeliveryConfig,
+  getWebhookManualRegistration,
   isMappableTrigger,
   mapAction,
   mapAdapter,
   mapAuthMethod,
-  mapToolCategory
+  mapToolCategory,
+  mapTriggerGroup
 } from './spec';
 
 let baseAction = {
@@ -202,6 +206,92 @@ describe('adapter exposure', () => {
   });
 });
 
+describe('webhook registration config', () => {
+  let config = {
+    userConfigSchema: z.object({ secret: z.string().describe('Signing secret') }),
+    fullConfigSchema: z.object({ secret: z.string(), endpoint: z.string() }),
+    setup: async () => ({ webhookSetupDocument: '', partialWebhookRegistrationPayload: {} }),
+    finish: async () => ({ webhookRegistrationPayload: {} }),
+    authenticate: async () => ({ routingKeys: [] })
+  };
+  let schemas = {
+    userConfigSchema: {
+      type: 'object',
+      properties: { secret: { type: 'string', description: 'Signing secret' } },
+      required: ['secret']
+    },
+    fullConfigSchema: {
+      type: 'object',
+      properties: { secret: { type: 'string' }, endpoint: { type: 'string' } },
+      required: ['secret', 'endpoint']
+    }
+  };
+  let autoRegistration = {
+    webhookTargetList: async () => ({ targets: [], nextPageToken: null }),
+    webhookRegister: async () => ({
+      webhookRegistrationIdentifier: 'reg',
+      webhookRegistrationPayload: {}
+    }),
+    webhookUnregister: async () => {}
+  };
+  let group = (webhook: Record<string, unknown>): any => ({
+    key: 'group',
+    name: 'Group',
+    source: 'webhook',
+    webhook: { process: async () => ({ events: [] }), ...webhook }
+  });
+  let auto = group({ autoRegistration });
+  let manual = group({ manualRegistration: config });
+  let configured = group({ autoRegistration, deliveryConfig: config });
+
+  it('keeps plain automatic and manual groups serialised as before', () => {
+    expect(mapTriggerGroup(auto).invocation).toEqual({
+      type: 'webhook',
+      registration: { mode: 'auto' }
+    });
+    expect(mapTriggerGroup(manual).invocation).toMatchObject({
+      type: 'webhook',
+      registration: { mode: 'manual', ...schemas }
+    });
+    expect(
+      Object.keys((mapTriggerGroup(manual).invocation as any).registration).sort()
+    ).toEqual(['fullConfigSchema', 'mode', 'userConfigSchema']);
+  });
+
+  it('advertises the delivery config of an automatic group', () => {
+    let mapped = mapTriggerGroup(configured);
+    expect(mapped.invocation).toMatchObject({
+      type: 'webhook',
+      registration: { mode: 'auto', deliveryConfig: schemas }
+    });
+    expect(slatesTriggerGroup.parse(mapped).invocation).toEqual(mapped.invocation);
+  });
+
+  it('authenticates deliveries only for automatic groups with a delivery config', () => {
+    expect(getWebhookDeliveryConfig(configured)).toBe(config);
+    for (let unsupported of [
+      auto,
+      manual,
+      { key: 'group', name: 'Group', source: 'polling' } as any
+    ]) {
+      expect(() => getWebhookDeliveryConfig(unsupported)).toThrow(
+        'Trigger group does not support webhook delivery authentication: group'
+      );
+    }
+  });
+
+  it('serves setup and finish for manual groups and automatic groups with a delivery config', () => {
+    expect(getWebhookManualRegistration(manual)).toBe(config);
+    expect(getWebhookManualRegistration(configured)).toBe(config);
+    expect(() => getWebhookManualRegistration(auto)).toThrow(
+      'Trigger group does not support manual webhook registration: group'
+    );
+    expect(() =>
+      getWebhookManualRegistration({ key: 'poll', name: 'Poll', source: 'polling' } as any)
+    ).toThrow('Trigger group does not support manual webhook registration: poll');
+  });
+});
+
 describe('mapAuthMethod', () => {
   let slate: any = { spec: { auth: { outputSchema: z.object({ token: z.string() }) } } };
   let oauthMethod: any = {

package/src/spec.ts

@@ -266,7 +266,11 @@ export let getWebhookAutoRegistration = <ConfigType extends {}, AuthType extends
 export let getWebhookManualRegistration = <ConfigType extends {}, AuthType extends {}>(
   group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
 ) => {
-  if (group.source !== 'webhook' || !group.webhook?.manualRegistration) {
+  let registration =
+    group.source === 'webhook'
+      ? (group.webhook?.manualRegistration ?? group.webhook?.deliveryConfig)
+      : undefined;
+  if (!registration) {
     throw new ServiceError(
       badRequestError({
         message: `Trigger group does not support manual webhook registration: ${group.key}`
@@ -274,9 +278,31 @@ export let getWebhookManualRegistration = <ConfigType extends {}, AuthType exten
     );
   }
 
-  return group.webhook.manualRegistration;
+  return registration;
 };
 
+export let getWebhookDeliveryConfig = <ConfigType extends {}, AuthType extends {}>(
+  group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
+) => {
+  if (group.source !== 'webhook' || !group.webhook?.deliveryConfig) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Trigger group does not support webhook delivery authentication: ${group.key}`
+      })
+    );
+  }
+
+  return group.webhook.deliveryConfig;
+};
+
+let mapWebhookConfigSchemas = (config: {
+  userConfigSchema: z.ZodType<any>;
+  fullConfigSchema: z.ZodType<any>;
+}) => ({
+  userConfigSchema: toJsonSchema(config.userConfigSchema),
+  fullConfigSchema: toJsonSchema(config.fullConfigSchema)
+});
+
 export let mapToolCategory = (category: SlateToolCategory): SlatesToolCategory => ({
   id: category.key,
   name: category.name,
@@ -307,6 +333,9 @@ export let mapTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
   name: group.name,
   description: group.description,
   metadata: group.metadata,
+  ...(group.selectionSchema
+    ? { selectionSchema: toJsonSchema(group.selectionSchema, 'input') }
+    : {}),
   invocation:
     group.source === 'polling'
       ? {
@@ -317,16 +346,25 @@ export let mapTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
         ? { type: 'gateway' }
         : {
             type: 'webhook',
+            ...(group.webhook?.expandWebhook ? { supportsExpansion: true } : {}),
+            ...(group.webhook?.autoRegistration?.webhookRenew
+              ? { supportsRenewal: true }
+              : {}),
+            ...(group.webhook?.reconcileIntervalSeconds !== undefined
+              ? { reconcileIntervalSeconds: group.webhook.reconcileIntervalSeconds }
+              : {}),
             registration: group.webhook?.manualRegistration
               ? {
                   mode: 'manual',
-                  userConfigSchema: toJsonSchema(
-                    group.webhook.manualRegistration.userConfigSchema
-                  ),
-                  fullConfigSchema: toJsonSchema(
-                    group.webhook.manualRegistration.fullConfigSchema
-                  )
+                  ...mapWebhookConfigSchemas(group.webhook.manualRegistration)
+                }
+              : {
+                  mode: 'auto',
+                  ...(group.webhook?.deliveryConfig
+                    ? {
+                        deliveryConfig: mapWebhookConfigSchemas(group.webhook.deliveryConfig)
+                      }
+                    : {})
                 }
-              : { mode: 'auto' }
           }
 });

package/src/validation.ts

@@ -26,8 +26,9 @@ export let validate = <T>(
   return result.data;
 };
 
-export let toJsonSchema = (schema: z.ZodType<any>) =>
+export let toJsonSchema = (schema: z.ZodType<any>, io: 'input' | 'output' = 'output') =>
   schema.toJSONSchema({
+    io,
     unrepresentable: 'any',
     override: ctx => {
       let def = ctx.zodSchema._zod.def;