@slates/provider 1.0.0-rc.16 → 1.0.0-rc.18

package/src/auth/types.ts

@@ -97,7 +97,7 @@ export type SlateAuthWithToken<InputType extends {}, OutputType extends { token?
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
     output: OutputType;
     scopes?: string[];
   }>;
@@ -109,7 +109,12 @@ export type SlateAuthWithToken<InputType extends {}, OutputType extends { token?
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
@@ -124,7 +129,7 @@ export type SlateAuthWithServiceAccount<InputType extends {}, OutputType extends
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
     output: OutputType;
     scopes?: string[];
   }>;
@@ -136,7 +141,12 @@ export type SlateAuthWithServiceAccount<InputType extends {}, OutputType extends
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
@@ -151,7 +161,7 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
     output: OutputType;
     scopes?: string[];
   }>;
@@ -162,6 +172,7 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    config?: SlateAuthCallbackConfig;
   }) => Promise<{
     output: OutputType;
     input?: InputType;
@@ -174,7 +185,12 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };

package/src/axios/http.test.ts

@@ -0,0 +1,83 @@
+import type { AxiosResponse } from 'axios';
+import { describe, expect, it } from 'vitest';
+import { createAuthenticatedAxios, requestAxios, requestAxiosData } from './index';
+
+describe('createAuthenticatedAxios', () => {
+  it('sets auth and JSON headers while preserving caller headers', () => {
+    let client = createAuthenticatedAxios({
+      baseURL: 'https://example.test',
+      authHeader: {
+        value: 'Bearer token'
+      },
+      headers: {
+        Accept: 'application/json'
+      }
+    });
+
+    expect(client.defaults.baseURL).toBe('https://example.test');
+    expect(client.defaults.headers.Authorization).toBe('Bearer token');
+    expect(client.defaults.headers['Content-Type']).toBe('application/json');
+    expect(client.defaults.headers.Accept).toBe('application/json');
+  });
+
+  it('allows custom auth header names and disabling content type defaults', () => {
+    let client = createAuthenticatedAxios({
+      authHeader: {
+        name: 'X-API-Key',
+        value: 'secret'
+      },
+      contentType: false
+    });
+
+    expect(client.defaults.headers['X-API-Key']).toBe('secret');
+    expect(client.defaults.headers['Content-Type']).toBeUndefined();
+  });
+});
+
+describe('requestAxios helpers', () => {
+  it('returns full responses or response data', async () => {
+    let response = {
+      config: {} as AxiosResponse<{ ok: boolean }>['config'],
+      data: { ok: true },
+      headers: {},
+      status: 200,
+      statusText: 'OK'
+    };
+
+    await expect(
+      requestAxios(
+        'get thing',
+        async () => response,
+        error => error
+      )
+    ).resolves.toBe(response);
+    await expect(
+      requestAxiosData(
+        'get thing',
+        async () => response,
+        error => error
+      )
+    ).resolves.toEqual({ ok: true });
+  });
+
+  it('maps failures with the operation name', async () => {
+    let upstream = new Error('upstream failed');
+    let mapped = new Error('mapped failure');
+    let seenOperation: string | undefined;
+
+    await expect(
+      requestAxiosData(
+        'create thing',
+        async () => {
+          throw upstream;
+        },
+        (_error, operation) => {
+          seenOperation = operation;
+          return mapped;
+        }
+      )
+    ).rejects.toBe(mapped);
+
+    expect(seenOperation).toBe('create thing');
+  });
+});

package/src/axios/index.ts

@@ -1,4 +1,9 @@
-import type { AxiosInstance, CreateAxiosDefaults, InternalAxiosRequestConfig } from 'axios';
+import type {
+  AxiosInstance,
+  AxiosResponse,
+  CreateAxiosDefaults,
+  InternalAxiosRequestConfig
+} from 'axios';
 import baseAxios, { getAdapter, isAxiosError } from 'axios';
 import { getCurrentContext } from '../context/hook';
 import type { SlateAxiosErrorOptions } from '../error';
@@ -13,6 +18,17 @@ export interface SlateAxiosDefaults extends CreateAxiosDefaults {
   errorMapping?: SlateAxiosErrorOptions;
 }
 
+export type SlateAxiosErrorAdapter = (error: unknown, operation: string) => unknown;
+
+export interface SlateAuthenticatedAxiosDefaults extends SlateAxiosDefaults {
+  authHeader?: {
+    name?: string;
+    value: string;
+  };
+  contentType?: string | false;
+  errorAdapter?: (error: unknown) => unknown;
+}
+
 let applySlateInterceptors = (
   instance: AxiosInstance,
   errorMapping?: SlateAxiosErrorOptions
@@ -73,4 +89,46 @@ export let createAxios = (config?: SlateAxiosDefaults) => {
   return instance;
 };
 
+export let createAuthenticatedAxios = (config: SlateAuthenticatedAxiosDefaults) => {
+  let { authHeader, contentType = 'application/json', errorAdapter, ...axiosConfig } = config;
+  let instance = createAxios({
+    ...axiosConfig,
+    headers: {
+      ...(contentType === false ? {} : { 'Content-Type': contentType }),
+      ...(authHeader ? { [authHeader.name ?? 'Authorization']: authHeader.value } : {}),
+      ...axiosConfig.headers
+    }
+  });
+
+  if (errorAdapter) {
+    instance.interceptors.response.use(
+      response => response,
+      error => Promise.reject(errorAdapter(error))
+    );
+  }
+
+  return instance;
+};
+
+export let requestAxios = async <T = unknown>(
+  operation: string,
+  request: () => Promise<AxiosResponse<T>>,
+  errorAdapter: SlateAxiosErrorAdapter
+) => {
+  try {
+    return await request();
+  } catch (error) {
+    throw errorAdapter(error, operation);
+  }
+};
+
+export let requestAxiosData = async <T = unknown>(
+  operation: string,
+  request: () => Promise<AxiosResponse<T>>,
+  errorAdapter: SlateAxiosErrorAdapter
+) => {
+  let response = await requestAxios(operation, request, errorAdapter);
+  return response.data as T;
+};
+
 export let axios = createAxios();

package/src/axios/trace.ts

@@ -1,5 +1,5 @@
 import type { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
-import type { SlateContext } from '../context';
+import type { SlatePublicContext } from '../context';
 
 export interface SlateHttpTraceTextBody {
   contentType?: string;
@@ -29,7 +29,7 @@ export interface SlateHttpTrace {
 }
 
 interface SlateHttpTraceDraft {
-  context: SlateContext<any, any, any>;
+  context: SlatePublicContext<any>;
   startedAt: string;
   startedAtMs: number;
   request: SlateHttpTrace['request'];
@@ -664,7 +664,7 @@ let clearTraceDraft = (
 
 export let attachHttpTraceDraft = (
   config: InternalAxiosRequestConfig,
-  context: SlateContext<any, any, any>
+  context: SlatePublicContext<any>
 ) => {
   let traceAwareConfig = config as TraceAwareAxiosRequestConfig;
   let contentType = getContentType(config.headers);

package/src/context/context.ts

@@ -2,32 +2,22 @@ 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;
+export class SlatePublicContext<InputType extends {}> {
   #input: InputType;
-  #auth: AuthType;
   #httpTraces: SlateHttpTrace[] = [];
 
   constructor(
-    config: ConfigType,
     input: InputType,
-    auth: AuthType,
-    private readonly spec: SlateSpecification<ConfigType, AuthType>,
+    private readonly spec: SlateSpecification<any, any>,
     private readonly logger: SlateLogger
   ) {
-    this.#config = config;
     this.#input = input;
-    this.#auth = auth;
   }
 
   get specification() {
     return this.spec;
   }
 
-  get config() {
-    return Object.freeze(this.#config);
-  }
-
   get input() {
     return Object.freeze(this.#input);
   }
@@ -48,8 +38,12 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
       : never;
   }
 
-  get auth() {
-    return Object.freeze(this.#auth);
+  get registrationDetails() {
+    return Object.freeze(
+      (this.#input as any).registrationDetails
+    ) as 'registrationDetails' extends keyof InputType
+      ? InputType['registrationDetails']
+      : never;
   }
 
   recordHttpTrace(trace: SlateHttpTrace) {
@@ -93,3 +87,32 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
     this.logger.progress(message);
   }
 }
+
+export class SlateContext<
+  ConfigType extends {},
+  AuthType extends {},
+  InputType extends {}
+> extends SlatePublicContext<InputType> {
+  #config: ConfigType;
+  #auth: AuthType;
+
+  constructor(
+    config: ConfigType,
+    input: InputType,
+    auth: AuthType,
+    spec: SlateSpecification<ConfigType, AuthType>,
+    logger: SlateLogger
+  ) {
+    super(input, spec, logger);
+    this.#config = config;
+    this.#auth = auth;
+  }
+
+  get config() {
+    return Object.freeze(this.#config);
+  }
+
+  get auth() {
+    return Object.freeze(this.#auth);
+  }
+}

package/src/context/hook.ts

@@ -1,24 +1,19 @@
 import { AsyncLocalStorage } from 'async_hooks';
-import type { SlateContext } from './context';
+import type { SlateContext, SlatePublicContext } from './context';
 
 let slateContextStorageKey = Symbol.for('slates.provider.context.asyncLocalStorage');
 let globalWithSlateContext = globalThis as typeof globalThis & {
-  [key: symbol]: AsyncLocalStorage<SlateContext<any, any, any>> | undefined;
+  [key: symbol]: AsyncLocalStorage<SlatePublicContext<any>> | undefined;
 };
 
 let asyncLocalStorage =
   globalWithSlateContext[slateContextStorageKey] ??
-  new AsyncLocalStorage<SlateContext<any, any, any>>();
+  new AsyncLocalStorage<SlatePublicContext<any>>();
 
 globalWithSlateContext[slateContextStorageKey] = asyncLocalStorage;
 
-export let runWithContext = <
-  ConfigType extends {},
-  AuthType extends {},
-  InputType extends {},
-  RV
->(
-  context: SlateContext<ConfigType, AuthType, InputType>,
+export let runWithContext = <InputType extends {}, RV>(
+  context: SlatePublicContext<InputType>,
   fn: () => Promise<RV>
 ): Promise<RV> => {
   return asyncLocalStorage.run(context, fn);

package/src/crypto/hmac.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { createHmacSignature, verifyHmacSignature } from './hmac';
+
+describe('createHmacSignature', () => {
+  it('creates prefixed hexadecimal HMAC signatures', () => {
+    expect(
+      createHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        digest: 'hex',
+        prefix: 'v0='
+      })
+    ).toBe('v0=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4');
+  });
+});
+
+describe('verifyHmacSignature', () => {
+  it('verifies prefixed hexadecimal HMAC signatures', () => {
+    expect(
+      verifyHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        signature: 'v0=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4',
+        digest: 'hex',
+        prefix: 'v0='
+      })
+    ).toBe(true);
+  });
+
+  it('rejects incorrect signatures, including signatures of a different length', () => {
+    expect(
+      verifyHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        signature: 'invalid',
+        digest: 'base64'
+      })
+    ).toBe(false);
+  });
+});

package/src/crypto/hmac.ts

@@ -0,0 +1,32 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+export interface CreateHmacSignatureOptions {
+  secret: string | Uint8Array;
+  payload: string | Uint8Array;
+  algorithm?: string;
+  digest: 'hex' | 'base64';
+  prefix?: string;
+}
+
+export interface VerifyHmacSignatureOptions extends CreateHmacSignatureOptions {
+  signature: string;
+}
+
+export let createHmacSignature = ({
+  secret,
+  payload,
+  algorithm = 'sha256',
+  digest,
+  prefix = ''
+}: CreateHmacSignatureOptions) =>
+  `${prefix}${createHmac(algorithm, secret).update(payload).digest(digest)}`;
+
+export let verifyHmacSignature = (options: VerifyHmacSignatureOptions) => {
+  let expected = createHmacSignature(options);
+  let expectedBytes = Buffer.from(expected);
+  let signatureBytes = Buffer.from(options.signature);
+  let lengthsMatch = signatureBytes.length === expectedBytes.length;
+  let comparableSignature = lengthsMatch ? signatureBytes : Buffer.alloc(expectedBytes.length);
+
+  return timingSafeEqual(comparableSignature, expectedBytes) && lengthsMatch;
+};

package/src/crypto/index.ts

@@ -0,0 +1 @@
+export * from './hmac';

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