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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.21",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,7 @@
     "package.json"
   ],
   "author": "Tobias Herber",
-  "license": "Apache 2",
+  "license": "FSL 1.1",
   "type": "module",
   "source": "src/index.ts",
   "exports": {
@@ -23,20 +23,23 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.module.js",
   "types": "dist/index.d.ts",
-  "unpkg": "./dist/index.umd.js",
+  "unpkg": "./dist/index.module.js",
   "scripts": {
     "test": "vitest run --passWithNoTests",
-    "lint": "prettier src/**/*.ts --check",
-    "build": "microbundle"
+    "build": "tsup --config ../../tsup.packages.config.ts --external async_hooks",
+    "typecheck": "tsc --noEmit",
+    "biome:check": "biome check --write src"
   },
   "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
     "@toon-format/toon": "^2.1.0",
     "axios": "^1.13.2",
+    "p-queue": "^6.6.2",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "microbundle": "^0.15.1",
-    "@slates/tsconfig": "^1.0.0",
+    "@slates/tsconfig": "1.0.0-rc.1",
     "typescript": "5.8.2",
     "vitest": "^3.1.2"
   }

package/src/action/action.ts

@@ -1,9 +1,19 @@
-import { z } from 'zod';
-import { SlateContext } from '../context';
-import { SlateSpecification } from '../specification/specification';
+import type { z } from 'zod';
+import type { SlateContext, SlatePublicContext } from '../context';
+import type { SlateActionDocsReference } from '../docs';
+import type { SlateSpecification } from '../specification/specification';
+import type { SlateAttachment } from './attachment';
 
 export type SlateActionType = 'tool' | 'trigger';
 
+export interface SlateActionScopeClause {
+  OR: string[];
+}
+
+export interface SlateActionScopes {
+  AND: SlateActionScopeClause[];
+}
+
 export interface SlateActionParameters {
   key: string;
   name: string;
@@ -16,6 +26,11 @@ export interface SlateActionParameters {
     [key: string]: boolean | undefined;
   };
   metadata?: Record<string, any>;
+  scopes?: SlateActionScopes;
+  authMethods?: string[];
+  docs?: SlateActionDocsReference[];
+  adapter?: string | null;
+  isPublic?: boolean;
 }
 
 export type SlateToolInvocationHandler<
@@ -26,6 +41,15 @@ export type SlateToolInvocationHandler<
 > = (context: SlateContext<ConfigType, AuthType, InputType>) => Promise<{
   output: OutputType;
   message: string;
+  attachments?: SlateAttachment[];
+}>;
+
+export type SlatePublicToolInvocationHandler<InputType extends {}, OutputType extends {}> = (
+  context: SlatePublicContext<InputType>
+) => Promise<{
+  output: OutputType;
+  message: string;
+  attachments?: SlateAttachment[];
 }>;
 
 export type SlateTriggerMappingHandler<
@@ -48,15 +72,58 @@ export type SlateTriggerPollingHandler<
   updatedState?: any;
 }>;
 
+export interface SlateWebhookHttpResponseInit {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array | null;
+}
+
+export type SlateWebhookHttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'HEAD'
+  | 'OPTIONS';
+
+export interface SlateWebhookRequestMatcher {
+  method?: string;
+  hasQueryParam?: string;
+  hasHeader?: string;
+  jsonBodyField?: {
+    path: string;
+    equals?: string;
+  };
+  formBodyField?: {
+    path: string;
+    equals?: string;
+  };
+}
+
+export interface SlateWebhookHttpOptions {
+  methods?: SlateWebhookHttpMethod[];
+  sync?: {
+    mode: 'never' | 'match' | 'always';
+    match?: SlateWebhookRequestMatcher[];
+    timeoutMs?: number;
+  };
+}
+
 export type SlateTriggerWebhookRequestHandler<
   ConfigType extends {},
   AuthType extends {},
   InputType extends {}
 > = (
-  context: SlateContext<ConfigType, AuthType, { request: Request; state: any | null }>
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { request: Request; state: any | null; registrationDetails: any | null }
+  >
 ) => Promise<{
   inputs: InputType[];
   updatedState?: any;
+  response?: Response | SlateWebhookHttpResponseInit;
 }>;
 
 export type SlateTriggerWebhookAutoRegistrationHandler<
@@ -103,6 +170,7 @@ export interface SlateActionParametersTrigger<
   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>;
@@ -188,4 +256,24 @@ export abstract class SlateAction<
   get metadata() {
     return this._params.metadata;
   }
+
+  get scopes() {
+    return this._params.scopes;
+  }
+
+  get authMethods() {
+    return this._params.authMethods;
+  }
+
+  get docs() {
+    return this._params.docs;
+  }
+
+  get adapter() {
+    return this._params.adapter ?? null;
+  }
+
+  get isPublic() {
+    return this._params.isPublic === true;
+  }
 }

package/src/action/attachment.ts

@@ -0,0 +1,87 @@
+export interface SlateAttachmentUrlContent {
+  type: 'url';
+  url: string;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  refreshReference?: unknown;
+  refreshAt?: string;
+}
+
+export interface SlateAttachmentInlineContent {
+  type: 'content';
+  encoding: 'base64' | 'utf-8';
+  content: string;
+}
+
+export interface SlateAttachmentUploadReferenceContent {
+  type: 'upload_reference';
+  referenceId: string;
+}
+
+export interface SlateAttachment {
+  mimeType?: string;
+  attachmentHash?: string;
+  content:
+    | SlateAttachmentUrlContent
+    | SlateAttachmentInlineContent
+    | SlateAttachmentUploadReferenceContent;
+}
+
+export let createUrlAttachment = (
+  url: string,
+  opts: {
+    mimeType?: string;
+    attachmentHash?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    refreshReference?: unknown;
+    refreshAt?: string;
+  } = {}
+): SlateAttachment => {
+  if (opts.refreshReference !== undefined && !opts.refreshAt) {
+    throw new Error('createUrlAttachment: refreshAt is required when refreshReference is set');
+  }
+
+  return {
+    mimeType: opts.mimeType,
+    attachmentHash: opts.attachmentHash,
+    content: {
+      type: 'url',
+      url,
+      ...(opts.headers ? { headers: opts.headers } : {}),
+      ...(opts.query ? { query: opts.query } : {}),
+      ...(opts.refreshReference !== undefined
+        ? { refreshReference: opts.refreshReference }
+        : {}),
+      ...(opts.refreshAt ? { refreshAt: opts.refreshAt } : {})
+    }
+  };
+};
+
+export let createBase64Attachment = (
+  content: string,
+  mimeType?: string,
+  attachmentHash?: string
+): SlateAttachment => ({
+  mimeType,
+  attachmentHash,
+  content: {
+    type: 'content',
+    encoding: 'base64',
+    content
+  }
+});
+
+export let createTextAttachment = (
+  content: string,
+  mimeType?: string,
+  attachmentHash?: string
+): SlateAttachment => ({
+  mimeType,
+  attachmentHash,
+  content: {
+    type: 'content',
+    encoding: 'utf-8',
+    content
+  }
+});

package/src/action/builder.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { SlateAuth } from '../auth';
+import { SlateConfig } from '../config';
+import { SlatePublicContext } from '../context';
+import { SlateSpecification } from '../specification/specification';
+import { SlatePublicTool } from './publicTool';
+import { SlateTool } from './tool';
+
+let createTestSpec = () => {
+  let config = SlateConfig.create(
+    z.object({
+      prefix: z.string()
+    })
+  );
+  let auth = SlateAuth.create<{ token: string }>().output(
+    z.object({
+      token: z.string()
+    })
+  );
+
+  return SlateSpecification.create({
+    key: 'demo',
+    name: 'Demo',
+    config,
+    auth
+  });
+};
+
+describe('SlateActionBuilder.lockInterface', () => {
+  it('prevents changing input and output schemas after the interface is locked', () => {
+    let spec = createTestSpec();
+    let builder = SlateTool.create(spec, {
+      key: 'send',
+      name: 'Send'
+    })
+      .input(z.object({ to: z.string() }))
+      .output(z.object({ id: z.string() }))
+      .lockInterface();
+
+    expect(() => builder.input(z.object({}))).toThrow(
+      'Adapter contract input schema cannot be changed'
+    );
+    expect(() => builder.output(z.object({}))).toThrow(
+      'Adapter contract output schema cannot be changed'
+    );
+  });
+});
+
+describe('SlatePublicTool', () => {
+  it('builds a public tool that omits config and auth from the handler context', async () => {
+    let spec = createTestSpec();
+    let tool = SlatePublicTool.create(spec, {
+      key: 'setup',
+      name: 'Setup'
+    })
+      .input(
+        z.object({
+          name: z.string()
+        })
+      )
+      .output(
+        z.object({
+          greeting: z.string()
+        })
+      )
+      .handleInvocation(async ctx => {
+        expect(ctx).not.toHaveProperty('config');
+        expect(ctx).not.toHaveProperty('auth');
+
+        return {
+          output: { greeting: `Hello ${ctx.input.name}` },
+          message: 'ok'
+        };
+      })
+      .build();
+
+    expect(tool.isPublic).toBe(true);
+    expect(tool.key).toBe('setup');
+
+    let result = await tool.handleInvocation(
+      new SlatePublicContext({ name: 'Ada' }, spec, {
+        debug: () => {},
+        error: () => {},
+        info: () => {},
+        progress: () => {},
+        warn: () => {}
+      } as any) as any
+    );
+
+    expect(result.output).toEqual({ greeting: 'Hello Ada' });
+  });
+
+  it('keeps regular tools private by default', () => {
+    let spec = createTestSpec();
+    let tool = SlateTool.create(spec, {
+      key: 'send',
+      name: 'Send'
+    })
+      .input(z.object({}))
+      .output(z.object({}))
+      .handleInvocation(async () => ({
+        output: {},
+        message: 'ok'
+      }))
+      .build();
+
+    expect(tool.isPublic).toBe(false);
+  });
+
+  it('rejects authentication methods on public tools', () => {
+    let spec = createTestSpec();
+
+    expect(() =>
+      SlatePublicTool.create(spec, {
+        key: 'setup',
+        name: 'Setup'
+      }).authMethods(['token_auth'])
+    ).toThrow('Public tools cannot require authentication methods');
+
+    expect(() =>
+      SlatePublicTool.create(spec, {
+        key: 'setup',
+        name: 'Setup',
+        authMethods: ['token_auth']
+      })
+        .input(z.object({}))
+        .output(z.object({}))
+        .handleInvocation(async () => ({
+          output: {},
+          message: 'ok'
+        }))
+        .build()
+    ).toThrow('Public tools cannot require authentication methods');
+  });
+});

package/src/action/builder.ts

@@ -1,21 +1,25 @@
-import z from 'zod';
+import type z from 'zod';
 import { SlateDeclarationError } from '../error';
-import { SlateSpecification } from '../specification/specification';
-import {
+import type { SlateSpecification } from '../specification/specification';
+import type {
   SlateAction,
   SlateActionCreateParameters,
   SlateActionParameters,
   SlateActionParametersTool,
   SlateActionParametersTrigger,
+  SlateActionScopes,
   SlateActionType,
   SlatePollingOptions,
+  SlatePublicToolInvocationHandler,
   SlateToolInvocationHandler,
   SlateTriggerMappingHandler,
   SlateTriggerPollingHandler,
   SlateTriggerWebhookAutoRegistrationHandler,
   SlateTriggerWebhookAutoUnregistrationHandler,
-  SlateTriggerWebhookRequestHandler
+  SlateTriggerWebhookRequestHandler,
+  SlateWebhookHttpOptions
 } from './action';
+import { validateScopes } from './scopes';
 
 export class SlateActionBuilder<
   Type extends SlateActionType,
@@ -23,12 +27,15 @@ export class SlateActionBuilder<
   AuthType extends {},
   InputType extends {},
   OutputType extends {},
-  Result extends SlateAction<Type, ConfigType, AuthType, any, any>
+  Result extends SlateAction<Type, ConfigType, AuthType, any, any>,
+  IsPublic extends boolean = false
 > {
   #configSchema: z.ZodType<ConfigType>;
   #authSchema: z.ZodType<AuthType>;
   #inputSchema: z.ZodType<InputType> | null = null;
   #outputSchema: z.ZodType<OutputType> | null = null;
+  #scopes: SlateActionScopes | undefined;
+  #authMethods: string[] | undefined;
 
   #toolParams: SlateActionParametersTool<ConfigType, AuthType, InputType, OutputType> | null =
     null;
@@ -38,14 +45,16 @@ export class SlateActionBuilder<
     InputType,
     OutputType
   > | null = null;
+  #interfaceLocked = false;
 
   constructor(
     private readonly type: Type,
-    private readonly spec: SlateSpecification<ConfigType, AuthType>,
+    readonly spec: SlateSpecification<ConfigType, AuthType>,
     private readonly params: SlateActionParameters,
     private readonly factory: (
       params: SlateActionCreateParameters<any, any, any, any>
-    ) => Result
+    ) => Result,
+    private readonly isPublicTool: IsPublic = false as IsPublic
   ) {
     this.#configSchema = spec.configSchema;
     this.#authSchema = spec.authSchema;
@@ -53,28 +62,102 @@ export class SlateActionBuilder<
 
   input<NewInputType extends {}>(
     schema: z.ZodType<NewInputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, NewInputType, OutputType, Result> {
+  ): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    NewInputType,
+    OutputType,
+    Result,
+    IsPublic
+  > {
+    if (this.#interfaceLocked) {
+      throw new SlateDeclarationError('Adapter contract input schema cannot be changed');
+    }
+
     this.#inputSchema = schema as any;
     return this as any;
   }
 
   output<NewOutputType extends {}>(
     schema: z.ZodType<NewOutputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, NewOutputType, Result> {
+  ): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    InputType,
+    NewOutputType,
+    Result,
+    IsPublic
+  > {
+    if (this.#interfaceLocked) {
+      throw new SlateDeclarationError('Adapter contract output schema cannot be changed');
+    }
+
     this.#outputSchema = schema as any;
     return this as any;
   }
 
+  lockInterface(): SlateActionBuilder<
+    Type,
+    ConfigType,
+    AuthType,
+    InputType,
+    OutputType,
+    Result,
+    IsPublic
+  > {
+    this.#interfaceLocked = true;
+    return this;
+  }
+
+  scopes(
+    scopes: SlateActionScopes
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
+    validateScopes(scopes);
+    this.#scopes = scopes;
+    return this;
+  }
+
+  authMethods(
+    authMethods: string[]
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
+    if (this.isPublicTool) {
+      throw new SlateDeclarationError('Public tools cannot require authentication methods');
+    }
+
+    this.#authMethods = this.validateAuthMethods(authMethods);
+    return this;
+  }
+
+  private validateAuthMethods(authMethods: string[] | undefined) {
+    if (!authMethods) return undefined;
+
+    let normalized = [...new Set(authMethods.map(authMethod => authMethod.trim()))];
+    if (normalized.some(authMethod => !authMethod)) {
+      throw new SlateDeclarationError('Auth method IDs must be non-empty strings');
+    }
+
+    return normalized;
+  }
+
   handleInvocation(
-    handler: SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+    handler: IsPublic extends true
+      ? SlatePublicToolInvocationHandler<InputType, OutputType>
+      : SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'tool') {
       throw new SlateDeclarationError('handleInvocation can only be set for tool actions');
     }
 
     this.#toolParams = {
       type: 'tool',
-      handleInvocation: handler
+      handleInvocation: handler as SlateToolInvocationHandler<
+        ConfigType,
+        AuthType,
+        InputType,
+        OutputType
+      >
     };
 
     return this;
@@ -85,7 +168,8 @@ export class SlateActionBuilder<
     handleRequest: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
     autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
     autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
-  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+    http?: SlateWebhookHttpOptions;
+  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'trigger') {
       throw new SlateDeclarationError('handleEvent can only be set for trigger actions');
     }
@@ -96,7 +180,8 @@ export class SlateActionBuilder<
       handleEvent: props.handleEvent,
       handleRequest: props.handleRequest,
       autoRegisterWebhook: props.autoRegisterWebhook,
-      autoUnregisterWebhook: props.autoUnregisterWebhook
+      autoUnregisterWebhook: props.autoUnregisterWebhook,
+      http: props.http
     };
 
     return this;
@@ -106,7 +191,7 @@ export class SlateActionBuilder<
     options?: SlatePollingOptions;
     pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
     handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
-  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+  }): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     if (this.type !== 'trigger') {
       throw new SlateDeclarationError('handleEvent can only be set for trigger actions');
     }
@@ -123,6 +208,16 @@ export class SlateActionBuilder<
   }
 
   build() {
+    let scopes = this.#scopes ?? this.params.scopes;
+    if (scopes) {
+      validateScopes(scopes);
+    }
+    let authMethods = this.validateAuthMethods(this.#authMethods ?? this.params.authMethods);
+
+    if (this.isPublicTool && authMethods) {
+      throw new SlateDeclarationError('Public tools cannot require authentication methods');
+    }
+
     if (!this.#inputSchema) {
       throw new SlateDeclarationError('Input schema is not defined');
     }
@@ -138,6 +233,9 @@ export class SlateActionBuilder<
 
     return this.factory({
       ...this.params,
+      scopes,
+      authMethods,
+      isPublic: this.isPublicTool === true,
       configSchema: this.#configSchema,
       authSchema: this.#authSchema,
       inputSchema: this.#inputSchema,

package/src/action/directUpload.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { uploadAttachmentDirect } from './directUpload';
+
+let live = {
+  token: 'live-token',
+  baseUrl: 'https://hub.example/',
+  maxAttachmentSizeBytes: 10
+};
+
+describe('uploadAttachmentDirect', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('buffers streams and uploads them with their exact content length', async () => {
+    let fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(
+        Response.json({
+          attachments: [
+            { referenceId: 'attachment-reference', uploadUrl: 'https://s3.example/upload' }
+          ]
+        })
+      )
+      .mockResolvedValueOnce(new Response(null, { status: 200 }));
+    let body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array([1, 2]));
+        controller.enqueue(new Uint8Array([3, 4, 5]));
+        controller.close();
+      }
+    });
+
+    await expect(
+      uploadAttachmentDirect({ live, body, mimeType: 'application/octet-stream' })
+    ).resolves.toEqual({
+      mimeType: 'application/octet-stream',
+      content: { type: 'upload_reference', referenceId: 'attachment-reference' }
+    });
+
+    expect(JSON.parse(fetchSpy.mock.calls[0]![1]!.body as string)).toEqual({
+      attachments: [{ mimeType: 'application/octet-stream', sizeBytes: 5 }]
+    });
+    let upload = fetchSpy.mock.calls[1]!;
+    expect(upload[0]).toBe('https://s3.example/upload');
+    expect(upload[1]).toMatchObject({
+      method: 'PUT',
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-length': '5'
+      }
+    });
+    expect(upload[1]!.body).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+    expect(upload[1]).not.toHaveProperty('duplex');
+  });
+
+  it('rejects an oversized stream before registering an upload', async () => {
+    let fetchSpy = vi.spyOn(globalThis, 'fetch');
+    let body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array(11));
+      }
+    });
+
+    await expect(uploadAttachmentDirect({ live, body })).rejects.toThrow(
+      'Attachment exceeds the maximum size of 10 bytes'
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});