@slates/provider 1.0.0-rc.15 → 1.0.0-rc.17

package/src/error/api.test.ts

@@ -0,0 +1,114 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { buildApiServiceError, collectApiErrorDetails, createApiServiceError } from './api';
+import { SlateError } from './base';
+
+describe('API service error helpers', () => {
+  it('collects unique nested API error details', () => {
+    let details: string[] = [];
+
+    collectApiErrorDetails(
+      {
+        message: 'Invalid request',
+        code: 'bad_request',
+        errors: [
+          {
+            detail: 'Missing name'
+          },
+          'Missing name'
+        ]
+      },
+      details
+    );
+
+    expect(details).toEqual(['Invalid request', 'bad_request', 'Missing name']);
+  });
+
+  it('builds provider API ServiceErrors with upstream metadata', () => {
+    let parent = new Error('Request failed');
+    (parent as any).response = {
+      status: 429,
+      statusText: 'Too Many Requests',
+      data: {
+        title: 'Rate limit',
+        details: [{ message: 'Retry later' }]
+      }
+    };
+
+    let error = buildApiServiceError(parent, {
+      providerLabel: 'Example',
+      operation: 'list widgets',
+      reason: 'example_api_error',
+      detailKeys: ['title', 'message'],
+      nestedKeys: ['details'],
+      extractUpstreamCode: () => 'RATE_LIMITED'
+    });
+
+    expect(error).toBeInstanceOf(ServiceError);
+    expect(error.data.message).toBe(
+      'Example API list widgets failed: HTTP 429 Too Many Requests: Rate limit - Retry later'
+    );
+    expect(error.data.reason).toBe('example_api_error');
+    expect(error.data.upstreamStatus).toBe(429);
+    expect(error.data.upstreamCode).toBe('RATE_LIMITED');
+  });
+
+  it('recovers the upstream status from interceptor-normalized SlateErrors', () => {
+    // Runtime axios instances reject with SlateError, not AxiosError: the
+    // response interceptor consumes error.response, so the status only
+    // survives at data.upstream.status / data.status.
+    let parent = new SlateError({
+      code: 'not_found',
+      message: 'Method not found.',
+      upstream: { status: 404 }
+    });
+
+    let error = buildApiServiceError(parent, {
+      providerLabel: 'Example',
+      operation: 'search messages',
+      reason: 'example_api_error'
+    });
+
+    expect(error.data.upstreamStatus).toBe(404);
+    expect(error.data.message).toBe(
+      'Example API search messages failed: HTTP 404: Method not found.'
+    );
+  });
+
+  it('allows provider-specific status and message extraction', () => {
+    let error = buildApiServiceError(
+      {
+        status: 503,
+        data: {
+          message: 'Unavailable'
+        }
+      },
+      {
+        providerLabel: 'Example',
+        reason: 'example_api_error',
+        extractStatus: (input, _response, helpers) =>
+          helpers.isRecord(input) && typeof input.status === 'number'
+            ? input.status
+            : undefined,
+        extractMessage: (input, helpers) => {
+          if (!helpers.isRecord(input) || !helpers.isRecord(input.data)) return undefined;
+          return typeof input.data.message === 'string' ? input.data.message : undefined;
+        }
+      }
+    );
+
+    expect(error.data.message).toBe('Example API request failed: HTTP 503: Unavailable');
+    expect(error.data.upstreamStatus).toBe(503);
+  });
+
+  it('passes through existing ServiceErrors', () => {
+    let existing = createApiServiceError('Already normalized');
+
+    expect(
+      buildApiServiceError(existing, {
+        providerLabel: 'Example',
+        reason: 'example_api_error'
+      })
+    ).toBe(existing);
+  });
+});

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/index.ts

@@ -1,3 +1,4 @@
+export * from './api';
 export * from './axios';
 export * from './base';
 export * from './declaration';

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

@@ -4,7 +4,11 @@ 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';

package/src/object/index.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { pickDefined, setIfDefined } from './index';
+
+describe('object helpers', () => {
+  it('omits only undefined values', () => {
+    expect(
+      pickDefined({
+        keepNull: null,
+        keepFalse: false,
+        keepZero: 0,
+        keepEmpty: '',
+        dropUndefined: undefined
+      })
+    ).toEqual({
+      keepNull: null,
+      keepFalse: false,
+      keepZero: 0,
+      keepEmpty: ''
+    });
+  });
+
+  it('sets only defined values on an existing target', () => {
+    let target: Record<string, unknown> = {};
+
+    setIfDefined(target, 'nullValue', null);
+    setIfDefined(target, 'falseValue', false);
+    setIfDefined(target, 'zeroValue', 0);
+    setIfDefined(target, 'emptyValue', '');
+    setIfDefined(target, 'undefinedValue', undefined);
+
+    expect(target).toEqual({
+      nullValue: null,
+      falseValue: false,
+      zeroValue: 0,
+      emptyValue: ''
+    });
+  });
+});

package/src/object/index.ts

@@ -0,0 +1,12 @@
+export let pickDefined = <T extends object>(value: T) =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, child]) => child !== undefined)
+  ) as Partial<T> & Record<string, unknown>;
+
+export let setIfDefined = (target: Record<string, unknown>, key: string, value: unknown) => {
+  if (value !== undefined) {
+    target[key] = value;
+  }
+
+  return target;
+};

package/src/webhook/graph.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { getGraphWebhookValidationResponse, graphWebhookHttp } from './graph';
+
+describe('Microsoft Graph webhook validation', () => {
+  it('makes only validation requests synchronous', () => {
+    expect(graphWebhookHttp).toEqual({
+      methods: ['POST'],
+      sync: {
+        mode: 'match',
+        match: [{ hasQueryParam: 'validationToken' }]
+      }
+    });
+  });
+
+  it('echoes the URL-decoded validation token as plain text', () => {
+    let response = getGraphWebhookValidationResponse(
+      new Request(
+        'https://example.com/webhook?validationToken=Validation%3a+Testing+client+application+reachability',
+        { method: 'POST' }
+      )
+    );
+
+    expect(response).toEqual({
+      status: 200,
+      headers: { 'content-type': 'text/plain' },
+      body: 'Validation: Testing client application reachability'
+    });
+  });
+
+  it('ignores ordinary change notifications', () => {
+    expect(
+      getGraphWebhookValidationResponse(
+        new Request('https://example.com/webhook', { method: 'POST' })
+      )
+    ).toBeNull();
+  });
+});

package/src/webhook/graph.ts

@@ -0,0 +1,22 @@
+import type { SlateWebhookHttpOptions, SlateWebhookHttpResponseInit } from '../action';
+
+export const graphWebhookHttp = {
+  methods: ['POST'],
+  sync: {
+    mode: 'match',
+    match: [{ hasQueryParam: 'validationToken' }]
+  }
+} satisfies SlateWebhookHttpOptions;
+
+export let getGraphWebhookValidationResponse = (
+  request: Request
+): SlateWebhookHttpResponseInit | null => {
+  let validationToken = new URL(request.url).searchParams.get('validationToken');
+  if (validationToken === null) return null;
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'text/plain' },
+    body: validationToken
+  };
+};

package/src/webhook/index.ts

@@ -0,0 +1,2 @@
+export * from './graph';
+export * from './meta';

package/src/webhook/meta.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { getMetaWebhookVerificationResponse, metaWebhookHttp } from './meta';
+
+let verificationRequest = (verifyToken = 'verify-token', challenge = 'challenge-value') =>
+  new Request(
+    `https://example.com/webhook?hub.mode=subscribe&hub.verify_token=${verifyToken}&hub.challenge=${challenge}`
+  );
+
+describe('Meta webhook verification', () => {
+  it('makes only verification GET requests synchronous', () => {
+    expect(metaWebhookHttp).toEqual({
+      methods: ['GET', 'POST'],
+      sync: {
+        mode: 'match',
+        match: [{ method: 'GET', hasQueryParam: 'hub.mode' }]
+      }
+    });
+  });
+
+  it('returns the challenge for a matching configured token', () => {
+    expect(getMetaWebhookVerificationResponse(verificationRequest(), 'verify-token')).toEqual({
+      status: 200,
+      headers: { 'content-type': 'text/plain' },
+      body: 'challenge-value'
+    });
+  });
+
+  it('rejects a mismatched configured token', () => {
+    expect(
+      getMetaWebhookVerificationResponse(verificationRequest('wrong-token'), 'verify-token')
+    ).toMatchObject({ status: 403 });
+    expect(
+      getMetaWebhookVerificationResponse(verificationRequest('wrong-token'), '')
+    ).toMatchObject({ status: 403 });
+  });
+
+  it('preserves legacy verification when no token is configured', () => {
+    expect(
+      getMetaWebhookVerificationResponse(verificationRequest('legacy-token'), undefined)
+    ).toMatchObject({ status: 200, body: 'challenge-value' });
+  });
+
+  it('rejects malformed verification and ignores POST events', () => {
+    let malformed = new Request('https://example.com/webhook?hub.mode=subscribe');
+    let post = new Request('https://example.com/webhook', { method: 'POST' });
+
+    expect(getMetaWebhookVerificationResponse(malformed, undefined)).toMatchObject({
+      status: 400
+    });
+    expect(getMetaWebhookVerificationResponse(post, undefined)).toBeNull();
+  });
+});

package/src/webhook/meta.ts

@@ -0,0 +1,43 @@
+import type { SlateWebhookHttpOptions, SlateWebhookHttpResponseInit } from '../action';
+
+export const metaWebhookHttp = {
+  methods: ['GET', 'POST'],
+  sync: {
+    mode: 'match',
+    match: [{ method: 'GET', hasQueryParam: 'hub.mode' }]
+  }
+} satisfies SlateWebhookHttpOptions;
+
+export let getMetaWebhookVerificationResponse = (
+  request: Request,
+  expectedVerifyToken: string | undefined
+): SlateWebhookHttpResponseInit | null => {
+  if (request.method !== 'GET') return null;
+
+  let url = new URL(request.url);
+  let mode = url.searchParams.get('hub.mode');
+  let verifyToken = url.searchParams.get('hub.verify_token');
+  let challenge = url.searchParams.get('hub.challenge');
+
+  if (mode !== 'subscribe' || challenge === null) {
+    return {
+      status: 400,
+      headers: { 'content-type': 'text/plain' },
+      body: 'invalid webhook verification request'
+    };
+  }
+
+  if (expectedVerifyToken !== undefined && verifyToken !== expectedVerifyToken) {
+    return {
+      status: 403,
+      headers: { 'content-type': 'text/plain' },
+      body: 'invalid verify token'
+    };
+  }
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'text/plain' },
+    body: challenge
+  };
+};