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

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,6 @@
+export * from './api';
+export * from './axios';
 export * from './base';
 export * from './declaration';
+export * from './service';
+export * from './types';

package/src/error/service.ts

@@ -0,0 +1,170 @@
+import type { ErrorData, ErrorRecord, ServiceError } from '@lowerdeck/error';
+import { isServiceError } 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,75 @@
+import type { AxiosError, AxiosResponse } from 'axios';
+import type { SlateHttpTrace } from '../axios/trace';
+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>;
+  requestTraces?: SlateHttpTrace[];
+}
+
+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> | undefined;
+}
+
+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,157 @@
+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?.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,
+    requestTraces: override.requestTraces ?? base.requestTraces
+  };
+};
+
+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),
+    requestTraces: input.requestTraces
+  };
+};
+
+export let isSlateErrorResponse = (error: unknown): error is SlateErrorResponse => {
+  if (!isRecord(error)) return false;
+  return typeof error.code === 'string' && typeof error.message === 'string';
+};

package/src/file/index.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { getBase64ByteLength, getResponseHeaderValue } from './index';
+
+describe('file helpers', () => {
+  it('finds response headers case-insensitively from plain objects', () => {
+    expect(
+      getResponseHeaderValue(
+        {
+          'Content-Type': 'application/pdf',
+          'x-empty': ''
+        },
+        'content-type'
+      )
+    ).toBe('application/pdf');
+    expect(getResponseHeaderValue({ 'x-empty': '' }, 'X-Empty')).toBe('');
+  });
+
+  it('returns the first string value from array headers', () => {
+    expect(
+      getResponseHeaderValue({ 'content-type': ['text/plain', 'text/html'] }, 'content-type')
+    ).toBe('text/plain');
+    expect(
+      getResponseHeaderValue({ 'content-type': [123, 'text/html'] }, 'content-type')
+    ).toBe('text/html');
+  });
+
+  it('supports Headers-like objects', () => {
+    let headers = new Headers({ 'content-type': 'image/png' });
+
+    expect(getResponseHeaderValue(headers, 'Content-Type')).toBe('image/png');
+  });
+
+  it('computes decoded base64 byte length', () => {
+    expect(getBase64ByteLength(Buffer.from('hello').toString('base64'))).toBe(5);
+  });
+});

package/src/file/index.ts

@@ -0,0 +1,27 @@
+export let getResponseHeaderValue = (headers: unknown, name: string): string | undefined => {
+  if (!headers) return undefined;
+
+  if (typeof (headers as { get?: unknown }).get === 'function') {
+    let value = (headers as { get(headerName: string): unknown }).get(name);
+    return typeof value === 'string' ? value : undefined;
+  }
+
+  if (typeof headers !== 'object') return undefined;
+
+  let lowerName = name.toLowerCase();
+  for (let [headerName, value] of Object.entries(headers as Record<string, unknown>)) {
+    if (headerName.toLowerCase() !== lowerName) continue;
+
+    if (Array.isArray(value)) {
+      let first = value.find(item => typeof item === 'string');
+      return typeof first === 'string' ? first : undefined;
+    }
+
+    return typeof value === 'string' ? value : undefined;
+  }
+
+  return undefined;
+};
+
+export let getBase64ByteLength = (contentBase64: string) =>
+  Buffer.from(contentBase64, 'base64').byteLength;

package/src/index.ts

@@ -1,8 +1,16 @@
 export * from './action';
+export * from './action/attachment';
+export * from './action/directUpload';
+export * from './adapter';
 export * from './auth';
 export * from './axios';
 export * from './config';
 export * from './context';
+export * from './crypto';
+export * from './docs';
 export * from './error';
+export * from './file';
 export * from './logger';
+export * from './object';
 export * from './specification';
+export * from './webhook';