@slates/provider 1.0.0-rc.1 → 1.0.0-rc.10

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.10",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "src/**",
+    "dist/**",
+    "README.md",
+    "package.json"
+  ],
   "author": "Tobias Herber",
-  "license": "Apache 2",
+  "license": "FSL 1.1",
   "type": "module",
   "source": "src/index.ts",
   "exports": {
@@ -17,20 +23,22 @@
   "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"
   },
   "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
     "@toon-format/toon": "^2.1.0",
     "axios": "^1.13.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,18 @@
-import { z } from 'zod';
-import { SlateContext } from '../context';
-import { SlateSpecification } from '../specification/specification';
+import type { z } from 'zod';
+import type { SlateContext } from '../context';
+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 +25,7 @@ export interface SlateActionParameters {
     [key: string]: boolean | undefined;
   };
   metadata?: Record<string, any>;
+  scopes?: SlateActionScopes;
 }
 
 export type SlateToolInvocationHandler<
@@ -26,6 +36,7 @@ export type SlateToolInvocationHandler<
 > = (context: SlateContext<ConfigType, AuthType, InputType>) => Promise<{
   output: OutputType;
   message: string;
+  attachments?: SlateAttachment[];
 }>;
 
 export type SlateTriggerMappingHandler<
@@ -188,4 +199,8 @@ export abstract class SlateAction<
   get metadata() {
     return this._params.metadata;
   }
+
+  get scopes() {
+    return this._params.scopes;
+  }
 }

package/src/action/attachment.ts

@@ -0,0 +1,41 @@
+export interface SlateAttachmentUrlContent {
+  type: 'url';
+  url: string;
+}
+
+export interface SlateAttachmentInlineContent {
+  type: 'content';
+  encoding: 'base64' | 'utf-8';
+  content: string;
+}
+
+export interface SlateAttachment {
+  mimeType?: string;
+  content: SlateAttachmentUrlContent | SlateAttachmentInlineContent;
+}
+
+export let createUrlAttachment = (url: string, mimeType?: string): SlateAttachment => ({
+  mimeType,
+  content: {
+    type: 'url',
+    url
+  }
+});
+
+export let createBase64Attachment = (content: string, mimeType?: string): SlateAttachment => ({
+  mimeType,
+  content: {
+    type: 'content',
+    encoding: 'base64',
+    content
+  }
+});
+
+export let createTextAttachment = (content: string, mimeType?: string): SlateAttachment => ({
+  mimeType,
+  content: {
+    type: 'content',
+    encoding: 'utf-8',
+    content
+  }
+});

package/src/action/builder.ts

@@ -1,9 +1,10 @@
-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,
+  SlateActionScopes,
   SlateActionParameters,
   SlateActionParametersTool,
   SlateActionParametersTrigger,
@@ -16,6 +17,7 @@ import {
   SlateTriggerWebhookAutoUnregistrationHandler,
   SlateTriggerWebhookRequestHandler
 } from './action';
+import { validateScopes } from './scopes';
 
 export class SlateActionBuilder<
   Type extends SlateActionType,
@@ -29,6 +31,7 @@ export class SlateActionBuilder<
   #authSchema: z.ZodType<AuthType>;
   #inputSchema: z.ZodType<InputType> | null = null;
   #outputSchema: z.ZodType<OutputType> | null = null;
+  #scopes: SlateActionScopes | undefined;
 
   #toolParams: SlateActionParametersTool<ConfigType, AuthType, InputType, OutputType> | null =
     null;
@@ -41,7 +44,7 @@ export class SlateActionBuilder<
 
   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>
@@ -65,6 +68,14 @@ export class SlateActionBuilder<
     return this as any;
   }
 
+  scopes(
+    scopes: SlateActionScopes
+  ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
+    validateScopes(scopes);
+    this.#scopes = scopes;
+    return this;
+  }
+
   handleInvocation(
     handler: SlateToolInvocationHandler<ConfigType, AuthType, InputType, OutputType>
   ): SlateActionBuilder<Type, ConfigType, AuthType, InputType, OutputType, Result> {
@@ -123,6 +134,11 @@ export class SlateActionBuilder<
   }
 
   build() {
+    let scopes = this.#scopes ?? this.params.scopes;
+    if (scopes) {
+      validateScopes(scopes);
+    }
+
     if (!this.#inputSchema) {
       throw new SlateDeclarationError('Input schema is not defined');
     }
@@ -138,6 +154,7 @@ export class SlateActionBuilder<
 
     return this.factory({
       ...this.params,
+      scopes,
       configSchema: this.#configSchema,
       authSchema: this.#authSchema,
       inputSchema: this.#inputSchema,

package/src/action/index.ts

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

package/src/action/scopes.test.ts

@@ -0,0 +1,77 @@
+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,101 @@
+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<
@@ -36,7 +40,7 @@ export class SlateTool<
     params: SlateActionParameters
   ) {
     return new SlateActionBuilder('tool', spec, params, params => {
-      if (params.type != 'tool') throw new Error('Invalid action type for tool');
+      if (params.type !== 'tool') throw new Error('Invalid action type for tool');
       return new SlateTool(spec, params.inputSchema, params.outputSchema, params);
     });
   }

package/src/action/trigger.ts

@@ -1,18 +1,18 @@
-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
 } from './action';
 import { SlateActionBuilder } from './builder';
 
-export const SlateDefaultPollingIntervalSeconds = 60 * 10;
+export let SlateDefaultPollingIntervalSeconds = 60 * 10;
 
 export interface SlateTriggerParameters<
   ConfigType extends {},
@@ -72,7 +72,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);
     });
   }

package/src/auth/auth.ts

@@ -1,5 +1,5 @@
-import z from 'zod';
-import { SlateAuthType } from './types';
+import type z from 'zod';
+import type { SlateAuthType } from './types';
 
 export class SlateAuth<OutputType extends {} = {}> {
   #outputSchema: z.ZodType<OutputType> | null = null;
@@ -68,7 +68,7 @@ export class SlateAuth<OutputType extends {} = {}> {
   }
 
   get authStack() {
-    return this.#authStack.filter(a => a.type != 'auth.none');
+    return this.#authStack.filter(a => a.type !== 'auth.none');
   }
 
   get outputSchema() {

package/src/auth/types.ts

@@ -1,4 +1,4 @@
-import z from 'zod';
+import type z from 'zod';
 
 export type SlateAuthWithOauth<
   InputType extends {},
@@ -16,6 +16,7 @@ export type SlateAuthWithOauth<
   scopes: {
     title: string;
     description?: string;
+    defaultChecked?: boolean;
     scope: string;
   }[];
 
@@ -24,7 +25,7 @@ export type SlateAuthWithOauth<
   onInputChanged?: (params: {
     previousInput: InputType | null;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
@@ -38,6 +39,7 @@ export type SlateAuthWithOauth<
   }) => Promise<{
     url: string;
     input?: InputType;
+    callbackState?: Record<string, any>;
   }>;
 
   handleCallback: (ctx: {
@@ -48,9 +50,11 @@ export type SlateAuthWithOauth<
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    callbackState: Record<string, any>;
   }) => Promise<{
     output: OutputType;
     input?: InputType;
+    scopes?: string[];
   }>;
 
   handleTokenRefresh?: (ctx: {
@@ -82,7 +86,7 @@ export type SlateAuthWithToken<InputType extends {}, OutputType extends { token?
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
@@ -104,7 +108,7 @@ export type SlateAuthWithServiceAccount<InputType extends {}, OutputType extends
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
@@ -126,7 +130,7 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
@@ -135,7 +139,7 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
   }>;
 };
 
-export type SlateAuthWithNone<InputType extends {}, OutputType extends {}> = {
+export type SlateAuthWithNone<_InputType extends {}, _OutputType extends {}> = {
   type: 'auth.none';
 
   name: string;

package/src/axios/index.ts

@@ -1,14 +1,22 @@
-import baseAxios, { CreateAxiosDefaults } from 'axios';
+import type { AxiosInstance, CreateAxiosDefaults, InternalAxiosRequestConfig } from 'axios';
+import baseAxios, { getAdapter, isAxiosError } from 'axios';
 import { getCurrentContext } from '../context/hook';
+import type { SlateAxiosErrorOptions } from '../error';
+import { SlateError } from '../error';
+import {
+  attachHttpTraceDraft,
+  recordHttpTraceFromError,
+  recordHttpTraceFromResponse
+} from './trace';
 
-export let createAxios = (config?: CreateAxiosDefaults) => {
-  let instance = baseAxios.create({
-    ...config,
-    headers: {
-      ...config?.headers
-    }
-  });
+export interface SlateAxiosDefaults extends CreateAxiosDefaults {
+  errorMapping?: SlateAxiosErrorOptions;
+}
 
+let applySlateInterceptors = (
+  instance: AxiosInstance,
+  errorMapping?: SlateAxiosErrorOptions
+) => {
   instance.interceptors.request.use(
     request => {
       // Has to be called in the context of an action execution
@@ -16,12 +24,51 @@ export let createAxios = (config?: CreateAxiosDefaults) => {
       let spec = ctx.specification;
 
       request.headers.set('User-Agent', `slates.dev@1.0.0/${spec.key}`);
+      request.headers.set('X-Slates-Provider', spec.key);
 
-      return request;
+      let tracedRequest = attachHttpTraceDraft(request, ctx) as InternalAxiosRequestConfig & {
+        __slatesTraceAdapterWrapped?: boolean;
+      };
+
+      if (!tracedRequest.__slatesTraceAdapterWrapped) {
+        let adapter = getAdapter(tracedRequest.adapter ?? baseAxios.defaults.adapter);
+        tracedRequest.adapter = async config => {
+          try {
+            let response = await adapter(config);
+            return recordHttpTraceFromResponse(response);
+          } catch (error) {
+            if (isAxiosError(error)) {
+              recordHttpTraceFromError(error);
+            }
+            throw error;
+          }
+        };
+        tracedRequest.__slatesTraceAdapterWrapped = true;
+      }
+
+      return tracedRequest;
     },
     error => Promise.reject(error)
   );
 
+  instance.interceptors.response.use(
+    response => response,
+    error => Promise.reject(SlateError.fromAxios(error, errorMapping))
+  );
+};
+
+applySlateInterceptors(baseAxios);
+
+export let createAxios = (config?: SlateAxiosDefaults) => {
+  let { errorMapping, ...axiosConfig } = config ?? {};
+  let instance = baseAxios.create({
+    ...axiosConfig,
+    headers: {
+      ...axiosConfig.headers
+    }
+  });
+
+  applySlateInterceptors(instance, errorMapping);
   return instance;
 };