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

package/src/auth/oauth.ts

@@ -0,0 +1,150 @@
+import { createApiServiceError } from '../error/api';
+
+export type OAuthTokenResponse = {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  [key: string]: unknown;
+};
+
+export type OAuthRefreshTokenFallbackMode = 'nullish' | 'falsy';
+
+export type OAuthExpiresAtOptions = {
+  nowMs?: number;
+  providerLabel?: string;
+  operation?: string;
+  required?: boolean;
+  expiresInType?: 'number' | 'numberLike';
+  message?: string;
+};
+
+export type NormalizeOAuthTokenResponseOptions = OAuthExpiresAtOptions & {
+  previousRefreshToken?: string;
+  refreshTokenFallbackMode?: OAuthRefreshTokenFallbackMode;
+  accessTokenMessage?: string;
+  expiresInMessage?: string;
+};
+
+let isOAuthTokenResponse = (value: unknown): value is OAuthTokenResponse =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let formatOAuthTokenResponseMessage = (
+  fieldLabel: string,
+  providerLabel = 'OAuth provider',
+  operation = 'token response'
+) => `${providerLabel} OAuth ${operation} did not return ${fieldLabel}.`;
+
+export let getOAuthExpiresAtFromExpiresIn = (
+  expiresIn: unknown,
+  options: OAuthExpiresAtOptions = {}
+) => {
+  let {
+    nowMs = Date.now(),
+    providerLabel,
+    operation,
+    required = false,
+    expiresInType = 'numberLike',
+    message
+  } = options;
+
+  if (expiresIn === undefined || expiresIn === null || expiresIn === '') {
+    if (required) {
+      throw createApiServiceError(
+        message ??
+          formatOAuthTokenResponseMessage(
+            'a valid expires_in value',
+            providerLabel,
+            operation
+          ),
+        { reason: 'oauth_token_response' }
+      );
+    }
+
+    return undefined;
+  }
+
+  let seconds =
+    typeof expiresIn === 'number'
+      ? expiresIn
+      : expiresInType === 'numberLike' && typeof expiresIn === 'string'
+        ? Number(expiresIn)
+        : Number.NaN;
+
+  if (!Number.isFinite(seconds)) {
+    throw createApiServiceError(
+      message ??
+        formatOAuthTokenResponseMessage('a valid expires_in value', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return new Date(nowMs + seconds * 1000).toISOString();
+};
+
+let getRefreshToken = (
+  refreshToken: unknown,
+  previousRefreshToken: string | undefined,
+  fallbackMode: OAuthRefreshTokenFallbackMode
+) => {
+  if (typeof refreshToken === 'string') {
+    if (fallbackMode === 'falsy' && !refreshToken) {
+      return previousRefreshToken;
+    }
+
+    return refreshToken;
+  }
+
+  if (fallbackMode === 'falsy' && !refreshToken) {
+    return previousRefreshToken;
+  }
+
+  return refreshToken === undefined || refreshToken === null
+    ? previousRefreshToken
+    : undefined;
+};
+
+export let normalizeOAuthTokenResponse = (
+  data: unknown,
+  options: NormalizeOAuthTokenResponseOptions = {}
+) => {
+  let {
+    providerLabel,
+    operation,
+    previousRefreshToken,
+    refreshTokenFallbackMode = 'nullish',
+    accessTokenMessage,
+    expiresInMessage,
+    ...expiresAtOptions
+  } = options;
+
+  if (!isOAuthTokenResponse(data)) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('a token response object', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  if (typeof data.access_token !== 'string' || !data.access_token) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('an access token', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return {
+    token: data.access_token,
+    refreshToken: getRefreshToken(
+      data.refresh_token,
+      previousRefreshToken,
+      refreshTokenFallbackMode
+    ),
+    expiresAt: getOAuthExpiresAtFromExpiresIn(data.expires_in, {
+      ...expiresAtOptions,
+      providerLabel,
+      operation,
+      message: expiresInMessage
+    })
+  };
+};

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

@@ -48,6 +48,14 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
       : never;
   }
 
+  get registrationDetails() {
+    return Object.freeze(
+      (this.#input as any).registrationDetails
+    ) as 'registrationDetails' extends keyof InputType
+      ? InputType['registrationDetails']
+      : never;
+  }
+
   get auth() {
     return Object.freeze(this.#auth);
   }

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