@slates/provider 1.0.0-rc.6 → 1.0.0-rc.8

package/src/error/service.ts

@@ -0,0 +1,160 @@
+import { isServiceError } from '@lowerdeck/error';
+import type { ErrorData, ErrorRecord, ServiceError } from '@lowerdeck/error';
+import { DEFAULT_CODE, SERVICE_ERROR_CODE_MAP } from './defaults';
+import type { SlateErrorInput, SlateErrorIssue, SlateServiceErrorData } from './types';
+import { cleanRecord, isRecord, normalizeKind, normalizeRetryable, sanitizeForBaggage } from './utils';
+
+let SERVICE_ERROR_DATA_RESERVED_KEYS = new Set([
+  'status',
+  'code',
+  'message',
+  'hint',
+  'description',
+  'reason',
+  'errors',
+  'object',
+  'ok'
+]);
+
+let isStructuredValue = (value: unknown): value is Record<string, unknown> | Function =>
+  (typeof value === 'object' || typeof value === 'function') && value !== null;
+
+let mapServiceErrorCodeByStatus = (status?: number) => {
+  if (status === 400) return 'request.bad';
+  if (status === 401) return 'auth.required';
+  if (status === 402) return 'payment.required';
+  if (status === 403) return 'permission.denied';
+  if (status === 404) return 'resource.not_found';
+  if (status === 406) return 'request.not_acceptable';
+  if (status === 409) return 'resource.conflict';
+  if (status === 410) return 'resource.gone';
+  if (status === 412) return 'request.precondition_failed';
+  if (status === 429) return 'request.rate_limited';
+  if (status === 501) return 'operation.not_implemented';
+  if (status === 504) return 'internal.timeout';
+  if (status && status >= 500) return 'internal.unexpected';
+  return DEFAULT_CODE;
+};
+
+let normalizeServiceErrorIssues = (errors: unknown): SlateErrorIssue[] | undefined => {
+  if (!Array.isArray(errors)) return undefined;
+
+  let issues = errors.map(error => {
+    if (!isRecord(error)) {
+      return {
+        message: String(error)
+      };
+    }
+
+    let path = Array.isArray(error.path)
+      ? error.path.map(entry => String(entry))
+      : undefined;
+
+    return {
+      ...error,
+      path,
+      code: typeof error.code === 'string' ? error.code : undefined,
+      message:
+        typeof error.message === 'string'
+          ? error.message
+          : typeof error.hint === 'string'
+            ? error.hint
+            : 'Validation issue'
+    };
+  });
+
+  return issues.length > 0 ? issues : undefined;
+};
+
+let getServiceErrorBaggage = (data: SlateServiceErrorData) => {
+  let extraEntries = Object.entries(data).filter(([key]) => !SERVICE_ERROR_DATA_RESERVED_KEYS.has(key));
+
+  return cleanRecord({
+    serviceError: {
+      code: data.code,
+      status: data.status,
+      hint: data.hint,
+      description: data.description,
+      reason: data.reason
+    },
+    ...(extraEntries.length > 0
+      ? {
+          serviceErrorData: sanitizeForBaggage(Object.fromEntries(extraEntries))
+        }
+      : {})
+  });
+};
+
+export let mapServiceErrorCode = (code: string, status?: number) =>
+  SERVICE_ERROR_CODE_MAP[code] ?? mapServiceErrorCodeByStatus(status);
+
+export let isServiceErrorData = (value: unknown): value is SlateServiceErrorData =>
+  isRecord(value) &&
+  typeof value.status === 'number' &&
+  typeof value.code === 'string' &&
+  typeof value.message === 'string' &&
+  !('config' in value) &&
+  !('request' in value) &&
+  !('response' in value) &&
+  !('isAxiosError' in value);
+
+export let getServiceErrorData = (error: unknown): SlateServiceErrorData | null => {
+  if (isServiceError(error)) {
+    return isServiceErrorData(error.data) ? error.data : null;
+  }
+
+  if (isServiceErrorData(error)) {
+    return error;
+  }
+
+  if (isStructuredValue(error) && 'data' in error && isServiceErrorData(error.data)) {
+    return error.data;
+  }
+
+  if (isStructuredValue(error) && 'toResponse' in error && typeof error.toResponse === 'function') {
+    let response = error.toResponse();
+    return isServiceErrorData(response) ? response : null;
+  }
+
+  return null;
+};
+
+export let mapServiceErrorToSlateErrorInput = (
+  error:
+    | ServiceError<ErrorRecord<any, any>>
+    | ErrorRecord<any, any>
+    | ErrorData<any, any>
+    | SlateServiceErrorData,
+  defaults: Partial<SlateErrorInput> = {}
+): SlateErrorInput => {
+  let data = getServiceErrorData(error);
+  if (!data) {
+    return {
+      code: defaults.code ?? DEFAULT_CODE,
+      message: defaults.message ?? 'An unexpected internal error occurred.',
+      kind: defaults.kind,
+      retryable: defaults.retryable,
+      status: defaults.status,
+      provider: defaults.provider,
+      upstream: defaults.upstream,
+      baggage: defaults.baggage
+    };
+  }
+
+  let code = defaults.code ?? mapServiceErrorCode(data.code, data.status);
+
+  return {
+    code,
+    message: defaults.message ?? data.message,
+    kind: defaults.kind ?? normalizeKind(code),
+    retryable: defaults.retryable ?? normalizeRetryable(code),
+    status: defaults.status ?? data.status,
+    issues: defaults.issues ?? normalizeServiceErrorIssues(data.errors),
+    provider: defaults.provider,
+    upstream: defaults.upstream,
+    baggage: cleanRecord({
+      ...(defaults.baggage ?? {}),
+      ...getServiceErrorBaggage(data)
+    })
+  };
+};

package/src/error/types.ts

@@ -0,0 +1,73 @@
+import type { AxiosError, AxiosResponse } from 'axios';
+import type { SlateError } from './base';
+
+export type SlateErrorKind =
+  | 'declaration'
+  | 'validation'
+  | 'request'
+  | 'auth'
+  | 'config'
+  | 'resource'
+  | 'payment'
+  | 'upstream'
+  | 'transport'
+  | 'internal';
+
+export interface SlateErrorIssue {
+  path?: string[];
+  code?: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+export interface SlateErrorProviderInfo {
+  key?: string;
+  service?: string;
+  operation?: string;
+}
+
+export interface SlateErrorUpstreamInfo {
+  status?: number;
+  code?: string;
+  type?: string;
+  requestId?: string;
+  method?: string;
+  url?: string;
+}
+
+export interface SlateErrorResponse {
+  code: string;
+  message: string;
+  kind: SlateErrorKind;
+  retryable?: boolean;
+  status?: number;
+  issues?: SlateErrorIssue[];
+  provider?: SlateErrorProviderInfo;
+  upstream?: SlateErrorUpstreamInfo;
+  baggage?: Record<string, unknown>;
+}
+
+export interface SlateErrorInput extends Omit<SlateErrorResponse, 'kind'> {
+  kind?: SlateErrorKind;
+  cause?: unknown;
+}
+
+export interface SlateAxiosErrorOptions {
+  defaults?: Partial<SlateErrorResponse>;
+  extractResponseData?: (response: AxiosResponse) => unknown;
+  mapAxiosError?: (
+    error: AxiosError,
+    inferred: SlateErrorResponse
+  ) => SlateError | Partial<SlateErrorResponse> | void;
+}
+
+export interface SlateServiceErrorData {
+  status: number;
+  code: string;
+  message: string;
+  hint?: string;
+  description?: string;
+  reason?: string;
+  errors?: unknown;
+  [key: string]: unknown;
+}

package/src/error/utils.ts

@@ -0,0 +1,155 @@
+import { DEFAULT_CODE, DEFAULT_MESSAGES } from './defaults';
+import type {
+  SlateErrorInput,
+  SlateErrorKind,
+  SlateErrorProviderInfo,
+  SlateErrorResponse,
+  SlateErrorUpstreamInfo
+} from './types';
+
+export let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+export let normalizeKind = (code: string, kind?: SlateErrorKind): SlateErrorKind => {
+  if (kind) return kind;
+  if (code.startsWith('declaration.')) return 'declaration';
+  if (code.startsWith('input.')) return 'validation';
+  if (code.startsWith('request.')) return 'request';
+  if (code.startsWith('config.')) return 'config';
+  if (code.startsWith('auth.') || code.startsWith('permission.')) return 'auth';
+  if (code.startsWith('resource.')) return 'resource';
+  if (code.startsWith('payment.')) return 'payment';
+  if (code.startsWith('transport.')) return 'transport';
+  if (code.startsWith('upstream.')) return 'upstream';
+  return 'internal';
+};
+
+export let normalizeStatus = (code: string, status?: number) => {
+  if (status) return status;
+  if (code === 'input.invalid' || code === 'request.bad' || code === 'config.invalid')
+    return 400;
+  if (code === 'request.invalid_version') return 400;
+  if (code === 'auth.required' || code === 'auth.invalid' || code === 'auth.expired')
+    return 401;
+  if (code === 'payment.required') return 402;
+  if (code === 'permission.denied') return 403;
+  if (code === 'resource.not_found') return 404;
+  if (code === 'resource.conflict') return 409;
+  if (code === 'resource.gone') return 410;
+  if (code === 'request.not_acceptable') return 406;
+  if (code === 'request.precondition_failed') return 412;
+  if (code === 'request.rate_limited' || code === 'upstream.rate_limited') return 429;
+  if (code === 'operation.not_implemented') return 501;
+  if (code === 'upstream.invalid_request') return 400;
+  if (code === 'upstream.timeout' || code === 'internal.timeout') return 504;
+  if (code === 'upstream.unavailable') return 503;
+  if (code === 'upstream.error') return 502;
+  return undefined;
+};
+
+export let normalizeRetryable = (code: string, retryable?: boolean) => {
+  if (typeof retryable === 'boolean') return retryable;
+  return (
+    code === 'request.rate_limited' ||
+    code === 'upstream.rate_limited' ||
+    code === 'upstream.timeout' ||
+    code === 'upstream.network_error' ||
+    code === 'upstream.unavailable' ||
+    code === 'upstream.error' ||
+    code === 'transport.invoke_failed' ||
+    code === 'internal.timeout'
+  );
+};
+
+export let getDefaultMessage = (code: string, message?: string) => {
+  if (message && message.trim()) return message;
+  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE];
+};
+
+export let cleanRecord = <Value extends Record<string, unknown> | undefined>(value: Value) => {
+  if (!value) return undefined;
+
+  let entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+  if (entries.length === 0) return undefined;
+  return Object.fromEntries(entries) as Value;
+};
+
+export let mergeRecords = (
+  left?: Record<string, unknown>,
+  right?: Record<string, unknown>
+): Record<string, unknown> | undefined => {
+  if (!left && !right) return undefined;
+  return cleanRecord({
+    ...(left ?? {}),
+    ...(right ?? {})
+  });
+};
+
+export let mergeSlateErrorData = (
+  base: SlateErrorResponse,
+  override?: Partial<SlateErrorResponse>
+): SlateErrorResponse => {
+  if (!override) return base;
+
+  return {
+    ...base,
+    ...override,
+    provider: cleanRecord({
+      ...(base.provider ?? {}),
+      ...(override.provider ?? {})
+    }) as SlateErrorProviderInfo | undefined,
+    upstream: cleanRecord({
+      ...(base.upstream ?? {}),
+      ...(override.upstream ?? {})
+    }) as SlateErrorUpstreamInfo | undefined,
+    baggage: mergeRecords(base.baggage, override.baggage),
+    issues: override.issues ?? base.issues
+  };
+};
+
+export let sanitizeForBaggage = (value: unknown, depth = 0): unknown => {
+  if (value == null) return value;
+  if (depth >= 4) return '[truncated]';
+  if (typeof value === 'string') {
+    return value.length > 2_000 ? `${value.slice(0, 2_000)}...[truncated]` : value;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 20).map(item => sanitizeForBaggage(item, depth + 1));
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .slice(0, 30)
+        .map(([key, entry]) => [key, sanitizeForBaggage(entry, depth + 1)])
+    );
+  }
+  return String(value);
+};
+
+export let normalizeSlateErrorInput = (input: SlateErrorInput): SlateErrorResponse => {
+  let code = input.code || DEFAULT_CODE;
+  return {
+    code,
+    message: getDefaultMessage(code, input.message),
+    kind: normalizeKind(code, input.kind),
+    retryable: normalizeRetryable(code, input.retryable),
+    status: normalizeStatus(code, input.status ?? input.upstream?.status),
+    issues: input.issues,
+    provider: cleanRecord(input.provider as Record<string, unknown> | undefined) as
+      | SlateErrorProviderInfo
+      | undefined,
+    upstream: cleanRecord({
+      ...input.upstream,
+      status: input.upstream?.status ?? input.status
+    }) as SlateErrorUpstreamInfo | undefined,
+    baggage: cleanRecord(input.baggage)
+  };
+};
+
+export let isSlateErrorResponse = (error: unknown): error is SlateErrorResponse => {
+  if (!isRecord(error)) return false;
+  return typeof error.code === 'string' && typeof error.message === 'string';
+};

package/src/logger/logger.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { SlateLogger, type SlateLogEntry } from './logger';
+
+let flushLogs = async () => {
+  await new Promise(resolve => setTimeout(resolve, 20));
+};
+
+describe('SlateLogger', () => {
+  it('keeps a readable message and structured data for object logs', async () => {
+    let entries: SlateLogEntry[] = [];
+    let logger = new SlateLogger([
+      batch => {
+        entries.push(...batch);
+      }
+    ]);
+
+    logger.info({
+      message: 'Invoking tool action',
+      providerId: 'demo-slate',
+      actionId: 'echo',
+      phase: 'start'
+    });
+
+    await flushLogs();
+
+    expect(entries[0]).toMatchObject({
+      type: 'info',
+      message: 'Invoking tool action',
+      data: {
+        providerId: 'demo-slate',
+        actionId: 'echo',
+        phase: 'start'
+      }
+    });
+  });
+
+  it('captures error details as structured metadata', async () => {
+    let entries: SlateLogEntry[] = [];
+    let logger = new SlateLogger([
+      batch => {
+        entries.push(...batch);
+      }
+    ]);
+
+    logger.error(new Error('boom'));
+
+    await flushLogs();
+
+    expect(entries[0]?.message).toBe('Error: boom');
+    expect(entries[0]?.data).toMatchObject({
+      error: {
+        name: 'Error',
+        message: 'boom'
+      }
+    });
+  });
+});

package/src/logger/logger.ts

@@ -1,6 +1,7 @@
 import { encode } from '@toon-format/toon';
 
 export type SlateLogType = 'info' | 'warn' | 'error' | 'progress';
+export type SlateLogFields = Record<string, unknown>;
 
 export type SlateLogMessageInput =
   | string
@@ -12,22 +13,79 @@ export type SlateLogMessageInput =
   | object
   | SlateLogMessageInput[];
 
-let formatMessage = (message: SlateLogMessageInput): string => {
+let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let normalizeMessage = (
+  message: SlateLogMessageInput
+): {
+  message: string;
+  data?: SlateLogFields;
+} => {
+  if (Array.isArray(message)) {
+    let parts = message.map(part => normalizeMessage(part));
+    let combinedMessage = parts
+      .map(part => part.message)
+      .filter(Boolean)
+      .join(' ')
+      .trim();
+
+    let dataParts = parts
+      .map(part => {
+        if (part.data) {
+          return {
+            message: part.message,
+            ...part.data
+          };
+        }
+
+        return part.message;
+      })
+      .filter(Boolean);
+
+    return {
+      message: combinedMessage || 'Log entry',
+      data: dataParts.length > 0 ? { parts: dataParts } : undefined
+    };
+  }
+
   if (typeof message === 'object') {
-    if (message === null) return 'null';
+    if (message === null) return { message: 'null' };
     if (message instanceof Error) {
-      return `[ERROR]: ${message.name}: ${message.message}\n${message.stack}`;
+      return {
+        message: `${message.name}: ${message.message}`,
+        data: {
+          error: {
+            name: message.name,
+            message: message.message,
+            stack: message.stack
+          }
+        }
+      };
     }
-    return encode(message);
+
+    if (isRecord(message) && typeof message.message === 'string') {
+      let { message: text, ...data } = message;
+      return {
+        message: text || 'Log entry',
+        data: Object.keys(data).length > 0 ? data : undefined
+      };
+    }
+
+    return {
+      message: encode(message),
+      data: isRecord(message) ? message : undefined
+    };
   }
 
-  return String(message);
+  return { message: String(message) };
 };
 
 export interface SlateLogEntry {
   type: SlateLogType;
   message: string;
   timestamp: Date;
+  data?: SlateLogFields;
 }
 
 export type SlateLogListener = (entries: SlateLogEntry[]) => void;
@@ -44,9 +102,10 @@ export class SlateLogger {
   private flush() {
     if (this.#timer) clearTimeout(this.#timer);
     if (this.#logs.length === 0) return;
+    let logs = this.#logs.splice(0);
 
     for (let listener of this.#listeners) {
-      listener(this.#logs);
+      listener(logs);
     }
   }
 
@@ -59,27 +118,29 @@ export class SlateLogger {
   }
 
   log(type: SlateLogType, message: SlateLogMessageInput) {
+    let normalized = normalizeMessage(message);
     this.#logs.push({
       type,
       timestamp: new Date(),
-      message: formatMessage(message)
+      message: normalized.message,
+      data: normalized.data
     });
     this.scheduleFlush();
   }
 
   info(...message: SlateLogMessageInput[]) {
-    this.log('info', message.flat());
+    this.log('info', message.length === 1 ? message[0]! : message.flat());
   }
 
   warn(...message: SlateLogMessageInput[]) {
-    this.log('warn', message.flat());
+    this.log('warn', message.length === 1 ? message[0]! : message.flat());
   }
 
   error(...message: SlateLogMessageInput[]) {
-    this.log('error', message.flat());
+    this.log('error', message.length === 1 ? message[0]! : message.flat());
   }
 
   progress(...message: SlateLogMessageInput[]) {
-    this.log('progress', message.flat());
+    this.log('progress', message.length === 1 ? message[0]! : message.flat());
   }
 }

package/src/specification/slate.ts

@@ -1,5 +1,5 @@
-import { SlateTool, SlateTrigger } from '../action';
-import { SlateSpecification } from './specification';
+import type { SlateTool, SlateTrigger } from '../action';
+import type { SlateSpecification } from './specification';
 
 export class Slate<ConfigType extends {}, AuthType extends {}> {
   private constructor(

package/src/specification/specification.ts

@@ -1,6 +1,6 @@
 import z from 'zod';
-import { SlateAuth } from '../auth';
-import { SlateConfig } from '../config';
+import type { SlateAuth } from '../auth';
+import type { SlateConfig } from '../config';
 
 export interface SlateSpecificationParameters {
   key: string;