@slates/provider 1.0.0-rc.17 → 1.0.0-rc.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.17",
+  "version": "1.0.0-rc.19",
   "publishConfig": {
     "access": "public"
   },
@@ -34,6 +34,7 @@
     "@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": {
@@ -42,4 +43,4 @@
     "typescript": "5.8.2",
     "vitest": "^3.1.2"
   }
-}
+}

package/src/action/action.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod';
-import type { SlateContext } from '../context';
+import type { SlateContext, SlatePublicContext } from '../context';
 import type { SlateActionDocsReference } from '../docs';
 import type { SlateSpecification } from '../specification/specification';
 import type { SlateAttachment } from './attachment';
@@ -29,6 +29,8 @@ export interface SlateActionParameters {
   scopes?: SlateActionScopes;
   authMethods?: string[];
   docs?: SlateActionDocsReference[];
+  adapter?: string | null;
+  isPublic?: boolean;
 }
 
 export type SlateToolInvocationHandler<
@@ -42,6 +44,14 @@ export type SlateToolInvocationHandler<
   attachments?: SlateAttachment[];
 }>;
 
+export type SlatePublicToolInvocationHandler<InputType extends {}, OutputType extends {}> = (
+  context: SlatePublicContext<InputType>
+) => Promise<{
+  output: OutputType;
+  message: string;
+  attachments?: SlateAttachment[];
+}>;
+
 export type SlateTriggerMappingHandler<
   ConfigType extends {},
   AuthType extends {},
@@ -258,4 +268,12 @@ export abstract class SlateAction<
   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

@@ -1,6 +1,10 @@
 export interface SlateAttachmentUrlContent {
   type: 'url';
   url: string;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  refreshReference?: unknown;
+  refreshAt?: string;
 }
 
 export interface SlateAttachmentInlineContent {
@@ -9,21 +13,58 @@ export interface SlateAttachmentInlineContent {
   content: string;
 }
 
+export interface SlateAttachmentUploadReferenceContent {
+  type: 'upload_reference';
+  referenceId: string;
+}
+
 export interface SlateAttachment {
   mimeType?: string;
-  content: SlateAttachmentUrlContent | SlateAttachmentInlineContent;
+  attachmentHash?: string;
+  content:
+    | SlateAttachmentUrlContent
+    | SlateAttachmentInlineContent
+    | SlateAttachmentUploadReferenceContent;
 }
 
-export let createUrlAttachment = (url: string, mimeType?: string): SlateAttachment => ({
-  mimeType,
-  content: {
-    type: 'url',
-    url
+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');
   }
-});
 
-export let createBase64Attachment = (content: string, mimeType?: string): SlateAttachment => ({
+  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',
@@ -31,8 +72,13 @@ export let createBase64Attachment = (content: string, mimeType?: string): SlateA
   }
 });
 
-export let createTextAttachment = (content: string, mimeType?: string): SlateAttachment => ({
+export let createTextAttachment = (
+  content: string,
+  mimeType?: string,
+  attachmentHash?: string
+): SlateAttachment => ({
   mimeType,
+  attachmentHash,
   content: {
     type: 'content',
     encoding: 'utf-8',

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

@@ -10,6 +10,7 @@ import type {
   SlateActionScopes,
   SlateActionType,
   SlatePollingOptions,
+  SlatePublicToolInvocationHandler,
   SlateToolInvocationHandler,
   SlateTriggerMappingHandler,
   SlateTriggerPollingHandler,
@@ -26,7 +27,8 @@ 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>;
@@ -43,6 +45,7 @@ export class SlateActionBuilder<
     InputType,
     OutputType
   > | null = null;
+  #interfaceLocked = false;
 
   constructor(
     private readonly type: Type,
@@ -50,7 +53,8 @@ export class SlateActionBuilder<
     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;
@@ -58,21 +62,58 @@ 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> {
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result, IsPublic> {
     validateScopes(scopes);
     this.#scopes = scopes;
     return this;
@@ -80,7 +121,11 @@ export class SlateActionBuilder<
 
   authMethods(
     authMethods: string[]
-  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+  ): 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;
   }
@@ -97,15 +142,22 @@ export class SlateActionBuilder<
   }
 
   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;
@@ -117,7 +169,7 @@ export class SlateActionBuilder<
     autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
     autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
     http?: SlateWebhookHttpOptions;
-  }): 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');
     }
@@ -139,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');
     }
@@ -162,6 +214,10 @@ export class SlateActionBuilder<
     }
     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');
     }
@@ -179,6 +235,7 @@ export class SlateActionBuilder<
       ...this.params,
       scopes,
       authMethods,
+      isPublic: this.isPublicTool === true,
       configSchema: this.#configSchema,
       authSchema: this.#authSchema,
       inputSchema: this.#inputSchema,

package/src/action/directUpload.ts

@@ -0,0 +1,59 @@
+import type { SlateAttachment } from './attachment';
+
+export interface SlateLiveInvocationInfo {
+  token: string;
+  baseUrl: string;
+  maxAttachmentSizeBytes: number;
+}
+
+export interface SlateDirectUploadInput {
+  live: SlateLiveInvocationInfo;
+  mimeType?: string;
+  filename?: string;
+  body: ReadableStream<Uint8Array> | Uint8Array;
+}
+
+export let uploadAttachmentDirect = async (
+  d: SlateDirectUploadInput
+): Promise<SlateAttachment> => {
+  let baseUrl = d.live.baseUrl.replace(/\/$/, '');
+
+  let registerRes = await fetch(`${baseUrl}/slates-hub/live-invocation/attachments`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${d.live.token}`
+    },
+    body: JSON.stringify({
+      attachments: [{ mimeType: d.mimeType, filename: d.filename }]
+    })
+  });
+  if (!registerRes.ok) {
+    throw new Error(
+      `Failed to register attachment for direct upload (status ${registerRes.status})`
+    );
+  }
+
+  let { attachments } = (await registerRes.json()) as {
+    attachments: { referenceId: string; uploadUrl: string }[];
+  };
+  let registration = attachments[0];
+  if (!registration) {
+    throw new Error('Live invocation API returned no attachment registrations');
+  }
+
+  let putRes = await fetch(registration.uploadUrl, {
+    method: 'PUT',
+    ...(d.body instanceof Uint8Array ? {} : ({ duplex: 'half' } as any)),
+    headers: d.mimeType ? { 'content-type': d.mimeType } : undefined,
+    body: d.body
+  });
+  if (!putRes.ok) {
+    throw new Error(`Failed to upload attachment content (status ${putRes.status})`);
+  }
+
+  return {
+    mimeType: d.mimeType,
+    content: { type: 'upload_reference', referenceId: registration.referenceId }
+  };
+};

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 type * from './builder';
+export * from './builder';
+export * from './getFileUrlTool';
+export * from './publicTool';
 export * from './scopes';
 export * from './tool';
 export * from './trigger';

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/tool.ts

@@ -24,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>,
@@ -40,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/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];
+  }
+}