@slates/provider 1.0.0-rc.33 → 1.0.0-rc.35

package/src/action/optionList.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import type { SlateContext } from '../context';
+import { SlateDeclarationError } from '../error';
+import type { SlateSpecification } from '../specification/specification';
+
+export interface SlateOption {
+  value: string | number;
+  label: string;
+  description?: string;
+}
+
+export interface SlateOptionListPage {
+  options: SlateOption[];
+  nextPageToken?: any | null;
+}
+
+export type SlateOptionListHandler<
+  ConfigType extends {},
+  AuthType extends {},
+  ParamsType extends {} = {}
+> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { query: string | null; pageToken: any | null; params: ParamsType }
+  >
+) => Promise<SlateOptionListPage>;
+
+export interface SlateOptionListParameters<
+  ConfigType extends {},
+  AuthType extends {},
+  ParamsSchema extends z.ZodObject<any> = z.ZodObject<{}>
+> {
+  key: string;
+  /** Made strict when declared, so params with a key the schema does not name are rejected. */
+  paramsSchema?: ParamsSchema;
+  list: SlateOptionListHandler<ConfigType, AuthType, z.output<ParamsSchema>>;
+}
+
+/** A list of options other integrations can link their selection fields to. */
+export class SlateOptionList<
+  ConfigType extends {},
+  AuthType extends {},
+  ParamsSchema extends z.ZodObject<any> = z.ZodObject<{}>
+> {
+  private constructor(
+    private readonly _spec: SlateSpecification<ConfigType, AuthType>,
+    private readonly _params: SlateOptionListParameters<ConfigType, AuthType, ParamsSchema>,
+    private readonly _paramsSchema: z.ZodObject<any>
+  ) {}
+
+  static create<
+    ConfigType extends {},
+    AuthType extends {},
+    ParamsSchema extends z.ZodObject<any> = z.ZodObject<{}>
+  >(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateOptionListParameters<ConfigType, AuthType, ParamsSchema>
+  ) {
+    let paramsSchema: z.ZodObject<any> = params.paramsSchema ?? z.object({});
+    if (paramsSchema?._zod?.def?.type !== 'object') {
+      throw new SlateDeclarationError(
+        `Option list "${params.key}" params schema must be a zod object`
+      );
+    }
+
+    return new SlateOptionList(spec, params, paramsSchema.strict());
+  }
+
+  get spec() {
+    return this._spec;
+  }
+
+  get key() {
+    return this._params.key;
+  }
+
+  get paramsSchema() {
+    return this._paramsSchema;
+  }
+
+  get list() {
+    return this._params.list;
+  }
+}
+
+export let optionList = <
+  ConfigType extends {},
+  AuthType extends {},
+  ParamsSchema extends z.ZodObject<any> = z.ZodObject<{}>
+>(
+  spec: SlateSpecification<ConfigType, AuthType>,
+  params: SlateOptionListParameters<ConfigType, AuthType, ParamsSchema>
+) => SlateOptionList.create(spec, params);

package/src/action/trigger.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { SlateAuth } from '../auth';
+import { SlateConfig } from '../config';
+import { SlateSpecification } from '../specification/specification';
+import { SlateTool } from './tool';
+import { SlateTrigger } from './trigger';
+import { triggerGroup } from './triggerGroup';
+
+let spec = SlateSpecification.create({
+  key: 'demo',
+  name: 'Demo',
+  config: SlateConfig.create(z.object({})),
+  auth: SlateAuth.create<{}>().output(z.object({}))
+});
+
+let group = triggerGroup(spec, { key: 'group', name: 'Group' })
+  .polling({ pollEvents: async () => ({ events: [] }) })
+  .routingMatchers(async () => [])
+  .build();
+
+let output = z.object({
+  fileId: z.string(),
+  parents: z.array(z.string()),
+  size: z.number().optional()
+});
+
+let create = () =>
+  SlateTrigger.create(spec, { key: 'changed', name: 'Changed' })
+    .input(z.object({}))
+    .triggerGroup(group)
+    .matches(() => true)
+    .map(async () => ({
+      type: 'file.changed',
+      id: '1',
+      output: { fileId: 'a', parents: [] }
+    }));
+
+describe('trigger event attributes', () => {
+  it('exposes the declared fields on the built trigger', () => {
+    let trigger = create().output(output).eventAttributes(['fileId', 'parents']).build();
+
+    expect(trigger.eventAttributes).toEqual(['fileId', 'parents']);
+  });
+
+  it('is empty when none are declared', () => {
+    expect(create().output(output).build().eventAttributes).toEqual([]);
+  });
+
+  it('checks the fields against an output schema set after the declaration', () => {
+    expect(
+      create()
+        .eventAttributes(['fileId'] as never[])
+        .output(output)
+        .build().eventAttributes
+    ).toEqual(['fileId']);
+
+    expect(() =>
+      create()
+        .eventAttributes(['folderId'] as never[])
+        .output(output)
+        .build()
+    ).toThrow('Event attribute "folderId" is not a top-level property of the output schema');
+  });
+
+  it('rejects fields that are not top-level output properties', () => {
+    expect(() =>
+      create()
+        .output(output)
+        .eventAttributes(['folderId' as any])
+    ).toThrow('Event attribute "folderId" is not a top-level property of the output schema');
+  });
+
+  it('requires the output schema to be a zod object', () => {
+    expect(() =>
+      create()
+        .output(z.record(z.string(), z.string()) as unknown as z.ZodType<{ fileId: string }>)
+        .eventAttributes(['fileId'])
+    ).toThrow('Event attributes require the output schema to be a zod object');
+
+    expect(() =>
+      create()
+        .eventAttributes(['fileId'] as never[])
+        .output(z.record(z.string(), z.string()) as unknown as z.ZodType<{ fileId: string }>)
+        .build()
+    ).toThrow('Event attributes require the output schema to be a zod object');
+  });
+
+  it('rejects names that do not match the key pattern', () => {
+    let schema = z.object({ _id: z.string(), '1st': z.string(), 'a-b': z.string() });
+    for (let field of ['_id', '1st', 'a-b']) {
+      expect(() =>
+        create()
+          .output(schema)
+          .eventAttributes([field as any])
+      ).toThrow(`Event attribute "${field}" must start with a letter`);
+    }
+
+    let long = 'a'.repeat(65);
+    expect(() => create().eventAttributes([long as never])).toThrow(
+      `Event attribute "${long}" must start with a letter`
+    );
+  });
+
+  it('rejects duplicates', () => {
+    expect(() => create().output(output).eventAttributes(['fileId', 'fileId'])).toThrow(
+      'Event attribute "fileId" is declared more than once'
+    );
+  });
+
+  it('allows at most eight fields', () => {
+    let fields = Array.from({ length: 9 }, (_, i) => `field${i}`);
+    let schema = z.object(Object.fromEntries(fields.map(field => [field, z.string()])));
+
+    expect(
+      create().output(schema).eventAttributes(fields.slice(0, 8)).build().eventAttributes
+    ).toHaveLength(8);
+    expect(() => create().output(schema).eventAttributes(fields)).toThrow(
+      'A trigger can declare at most 8 event attributes'
+    );
+  });
+
+  it('can only be declared on triggers', () => {
+    let tool = SlateTool.create(spec, { key: 'send', name: 'Send' })
+      .input(z.object({}))
+      .output(z.object({ id: z.string() }));
+
+    expect(() => tool.eventAttributes(['id'])).toThrow(
+      'eventAttributes can only be set for trigger actions'
+    );
+  });
+});

package/src/action/trigger.ts

@@ -21,6 +21,7 @@ export interface SlateTriggerParameters<
   triggerGroup: SlateTriggerGroup<ConfigType, AuthType>;
   matches: SlateTriggerMatchesHandler;
   map: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
+  eventAttributes?: string[];
 }
 
 export class SlateTrigger<
@@ -34,6 +35,7 @@ export class SlateTrigger<
   #triggerGroup: SlateTriggerGroup<ConfigType, AuthType>;
   #matches: SlateTriggerMatchesHandler;
   #map: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
+  #eventAttributes: string[];
 
   private constructor(
     spec: SlateSpecification<ConfigType, AuthType>,
@@ -46,6 +48,7 @@ export class SlateTrigger<
     this.#triggerGroup = params.triggerGroup;
     this.#matches = params.matches;
     this.#map = params.map;
+    this.#eventAttributes = params.eventAttributes ?? [];
   }
 
   static create<ConfigType extends {}, AuthType extends {}>(
@@ -69,6 +72,10 @@ export class SlateTrigger<
   get map() {
     return this.#map;
   }
+
+  get eventAttributes(): string[] {
+    return [...this.#eventAttributes];
+  }
 }
 
 export let trigger = <ConfigType extends {}, AuthType extends {}>(

package/src/action/triggerGroup.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { SlateAuth } from '../auth';
+import { SlateConfig } from '../config';
+import { SlateSpecification } from '../specification/specification';
+import { triggerGroup } from './triggerGroup';
+
+let spec = SlateSpecification.create({
+  key: 'demo',
+  name: 'Demo',
+  config: SlateConfig.create(z.object({})),
+  auth: SlateAuth.create<{}>().output(z.object({}))
+});
+
+let autoRegistration = {
+  webhookTargetList: async () => ({ targets: [], nextPageToken: null }),
+  webhookRegister: async () => ({
+    webhookRegistrationIdentifier: 'reg',
+    webhookRegistrationPayload: {}
+  }),
+  webhookUnregister: async () => {}
+};
+let setup = async () => ({ webhookSetupDocument: '', partialWebhookRegistrationPayload: {} });
+let manualRegistration = {
+  userConfigSchema: z.object({}),
+  fullConfigSchema: z.object({}),
+  setup
+};
+let deliveryConfig = {
+  ...manualRegistration,
+  finish: async () => ({ webhookRegistrationPayload: {} }),
+  authenticate: async () => ({ routingKeys: [] })
+};
+
+type WebhookProps = Parameters<ReturnType<typeof triggerGroup>['webhook']>[0];
+
+let build = (props: Omit<WebhookProps, 'process'>) =>
+  triggerGroup(spec, { key: 'group', name: 'Group' })
+    .webhook({ ...props, process: async () => ({ events: [] }) })
+    .routingMatchers(async () => [])
+    .build();
+
+describe('webhook trigger group declaration', () => {
+  it('builds plain automatic and manual groups as before', () => {
+    expect(build({ autoRegistration }).webhook).toMatchObject({
+      autoRegistration,
+      manualRegistration: undefined,
+      deliveryConfig: undefined
+    });
+    expect(build({ manualRegistration }).webhook).toMatchObject({
+      autoRegistration: undefined,
+      manualRegistration,
+      deliveryConfig: undefined
+    });
+  });
+
+  it('requires exactly one of automatic or manual registration', () => {
+    let message =
+      'Webhook trigger groups require exactly one of autoRegistration or manualRegistration';
+    expect(() => build({})).toThrow(message);
+    expect(() => build({ deliveryConfig })).toThrow(message);
+    expect(() => build({ autoRegistration, manualRegistration })).toThrow(message);
+  });
+
+  it('allows a delivery config only with automatic registration and its handlers', () => {
+    expect(build({ autoRegistration, deliveryConfig }).webhook?.deliveryConfig).toBe(
+      deliveryConfig
+    );
+    expect(() => build({ manualRegistration, deliveryConfig })).toThrow(
+      'A webhook delivery config requires automatic webhook registration'
+    );
+    let { finish: _, ...withoutFinish } = deliveryConfig;
+    expect(() =>
+      build({
+        autoRegistration,
+        deliveryConfig: withoutFinish as unknown as typeof deliveryConfig
+      })
+    ).toThrow('A webhook delivery config requires a finish handler');
+  });
+
+  it('requires a delivery config to authenticate the requests it receives', () => {
+    let { authenticate: _, ...withoutAuthenticate } = deliveryConfig;
+    expect(() =>
+      build({
+        autoRegistration,
+        deliveryConfig: withoutAuthenticate as unknown as typeof deliveryConfig
+      })
+    ).toThrow('A webhook delivery config requires an authenticate handler');
+  });
+});
+
+describe('trigger group selection options', () => {
+  let polling = (
+    selectionSchema: z.ZodType<Record<string, any>> = z.object({
+      fileId: z.string(),
+      tab: z.string().optional(),
+      fileIds: z.array(z.string()),
+      folder: z.object({ id: z.string() })
+    })
+  ) =>
+    triggerGroup(spec, { key: 'group', name: 'Group', selectionSchema })
+      .polling({ pollEvents: async () => ({ events: [] }) })
+      .routingMatchers(async () => []);
+  let list = async () => ({ options: [{ value: 'a', label: 'A' }] });
+  let linked = { slate: 'acme/files', optionList: 'files', params: { kind: 'sheet' } };
+
+  it('rejects fields that are not top-level properties of the selection schema', () => {
+    for (let field of ['fileid', 'folder.id', 'id', 'constructor']) {
+      expect(() => polling().selectionOptions({ [field]: { list } })).toThrow(
+        `Selection field "${field}" is not a top-level property of the selection schema`
+      );
+    }
+  });
+
+  it('rejects a selection schema that is not a zod object', () => {
+    for (let selectionSchema of [
+      z.record(z.string(), z.string()),
+      z.object({ fileId: z.string() }).optional() as z.ZodType<Record<string, any>>
+    ]) {
+      expect(() => polling(selectionSchema).selectionOptions({ fileId: { list } })).toThrow(
+        'Selection options require the selection schema to be a zod object'
+      );
+    }
+    expect(() =>
+      triggerGroup(spec, { key: 'group', name: 'Group' }).selectionOptions({
+        fileId: { list }
+      })
+    ).toThrow('Selection options require a selection schema');
+  });
+
+  it('rejects a bare handler instead of { list, linked }', () => {
+    for (let declaration of [list, null]) {
+      expect(() => polling().selectionOptions({ fileId: declaration as any })).toThrow(
+        'Selection field "fileId" must be declared as { list, linked }'
+      );
+    }
+  });
+
+  it('accepts an own list, a linked list, or both per field', () => {
+    let group = polling()
+      .selectionOptions({ fileId: { list, linked } })
+      .selectionOptions({
+        tab: { linked: { slate: 'acme/files', optionList: 'tabs' } },
+        fileIds: { list }
+      })
+      .build();
+    expect(group.selectionOptions).toEqual({
+      fileId: { list, linked },
+      tab: { linked: { slate: 'acme/files', optionList: 'tabs' } },
+      fileIds: { list }
+    });
+  });
+
+  it('rejects a field without an own list or a linked list', () => {
+    expect(() => polling().selectionOptions({ fileId: {} })).toThrow(
+      'Selection field "fileId" needs its own options list, a linked option list, or both'
+    );
+  });
+
+  it('rejects linked lists that do not name a scoped slate and a list', () => {
+    expect(() =>
+      polling().selectionOptions({
+        fileId: { linked: { slate: 'files', optionList: 'files' } }
+      })
+    ).toThrow('must be written as <scope>/<name>');
+    expect(() =>
+      polling().selectionOptions({
+        fileId: { linked: { slate: 'acme/files', optionList: ' ' } }
+      })
+    ).toThrow('Selection field "fileId" must name the option list it links to');
+  });
+});