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

package/src/error/api.ts

@@ -0,0 +1,236 @@
+import { badRequestError, type ErrorRecord, ServiceError } from '@lowerdeck/error';
+
+export type ApiErrorStatus = number | string;
+export type ApiServiceError = ServiceError<ErrorRecord<any, any>>;
+
+export type ApiErrorResponse = {
+  status?: ApiErrorStatus;
+  statusText?: string;
+  data?: unknown;
+};
+
+export type ApiErrorDetailOptions = {
+  detailKeys?: readonly string[];
+  nestedKeys?: readonly string[];
+  includeNumbers?: boolean;
+  separator?: string;
+  fallbackMessage?: string;
+};
+
+export type ApiErrorBuildHelpers = {
+  collectDetails: (value: unknown, details: string[], options?: ApiErrorDetailOptions) => void;
+  extractMessage: (error: unknown, options?: ApiErrorDetailOptions) => string;
+  getResponse: (error: unknown) => ApiErrorResponse | undefined;
+  getStatus: (error: unknown) => ApiErrorStatus | undefined;
+  isRecord: (value: unknown) => value is Record<string, unknown>;
+  statusLabelFor: (status?: ApiErrorStatus, statusText?: string) => string;
+};
+
+export type BuildApiServiceErrorOptions = ApiErrorDetailOptions & {
+  providerLabel: string;
+  reason: string;
+  operation?: string;
+  extractMessage?: (error: unknown, helpers: ApiErrorBuildHelpers) => string | undefined;
+  extractResponse?: (
+    error: unknown,
+    helpers: ApiErrorBuildHelpers
+  ) => ApiErrorResponse | undefined;
+  extractStatus?: (
+    error: unknown,
+    response: ApiErrorResponse | undefined,
+    helpers: ApiErrorBuildHelpers
+  ) => ApiErrorStatus | undefined;
+  extractUpstreamCode?: (
+    error: unknown,
+    response: ApiErrorResponse | undefined,
+    helpers: ApiErrorBuildHelpers
+  ) => string | undefined;
+  formatMessage?: (parts: {
+    providerLabel: string;
+    operation: string;
+    statusLabel: string;
+    message: string;
+    response?: ApiErrorResponse;
+    status?: ApiErrorStatus;
+  }) => string;
+  parent?: unknown;
+};
+
+let DEFAULT_DETAIL_KEYS = ['message', 'detail', 'error', 'error_description', 'code'];
+let DEFAULT_NESTED_KEYS = ['errors'];
+
+export let isApiErrorRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let pushDetail = (
+  details: string[],
+  value: unknown,
+  options: Pick<ApiErrorDetailOptions, 'includeNumbers'> = {}
+) => {
+  if (
+    typeof value !== 'string' &&
+    (options.includeNumbers === false || typeof value !== 'number')
+  ) {
+    return;
+  }
+
+  let detail = String(value).trim();
+  if (detail && !details.includes(detail)) {
+    details.push(detail);
+  }
+};
+
+export let collectApiErrorDetails = (
+  value: unknown,
+  details: string[],
+  options: ApiErrorDetailOptions = {}
+) => {
+  if (Array.isArray(value)) {
+    for (let item of value) {
+      collectApiErrorDetails(item, details, options);
+    }
+    return;
+  }
+
+  if (!isApiErrorRecord(value)) {
+    pushDetail(details, value, options);
+    return;
+  }
+
+  for (let key of options.detailKeys ?? DEFAULT_DETAIL_KEYS) {
+    pushDetail(details, value[key], options);
+  }
+
+  for (let key of options.nestedKeys ?? DEFAULT_NESTED_KEYS) {
+    collectApiErrorDetails(value[key], details, options);
+  }
+};
+
+// Runtime axios instances from createAxios reject with SlateError (the raw
+// AxiosError is consumed by the response interceptor), so the upstream HTTP
+// status only survives inside SlateError.data — read it back from there or
+// every buildApiServiceError caller loses status-based handling in production.
+let getSlateErrorResponse = (error: Record<string, unknown>): ApiErrorResponse | undefined => {
+  if (error.name !== 'SlateError' || !isApiErrorRecord(error.data)) {
+    return undefined;
+  }
+
+  let data = error.data;
+  let upstream = isApiErrorRecord(data.upstream) ? data.upstream : undefined;
+  let status = upstream?.status ?? data.status;
+  return typeof status === 'number' || typeof status === 'string' ? { status } : undefined;
+};
+
+export let getApiErrorResponse = (error: unknown): ApiErrorResponse | undefined => {
+  if (!isApiErrorRecord(error)) {
+    return undefined;
+  }
+  if (!isApiErrorRecord(error.response)) {
+    return getSlateErrorResponse(error);
+  }
+
+  let response = error.response;
+  return {
+    status:
+      typeof response.status === 'number' || typeof response.status === 'string'
+        ? response.status
+        : undefined,
+    statusText: typeof response.statusText === 'string' ? response.statusText : undefined,
+    data: response.data
+  };
+};
+
+export let getApiErrorStatus = (error: unknown): ApiErrorStatus | undefined =>
+  getApiErrorResponse(error)?.status;
+
+export let statusLabelForApiError = (status?: ApiErrorStatus, statusText?: string) =>
+  status !== undefined ? `HTTP ${status}${statusText ? ` ${statusText}` : ''}: ` : '';
+
+export let extractApiErrorMessage = (
+  error: unknown,
+  options: ApiErrorDetailOptions & { response?: ApiErrorResponse } = {}
+) => {
+  let details: string[] = [];
+  let response = options.response ?? getApiErrorResponse(error);
+
+  collectApiErrorDetails(response?.data, details, options);
+
+  if (details.length > 0) {
+    return details.join(options.separator ?? ' - ');
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return options.fallbackMessage ?? 'Unknown error';
+};
+
+export let createApiServiceError = (
+  message: string,
+  options: {
+    reason?: string;
+    upstreamStatus?: ApiErrorStatus;
+    upstreamCode?: string;
+    parent?: unknown;
+  } = {}
+) => {
+  let error = new ServiceError(badRequestError({ message }));
+
+  if (options.reason !== undefined) {
+    error.data.reason = options.reason;
+  }
+
+  if ('upstreamStatus' in options) {
+    error.data.upstreamStatus = options.upstreamStatus;
+  }
+
+  if ('upstreamCode' in options) {
+    error.data.upstreamCode = options.upstreamCode;
+  }
+
+  if (options.parent instanceof Error) {
+    error.setParent(options.parent);
+  }
+
+  return error;
+};
+
+let helpers: ApiErrorBuildHelpers = {
+  collectDetails: collectApiErrorDetails,
+  extractMessage: extractApiErrorMessage,
+  getResponse: getApiErrorResponse,
+  getStatus: getApiErrorStatus,
+  isRecord: isApiErrorRecord,
+  statusLabelFor: statusLabelForApiError
+};
+
+export let buildApiServiceError = (error: unknown, options: BuildApiServiceErrorOptions) => {
+  if (error instanceof ServiceError) {
+    return error;
+  }
+
+  let operation = options.operation ?? 'request';
+  let response = options.extractResponse?.(error, helpers) ?? getApiErrorResponse(error);
+  let status = options.extractStatus?.(error, response, helpers) ?? response?.status;
+  let message =
+    options.extractMessage?.(error, helpers) ??
+    extractApiErrorMessage(error, { ...options, response });
+  let statusLabel = statusLabelForApiError(status, response?.statusText);
+  let fullMessage =
+    options.formatMessage?.({
+      providerLabel: options.providerLabel,
+      operation,
+      statusLabel,
+      message,
+      response,
+      status
+    }) ?? `${options.providerLabel} API ${operation} failed: ${statusLabel}${message}`;
+
+  return createApiServiceError(fullMessage, {
+    reason: options.reason,
+    upstreamStatus: status,
+    upstreamCode: options.extractUpstreamCode?.(error, response, helpers),
+    parent: options.parent ?? error
+  });
+};

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
+      });
+    }
+  });
+});