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

package/src/config/config.ts

@@ -1,4 +1,4 @@
-import z from 'zod';
+import type z from 'zod';
 
 export class SlateConfig<ConfigType extends {}> {
   #configSchema: z.ZodType<ConfigType>;
@@ -6,7 +6,7 @@ export class SlateConfig<ConfigType extends {}> {
     | ((params: {
         previousConfig: ConfigType | null;
         newConfig: ConfigType;
-      }) => { config: ConfigType | undefined } | void)
+      }) => { config: ConfigType | undefined } | undefined)
     | null = null;
   #getDefaultConfig: (() => ConfigType) | null = null;
 
@@ -29,7 +29,7 @@ export class SlateConfig<ConfigType extends {}> {
     handler: (params: {
       previousConfig: ConfigType | null;
       newConfig: ConfigType;
-    }) => { config: ConfigType | undefined } | void
+    }) => { config: ConfigType | undefined } | undefined
   ): SlateConfig<ConfigType> {
     this.#configChanged = handler;
     return this;

package/src/context/context.ts

@@ -1,10 +1,12 @@
-import { SlateLogger, SlateLogMessageInput } from '../logger';
-import { SlateSpecification } from '../specification/specification';
+import type { SlateHttpTrace } from '../axios/trace';
+import type { SlateLogger, SlateLogMessageInput } from '../logger';
+import type { SlateSpecification } from '../specification/specification';
 
 export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType extends {}> {
   #config: ConfigType;
   #input: InputType;
   #auth: AuthType;
+  #httpTraces: SlateHttpTrace[] = [];
 
   constructor(
     config: ConfigType,
@@ -50,6 +52,31 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
     return Object.freeze(this.#auth);
   }
 
+  recordHttpTrace(trace: SlateHttpTrace) {
+    this.#httpTraces.push(trace);
+  }
+
+  getHttpTraces() {
+    return this.#httpTraces.map(trace => ({
+      ...trace,
+      request: {
+        ...trace.request,
+        ...(trace.request.headers ? { headers: { ...trace.request.headers } } : {}),
+        ...(trace.request.body ? { body: { ...trace.request.body } } : {})
+      },
+      ...(trace.response
+        ? {
+            response: {
+              ...trace.response,
+              ...(trace.response.headers ? { headers: { ...trace.response.headers } } : {}),
+              ...(trace.response.body ? { body: { ...trace.response.body } } : {})
+            }
+          }
+        : {}),
+      ...(trace.error ? { error: { ...trace.error } } : {})
+    }));
+  }
+
   info(message: SlateLogMessageInput) {
     this.logger.info(message);
   }

package/src/context/hook.ts

@@ -1,12 +1,17 @@
 import { AsyncLocalStorage } from 'async_hooks';
-import { SlateContext } from './context';
+import type { SlateContext } from './context';
 
 let asyncLocalStorage = new AsyncLocalStorage<SlateContext<any, any, any>>();
 
-export let runWithContext = <ConfigType extends {}, AuthType extends {}, InputType extends {}>(
+export let runWithContext = <
+  ConfigType extends {},
+  AuthType extends {},
+  InputType extends {},
+  RV
+>(
   context: SlateContext<ConfigType, AuthType, InputType>,
-  fn: () => Promise<void>
-) => {
+  fn: () => Promise<RV>
+): Promise<RV> => {
   return asyncLocalStorage.run(context, fn);
 };
 

package/src/context/index.ts

@@ -1 +1,2 @@
 export * from './context';
+export * from './hook';

package/src/error/axios.ts

@@ -0,0 +1,220 @@
+import type { AxiosError } from 'axios';
+import { isAxiosError } from 'axios';
+import { getCurrentContext } from '../context/hook';
+import type { SlateAxiosErrorOptions, SlateErrorResponse } from './types';
+import {
+  getDefaultMessage,
+  isRecord,
+  mergeRecords,
+  normalizeKind,
+  normalizeRetryable,
+  normalizeSlateErrorInput,
+  sanitizeForBaggage
+} from './utils';
+
+let getResponseField = (value: unknown, key: string): unknown => {
+  if (!isRecord(value)) return undefined;
+  return value[key];
+};
+
+let getNestedMessage = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return value;
+  if (!isRecord(value)) return undefined;
+
+  let message = getResponseField(value, 'message');
+  if (typeof message === 'string' && message.trim()) return message;
+
+  let description = getResponseField(value, 'description');
+  if (typeof description === 'string' && description.trim()) return description;
+
+  let error = getResponseField(value, 'error');
+  if (typeof error === 'string' && error.trim()) return error;
+  if (isRecord(error)) {
+    let nested = getNestedMessage(error);
+    if (nested) return nested;
+  }
+
+  let errorDescription = getResponseField(value, 'error_description');
+  if (typeof errorDescription === 'string' && errorDescription.trim()) {
+    return errorDescription;
+  }
+
+  return undefined;
+};
+
+let getNestedCode = (value: unknown): string | undefined => {
+  if (!isRecord(value)) return undefined;
+
+  let directCode = getResponseField(value, 'code');
+  if (typeof directCode === 'string' && directCode.trim()) return directCode;
+
+  let errorCode = getResponseField(value, 'error_code');
+  if (typeof errorCode === 'string' && errorCode.trim()) return errorCode;
+
+  let type = getResponseField(value, 'type');
+  if (typeof type === 'string' && type.trim()) return type;
+
+  let error = getResponseField(value, 'error');
+  if (typeof error === 'string' && error.trim()) return error;
+  if (isRecord(error)) return getNestedCode(error);
+
+  return undefined;
+};
+
+let getNestedType = (value: unknown): string | undefined => {
+  if (!isRecord(value)) return undefined;
+
+  let type = getResponseField(value, 'type');
+  if (typeof type === 'string' && type.trim()) return type;
+
+  let error = getResponseField(value, 'error');
+  if (isRecord(error)) {
+    let nestedType = getNestedType(error);
+    if (nestedType) return nestedType;
+  }
+
+  return undefined;
+};
+
+let getHeaderValue = (headers: unknown, key: string): string | undefined => {
+  if (!headers) return undefined;
+
+  if (typeof (headers as { get?: unknown }).get === 'function') {
+    let value = (headers as { get(name: string): unknown }).get(key);
+    if (typeof value === 'string' && value.trim()) return value;
+  }
+
+  if (isRecord(headers)) {
+    for (let [headerKey, headerValue] of Object.entries(headers)) {
+      if (headerKey.toLowerCase() !== key.toLowerCase()) continue;
+      if (typeof headerValue === 'string' && headerValue.trim()) return headerValue;
+      if (Array.isArray(headerValue)) {
+        let first = headerValue.find(item => typeof item === 'string' && item.trim());
+        if (typeof first === 'string') return first;
+      }
+    }
+  }
+
+  return undefined;
+};
+
+let buildRequestUrl = (error: AxiosError) => {
+  let baseURL = error.config?.baseURL;
+  let url = error.config?.url;
+
+  if (!url) return undefined;
+  if (!baseURL) return url;
+
+  try {
+    return new URL(url, baseURL).toString();
+  } catch {
+    return url;
+  }
+};
+
+let getProviderDefaults = (): Partial<SlateErrorResponse> => {
+  try {
+    let ctx = getCurrentContext();
+    return {
+      provider: {
+        key: ctx.specification.key
+      },
+      ...(ctx.getHttpTraces().length > 0 ? { requestTraces: ctx.getHttpTraces() } : {})
+    };
+  } catch {
+    return {};
+  }
+};
+
+let inferAxiosCode = (error: AxiosError, data: unknown) => {
+  let status = error.response?.status;
+  let axiosCode = error.code?.toUpperCase();
+  let remoteCode = getNestedCode(data)?.toLowerCase();
+
+  if (
+    axiosCode === 'ECONNABORTED' ||
+    axiosCode === 'ETIMEDOUT' ||
+    status === 408 ||
+    remoteCode?.includes('timeout')
+  ) {
+    return 'upstream.timeout';
+  }
+
+  if (!error.response) {
+    return 'upstream.network_error';
+  }
+
+  if (status === 401) return 'auth.invalid';
+  if (status === 403) {
+    return remoteCode?.includes('rate') ? 'upstream.rate_limited' : 'permission.denied';
+  }
+  if (status === 404) return 'resource.not_found';
+  if (status === 409) return 'resource.conflict';
+  if (status === 422 || status === 400) return 'upstream.invalid_request';
+  if (status === 429) return 'upstream.rate_limited';
+  if (status === 502 || status === 503 || status === 504) return 'upstream.unavailable';
+  if (status && status >= 500) return 'upstream.error';
+
+  return 'upstream.error';
+};
+
+let inferAxiosMessage = (error: AxiosError, data: unknown, code: string) => {
+  return (
+    getNestedMessage(data) ??
+    error.response?.statusText ??
+    error.message ??
+    getDefaultMessage(code)
+  );
+};
+
+let inferAxiosRetryable = (error: AxiosError, code: string) => {
+  let headerValue = getHeaderValue(error.response?.headers, 'retry-after');
+  if (headerValue) return true;
+  return normalizeRetryable(code, undefined);
+};
+
+export let isAxiosErrorLike = (error: unknown): error is AxiosError => isAxiosError(error);
+
+export let inferSlateErrorFromAxios = (
+  error: AxiosError,
+  options: SlateAxiosErrorOptions = {}
+): SlateErrorResponse => {
+  let responseData = error.response
+    ? (options.extractResponseData?.(error.response) ?? error.response.data)
+    : undefined;
+
+  let code = inferAxiosCode(error, responseData);
+
+  return normalizeSlateErrorInput({
+    ...getProviderDefaults(),
+    ...options.defaults,
+    code: options.defaults?.code ?? code,
+    message: options.defaults?.message ?? inferAxiosMessage(error, responseData, code),
+    kind: options.defaults?.kind ?? normalizeKind(options.defaults?.code ?? code),
+    retryable:
+      options.defaults?.retryable ??
+      inferAxiosRetryable(error, options.defaults?.code ?? code),
+    status: options.defaults?.status ?? error.response?.status,
+    provider: {
+      ...getProviderDefaults().provider,
+      ...(options.defaults?.provider ?? {})
+    },
+    upstream: {
+      ...(options.defaults?.upstream ?? {}),
+      status: error.response?.status ?? options.defaults?.upstream?.status,
+      code: getNestedCode(responseData) ?? options.defaults?.upstream?.code,
+      type: getNestedType(responseData) ?? options.defaults?.upstream?.type,
+      requestId:
+        getHeaderValue(error.response?.headers, 'x-request-id') ??
+        getHeaderValue(error.response?.headers, 'request-id') ??
+        getHeaderValue(error.response?.headers, 'x-correlation-id') ??
+        options.defaults?.upstream?.requestId,
+      method: error.config?.method?.toUpperCase() ?? options.defaults?.upstream?.method,
+      url: buildRequestUrl(error) ?? options.defaults?.upstream?.url
+    },
+    baggage: mergeRecords(options.defaults?.baggage, {
+      axiosCode: error.code,
+      response: sanitizeForBaggage(responseData)
+    })
+  });
+};

package/src/error/base.test.ts

@@ -0,0 +1,178 @@
+import {
+  badRequestError,
+  conflictError,
+  forbiddenError,
+  goneError,
+  internalServerError,
+  invalidVersion,
+  notAcceptableError,
+  notFoundError,
+  notImplementedError,
+  paymentRequiredError,
+  preconditionFailedError,
+  timeoutError,
+  tooManyRequestsError,
+  unauthorizedError,
+  validationError
+} from '@lowerdeck/error';
+import { AxiosError, type AxiosResponse, type InternalAxiosRequestConfig } from 'axios';
+import { describe, expect, it } from 'vitest';
+import { SlateError } from './base';
+
+let createConfig = (overrides: Partial<InternalAxiosRequestConfig> = {}) =>
+  ({
+    url: '/issues',
+    method: 'get',
+    headers: {},
+    ...overrides
+  }) as InternalAxiosRequestConfig;
+
+let createResponse = (overrides: Partial<AxiosResponse> = {}) =>
+  ({
+    status: 429,
+    statusText: 'Too Many Requests',
+    headers: {
+      'x-request-id': 'req_123'
+    },
+    config: createConfig(),
+    data: {
+      error: {
+        code: 'rate_limited',
+        message: 'GitHub API rate limit exceeded',
+        type: 'rate_limit'
+      }
+    },
+    ...overrides
+  }) as AxiosResponse;
+
+describe('SlateError', () => {
+  it('maps axios responses to structured slate errors', () => {
+    let axiosError = new AxiosError(
+      'Request failed with status code 429',
+      'ERR_BAD_REQUEST',
+      createConfig(),
+      undefined,
+      createResponse()
+    );
+
+    let error = SlateError.fromAxios(axiosError, {
+      defaults: {
+        provider: {
+          service: 'github',
+          operation: 'issues.list'
+        }
+      }
+    });
+
+    expect(error).toBeInstanceOf(SlateError);
+    expect(error.code).toBe('upstream.rate_limited');
+    expect(error.status).toBe(429);
+    expect(error.retryable).toBe(true);
+    expect(error.data.provider).toEqual({
+      service: 'github',
+      operation: 'issues.list'
+    });
+    expect(error.data.upstream).toMatchObject({
+      status: 429,
+      code: 'rate_limited',
+      type: 'rate_limit',
+      requestId: 'req_123',
+      method: 'GET',
+      url: '/issues'
+    });
+    expect(error.data.baggage?.response).toBeTruthy();
+  });
+
+  it('maps transport failures without responses', () => {
+    let axiosError = new AxiosError('socket hang up', 'ECONNRESET', createConfig());
+
+    let error = SlateError.fromAxios(axiosError);
+
+    expect(error.code).toBe('upstream.network_error');
+    expect(error.kind).toBe('upstream');
+    expect(error.retryable).toBe(true);
+    expect(error.data.upstream).toMatchObject({
+      method: 'GET',
+      url: '/issues'
+    });
+  });
+
+  it('lets providers override inferred axios mappings', () => {
+    let axiosError = new AxiosError(
+      'Request failed with status code 404',
+      'ERR_BAD_REQUEST',
+      createConfig({ method: 'post', url: '/contacts' }),
+      undefined,
+      createResponse({
+        status: 404,
+        statusText: 'Not Found',
+        data: {
+          error: {
+            code: 'contact_missing',
+            message: 'Contact does not exist'
+          }
+        }
+      })
+    );
+
+    let error = SlateError.fromAxios(axiosError, {
+      mapAxiosError: (_, inferred) => ({
+        ...inferred,
+        code: 'resource.not_found',
+        message: 'Salesforce contact was not found',
+        provider: {
+          ...inferred.provider,
+          service: 'salesforce',
+          operation: 'contacts.create'
+        },
+        baggage: {
+          ...inferred.baggage,
+          entity: 'contact'
+        }
+      })
+    });
+
+    expect(error.code).toBe('resource.not_found');
+    expect(error.message).toBe('Salesforce contact was not found');
+    expect(error.data.provider).toEqual({
+      service: 'salesforce',
+      operation: 'contacts.create'
+    });
+    expect(error.data.baggage?.entity).toBe('contact');
+  });
+
+  it('maps service errors to canonical slate errors', () => {
+    let serviceErrors = [
+      [
+        validationError({ entity: 'request', errors: [], message: 'Invalid request data' }),
+        'input.invalid'
+      ],
+      [badRequestError({ message: 'Bad request' }), 'request.bad'],
+      [notFoundError('handler', 'missing'), 'resource.not_found'],
+      [unauthorizedError({ message: 'Please log in' }), 'auth.required'],
+      [forbiddenError({ message: 'Forbidden' }), 'permission.denied'],
+      [invalidVersion({ message: 'Invalid version' }), 'request.invalid_version'],
+      [conflictError({ message: 'Conflict' }), 'resource.conflict'],
+      [goneError({ message: 'Gone' }), 'resource.gone'],
+      [paymentRequiredError({ message: 'Payment required' }), 'payment.required'],
+      [
+        preconditionFailedError({ message: 'Precondition failed' }),
+        'request.precondition_failed'
+      ],
+      [notAcceptableError({ message: 'Not acceptable' }), 'request.not_acceptable'],
+      [notImplementedError({ message: 'Not implemented' }), 'operation.not_implemented'],
+      [tooManyRequestsError({ message: 'Too many requests' }), 'request.rate_limited'],
+      [timeoutError({ message: 'Timed out' }), 'internal.timeout'],
+      [internalServerError({ message: 'Internal error' }), 'internal.unexpected']
+    ] as const;
+
+    for (let [serviceError, code] of serviceErrors) {
+      let error = SlateError.fromServiceError(serviceError);
+      expect(error.code).toBe(code);
+      expect(error.data.baggage?.serviceError).toMatchObject({
+        code: serviceError.data.code,
+        status: serviceError.data.status
+      });
+    }
+  });
+});

package/src/error/base.ts

@@ -1,10 +1,116 @@
+import { inferSlateErrorFromAxios, isAxiosErrorLike } from './axios';
+import { DEFAULT_CODE } from './defaults';
+import { getServiceErrorData, mapServiceErrorToSlateErrorInput } from './service';
+import type { SlateAxiosErrorOptions, SlateErrorInput, SlateErrorResponse } from './types';
+import {
+  getDefaultMessage,
+  isSlateErrorResponse,
+  mergeRecords,
+  mergeSlateErrorData,
+  normalizeSlateErrorInput,
+  sanitizeForBaggage
+} from './utils';
+
 export class SlateError extends Error {
-  constructor(message: string) {
-    super(message);
+  cause?: unknown;
+  data: SlateErrorResponse;
+
+  constructor(input: SlateErrorInput) {
+    let normalized = normalizeSlateErrorInput(input);
+    super(normalized.message);
     this.name = 'SlateError';
+    this.data = normalized;
+    this.cause = input.cause;
+  }
+
+  get code() {
+    return this.data.code;
+  }
+
+  get kind() {
+    return this.data.kind;
+  }
+
+  get status() {
+    return this.data.status;
+  }
+
+  get retryable() {
+    return this.data.retryable;
+  }
+
+  toResponse(): SlateErrorResponse {
+    return {
+      ...this.data
+    };
+  }
+
+  toJSON(): SlateErrorResponse {
+    return this.toResponse();
   }
 
   static is(error: unknown): error is SlateError {
     return error instanceof SlateError;
   }
+
+  static fromUnknown(error: unknown, defaults: Partial<SlateErrorResponse> = {}): SlateError {
+    if (SlateError.is(error)) return error;
+    if (isSlateErrorResponse(error)) return new SlateError({ ...defaults, ...error });
+    if (getServiceErrorData(error)) return SlateError.fromServiceError(error, defaults);
+    if (isAxiosErrorLike(error)) return SlateError.fromAxios(error, { defaults });
+
+    if (error instanceof Error) {
+      return new SlateError({
+        code: defaults.code ?? DEFAULT_CODE,
+        message: error.message,
+        kind: defaults.kind,
+        retryable: defaults.retryable,
+        status: defaults.status,
+        issues: defaults.issues,
+        provider: defaults.provider,
+        upstream: defaults.upstream,
+        baggage: mergeRecords(defaults.baggage, {
+          originalName: error.name
+        }),
+        cause: error
+      });
+    }
+
+    return new SlateError({
+      code: defaults.code ?? DEFAULT_CODE,
+      message: getDefaultMessage(defaults.code ?? DEFAULT_CODE, defaults.message),
+      kind: defaults.kind,
+      retryable: defaults.retryable,
+      status: defaults.status,
+      issues: defaults.issues,
+      provider: defaults.provider,
+      upstream: defaults.upstream,
+      baggage: mergeRecords(defaults.baggage, {
+        originalValue: sanitizeForBaggage(error)
+      })
+    });
+  }
+
+  static fromServiceError(
+    error: unknown,
+    defaults: Partial<SlateErrorInput> = {}
+  ): SlateError {
+    return new SlateError(mapServiceErrorToSlateErrorInput(error as any, defaults));
+  }
+
+  static fromAxios(error: unknown, options: SlateAxiosErrorOptions = {}): SlateError {
+    if (SlateError.is(error)) return error;
+    if (getServiceErrorData(error))
+      return SlateError.fromServiceError(error, options.defaults);
+    if (!isAxiosErrorLike(error)) return SlateError.fromUnknown(error, options.defaults);
+
+    let inferred = inferSlateErrorFromAxios(error, options);
+
+    let mapped = options.mapAxiosError?.(error, inferred);
+    if (SlateError.is(mapped)) return mapped;
+
+    return new SlateError(mergeSlateErrorData(inferred, mapped ?? undefined));
+  }
 }
+
+export let createSlateError = (input: SlateErrorInput) => new SlateError(input);

package/src/error/declaration.ts

@@ -1,8 +1,13 @@
 import { SlateError } from './base';
 
 export class SlateDeclarationError extends SlateError {
-  constructor(message: string) {
-    super(`[Declaration Error]: ${message}`);
+  constructor(message: string, input: Partial<SlateError['data']> = {}) {
+    super({
+      code: 'declaration.invalid_definition',
+      kind: 'declaration',
+      message,
+      ...input
+    });
     this.name = 'SlateError.DeclarationError';
   }
 

package/src/error/defaults.ts

@@ -0,0 +1,50 @@
+export let DEFAULT_CODE = 'internal.unexpected';
+
+export let DEFAULT_MESSAGES: Record<string, string> = {
+  'declaration.invalid_definition': 'The slate definition is invalid.',
+  'context.missing': 'No Slate context is available.',
+  'input.invalid': 'The provided input is invalid.',
+  'request.bad': 'The request is invalid.',
+  'request.invalid_version': 'The requested version is invalid.',
+  'request.precondition_failed': 'The request precondition failed.',
+  'request.not_acceptable': 'The request is not acceptable.',
+  'request.rate_limited': 'Too many requests were made in a short period of time.',
+  'config.invalid': 'The provided configuration is invalid.',
+  'auth.required': 'Authentication is required.',
+  'auth.invalid': 'Authentication failed.',
+  'auth.expired': 'Authentication has expired.',
+  'permission.denied': 'Permission was denied.',
+  'resource.not_found': 'The requested resource was not found.',
+  'resource.conflict': 'The requested resource is in conflict.',
+  'resource.gone': 'The requested resource is no longer available.',
+  'payment.required': 'Payment is required to continue.',
+  'operation.not_implemented': 'The requested operation is not implemented.',
+  'upstream.invalid_request': 'The upstream service rejected the request.',
+  'upstream.rate_limited': 'The upstream service rate limited the request.',
+  'upstream.timeout': 'The upstream service timed out.',
+  'upstream.network_error': 'A network error occurred while contacting the upstream service.',
+  'upstream.unavailable': 'The upstream service is unavailable.',
+  'upstream.invalid_response': 'The upstream service returned an invalid response.',
+  'upstream.error': 'The upstream service returned an error.',
+  'transport.invoke_failed': 'The provider transport failed.',
+  'internal.timeout': 'The operation timed out.',
+  'internal.unexpected': 'An unexpected internal error occurred.'
+};
+
+export let SERVICE_ERROR_CODE_MAP: Record<string, string> = {
+  invalid_data: 'input.invalid',
+  bad_request: 'request.bad',
+  not_found: 'resource.not_found',
+  unauthorized: 'auth.required',
+  forbidden: 'permission.denied',
+  invalid_version: 'request.invalid_version',
+  conflict: 'resource.conflict',
+  gone: 'resource.gone',
+  payment_required: 'payment.required',
+  precondition_failed: 'request.precondition_failed',
+  not_acceptable: 'request.not_acceptable',
+  not_implemented: 'operation.not_implemented',
+  too_many_requests: 'request.rate_limited',
+  timeout: 'internal.timeout',
+  internal_server_error: 'internal.unexpected'
+};

package/src/error/index.ts

@@ -1,2 +1,5 @@
+export * from './axios';
 export * from './base';
 export * from './declaration';
+export * from './service';
+export * from './types';