@slates/provider 1.0.0-rc.2 → 1.0.0-rc.20

package/src/action/getFileUrlTool.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { SlateContext } from '../context/context';
+import type { SlateSpecification } from '../specification/specification';
+import { tool } from './tool';
+
+export let GET_FILE_URL_TOOL_ID = 'metorial$getFileUrl';
+
+export let getFileUrlToolInputSchema = z.object({
+  url: z.string(),
+  reference: z.any().nullable()
+});
+export type GetFileUrlToolInput = z.infer<typeof getFileUrlToolInputSchema>;
+
+export let getFileUrlToolOutputSchema = z.object({
+  url: z.string(),
+  expiresAt: z.string(),
+  headers: z.record(z.string(), z.string()).optional(),
+  query: z.record(z.string(), z.string()).optional()
+});
+export type GetFileUrlToolOutput = z.infer<typeof getFileUrlToolOutputSchema>;
+
+export type GetFileUrlHandler<ConfigType extends {}, AuthType extends {}> = (
+  context: SlateContext<ConfigType, AuthType, GetFileUrlToolInput>
+) => Promise<GetFileUrlToolOutput>;
+
+export let getFileUrlTool = <ConfigType extends {}, AuthType extends {}>(
+  spec: SlateSpecification<ConfigType, AuthType>,
+  handleGetFileUrl: GetFileUrlHandler<ConfigType, AuthType>
+) =>
+  tool(spec, {
+    key: GET_FILE_URL_TOOL_ID,
+    name: 'Get File URL',
+    description: 'Reserved: refreshes an expiring attachment download URL. Hub-internal only.'
+  })
+    .input(getFileUrlToolInputSchema)
+    .output(getFileUrlToolOutputSchema)
+    .handleInvocation(async ctx => ({
+      output: await handleGetFileUrl(ctx),
+      message: 'ok'
+    }))
+    .build();

package/src/action/index.ts

@@ -1,5 +1,7 @@
 export * from './action';
+export * from './builder';
+export * from './getFileUrlTool';
+export * from './publicTool';
+export * from './scopes';
 export * from './tool';
 export * from './trigger';
-
-export type * from './builder';

package/src/action/publicTool.ts

@@ -0,0 +1,36 @@
+import type { SlateSpecification } from '../specification/specification';
+import type { SlateActionParameters, SlatePublicToolInvocationHandler } from './action';
+import { SlateActionBuilder } from './builder';
+import { SlateTool } from './tool';
+
+export interface SlatePublicToolParameters<InputType extends {}, OutputType extends {}>
+  extends SlateActionParameters {
+  handleInvocation: SlatePublicToolInvocationHandler<InputType, OutputType>;
+}
+
+export class SlatePublicTool {
+  private constructor() {}
+
+  static create<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: SlateActionParameters
+  ) {
+    return new SlateActionBuilder(
+      'tool',
+      spec,
+      params,
+      params => {
+        return SlateTool.fromCreateParameters(spec, {
+          ...params,
+          isPublic: true
+        });
+      },
+      true
+    );
+  }
+}
+
+export let publicTool = <ConfigType extends {}, AuthType extends {}>(
+  spec: SlateSpecification<ConfigType, AuthType>,
+  params: SlateActionParameters
+) => SlatePublicTool.create(spec, params);

package/src/action/scopes.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { allOf, anyOf, mergeScopes, scopeClause, validateScopes } from './scopes';
+
+describe('action scope helpers', () => {
+  it('builds OR and AND scope clauses', () => {
+    expect(scopeClause('scope:read', 'scope:admin')).toEqual({
+      OR: ['scope:read', 'scope:admin']
+    });
+
+    expect(anyOf('scope:read', 'scope:admin')).toEqual({
+      AND: [{ OR: ['scope:read', 'scope:admin'] }]
+    });
+
+    expect(allOf(['scope:calendar'], ['scope:sharing', 'scope:sharing:admin'])).toEqual({
+      AND: [{ OR: ['scope:calendar'] }, { OR: ['scope:sharing', 'scope:sharing:admin'] }]
+    });
+  });
+
+  it('accepts nested scope structures and flattens them', () => {
+    expect(
+      allOf(
+        anyOf('scope:events.read', 'scope:events.write'),
+        scopeClause('scope:calendar'),
+        'scope:profile'
+      )
+    ).toEqual({
+      AND: [
+        { OR: ['scope:events.read', 'scope:events.write'] },
+        { OR: ['scope:calendar'] },
+        { OR: ['scope:profile'] }
+      ]
+    });
+  });
+
+  it('merges multiple scope sets and skips empty inputs', () => {
+    expect(
+      mergeScopes(
+        anyOf('scope:calendar'),
+        undefined,
+        false,
+        allOf(['scope:events.read', 'scope:events.write'], 'scope:profile')
+      )
+    ).toEqual({
+      AND: [
+        { OR: ['scope:calendar'] },
+        { OR: ['scope:events.read', 'scope:events.write'] },
+        { OR: ['scope:profile'] }
+      ]
+    });
+
+    expect(mergeScopes(undefined, false, null)).toBeUndefined();
+  });
+
+  it('validates and clones incoming scope objects', () => {
+    let input = {
+      AND: [{ OR: ['scope:calendar', 'scope:calendar:admin'] }]
+    };
+    let validated = validateScopes(input);
+
+    expect(validated).toEqual({
+      AND: [{ OR: ['scope:calendar', 'scope:calendar:admin'] }]
+    });
+    expect(validated).not.toBe(input);
+    expect(validated.AND[0]).not.toBe(input.AND[0]);
+  });
+
+  it('throws helpful errors for invalid scope definitions', () => {
+    expect(() => scopeClause()).toThrow(
+      'Each action scope clause must include at least one OR scope'
+    );
+    expect(() => scopeClause('')).toThrow('Action scopes must be non-empty strings');
+    expect(() => validateScopes({ AND: [] })).toThrow(
+      'Action scopes must include at least one AND clause'
+    );
+  });
+});

package/src/action/scopes.ts

@@ -0,0 +1,103 @@
+import { SlateDeclarationError } from '../error';
+import type { SlateActionScopeClause, SlateActionScopes } from './action';
+
+export type SlateActionScopeValue = string;
+
+export type SlateActionScopeClauseInput =
+  | SlateActionScopeValue
+  | readonly SlateActionScopeValue[]
+  | SlateActionScopeClause;
+
+export type SlateActionScopesInput = SlateActionScopeClauseInput | SlateActionScopes;
+
+export let scopeClause = (...scopes: SlateActionScopeValue[]): SlateActionScopeClause => {
+  assertScopeValues(scopes);
+  return {
+    OR: [...scopes]
+  };
+};
+
+export let anyOf = (...scopes: SlateActionScopeValue[]): SlateActionScopes => ({
+  AND: [scopeClause(...scopes)]
+});
+
+export let allOf = (...inputs: SlateActionScopesInput[]): SlateActionScopes => {
+  let AND = inputs.flatMap(input => normalizeScopes(input).AND);
+  return validateScopes({ AND });
+};
+
+export let mergeScopes = (
+  ...inputs: Array<SlateActionScopes | null | undefined | false>
+): SlateActionScopes | undefined => {
+  let AND = inputs.flatMap(input => (input ? input.AND : []));
+  if (AND.length === 0) {
+    return undefined;
+  }
+
+  return validateScopes({ AND });
+};
+
+export let validateScopes = (scopes: SlateActionScopes): SlateActionScopes => {
+  if (!Array.isArray(scopes.AND) || scopes.AND.length === 0) {
+    throw new SlateDeclarationError('Action scopes must include at least one AND clause');
+  }
+
+  return {
+    AND: scopes.AND.map(clause => normalizeClause(clause))
+  };
+};
+
+let normalizeScopes = (input: SlateActionScopesInput): SlateActionScopes => {
+  if (isScopes(input)) {
+    return validateScopes(input);
+  }
+
+  return {
+    AND: [normalizeClause(input)]
+  };
+};
+
+let normalizeClause = (input: SlateActionScopeClauseInput): SlateActionScopeClause => {
+  if (typeof input === 'string') {
+    return scopeClause(input);
+  }
+
+  if (Array.isArray(input)) {
+    return scopeClause(...input);
+  }
+
+  if (!isClause(input)) {
+    throw new SlateDeclarationError('Action scope clauses must be strings or OR clauses');
+  }
+
+  assertScopeValues(input.OR);
+  return {
+    OR: [...input.OR]
+  };
+};
+
+let assertScopeValues = (scopes: readonly SlateActionScopeValue[]) => {
+  if (scopes.length === 0) {
+    throw new SlateDeclarationError(
+      'Each action scope clause must include at least one OR scope'
+    );
+  }
+
+  for (let scope of scopes) {
+    if (typeof scope !== 'string' || scope.trim().length === 0) {
+      throw new SlateDeclarationError('Action scopes must be non-empty strings');
+    }
+  }
+};
+
+let isClause = (value: unknown): value is SlateActionScopeClause =>
+  typeof value === 'object' &&
+  value !== null &&
+  'OR' in value &&
+  Array.isArray((value as SlateActionScopeClause).OR);
+
+let isScopes = (value: unknown): value is SlateActionScopes =>
+  typeof value === 'object' &&
+  value !== null &&
+  'AND' in value &&
+  Array.isArray((value as SlateActionScopes).AND);

package/src/action/tool.ts

@@ -1,6 +1,10 @@
-import z from 'zod';
-import { SlateSpecification } from '../specification/specification';
-import { SlateAction, SlateActionParameters, SlateToolInvocationHandler } from './action';
+import type z from 'zod';
+import type { SlateSpecification } from '../specification/specification';
+import {
+  SlateAction,
+  type SlateActionParameters,
+  type SlateToolInvocationHandler
+} from './action';
 import { SlateActionBuilder } from './builder';
 
 export interface SlateToolParameters<
@@ -20,7 +24,7 @@ export class SlateTool<
 > extends SlateAction<'tool', ConfigType, AuthType, InputType, OutputType> {
   #handleInvocation: SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>;
 
-  private constructor(
+  protected constructor(
     spec: SlateSpecification<ConfigType, AuthType>,
     inputSchema: z.ZodType<InputType>,
     outputSchema: z.ZodType<OutputType>,
@@ -36,11 +40,23 @@ export class SlateTool<
     params: SlateActionParameters
   ) {
     return new SlateActionBuilder('tool', spec, params, params => {
-      if (params.type != 'tool') throw new Error('Invalid action type for tool');
-      return new SlateTool(spec, params.inputSchema, params.outputSchema, params);
+      return SlateTool.fromCreateParameters(spec, params);
     });
   }
 
+  static fromCreateParameters<ConfigType extends {}, AuthType extends {}>(
+    spec: SlateSpecification<ConfigType, AuthType>,
+    params: {
+      type: string;
+      inputSchema: z.ZodType<any>;
+      outputSchema: z.ZodType<any>;
+      handleInvocation?: SlateToolInvocationHandler<ConfigType, AuthType, any, any>;
+    } & SlateActionParameters
+  ) {
+    if (params.type !== 'tool') throw new Error('Invalid action type for tool');
+    return new SlateTool(spec, params.inputSchema, params.outputSchema, params as any);
+  }
+
   get handleInvocation() {
     return this.#handleInvocation;
   }

package/src/action/trigger.ts

@@ -1,18 +1,19 @@
-import z from 'zod';
-import { SlateSpecification } from '../specification/specification';
+import type z from 'zod';
+import type { SlateSpecification } from '../specification/specification';
 import {
   SlateAction,
-  SlateActionParameters,
-  SlatePollingOptions,
-  SlateTriggerMappingHandler,
-  SlateTriggerPollingHandler,
-  SlateTriggerWebhookAutoRegistrationHandler,
-  SlateTriggerWebhookAutoUnregistrationHandler,
-  SlateTriggerWebhookRequestHandler
+  type SlateActionParameters,
+  type SlatePollingOptions,
+  type SlateTriggerMappingHandler,
+  type SlateTriggerPollingHandler,
+  type SlateTriggerWebhookAutoRegistrationHandler,
+  type SlateTriggerWebhookAutoUnregistrationHandler,
+  type SlateTriggerWebhookRequestHandler,
+  type SlateWebhookHttpOptions
 } from './action';
 import { SlateActionBuilder } from './builder';
 
-export const SlateDefaultPollingIntervalSeconds = 60 * 10;
+export let SlateDefaultPollingIntervalSeconds = 60 * 10;
 
 export interface SlateTriggerParameters<
   ConfigType extends {},
@@ -27,6 +28,7 @@ export interface SlateTriggerParameters<
   polling?: SlatePollingOptions;
   handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  http?: SlateWebhookHttpOptions;
   pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -44,6 +46,7 @@ export class SlateTrigger<
   #polling: SlatePollingOptions;
   #handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   #handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  #http?: SlateWebhookHttpOptions;
   #pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   #autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   #autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -62,6 +65,7 @@ export class SlateTrigger<
     };
     this.#handleEvent = params.handleEvent;
     this.#handleRequest = params.handleRequest;
+    this.#http = params.http;
     this.#pollEvents = params.pollEvents;
     this.#autoRegisterWebhook = params.autoRegisterWebhook;
     this.#autoUnregisterWebhook = params.autoUnregisterWebhook;
@@ -72,7 +76,7 @@ export class SlateTrigger<
     params: SlateActionParameters
   ) {
     return new SlateActionBuilder('trigger', spec, params, params => {
-      if (params.type != 'trigger') throw new Error('Invalid action type for trigger');
+      if (params.type !== 'trigger') throw new Error('Invalid action type for trigger');
       return new SlateTrigger(spec, params.inputSchema, params.outputSchema, params);
     });
   }
@@ -93,6 +97,10 @@ export class SlateTrigger<
     return this.#handleRequest;
   }
 
+  get http() {
+    return this.#http;
+  }
+
   get pollEvents() {
     return this.#pollEvents;
   }

package/src/adapter/adapter.ts

@@ -0,0 +1,38 @@
+import type { SlateTool, SlateTrigger } from '../action';
+import type { SlateAdapterSpec } from './spec';
+
+export class SlateAdapter<ConfigType extends {}, AuthType extends {}> {
+  constructor(
+    private readonly _spec: SlateAdapterSpec,
+    private readonly _tools: SlateTool<ConfigType, AuthType, any, any>[],
+    private readonly _triggers: SlateTrigger<ConfigType, AuthType, any, any>[]
+  ) {}
+
+  get spec() {
+    return this._spec;
+  }
+
+  get id() {
+    return this._spec.id;
+  }
+
+  get name() {
+    return this._spec.name;
+  }
+
+  get capabilities() {
+    return this._spec.capabilities;
+  }
+
+  get tools() {
+    return this._tools;
+  }
+
+  get triggers() {
+    return this._triggers;
+  }
+
+  get actions() {
+    return [...this._triggers, ...this._tools];
+  }
+}