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

package/src/action/trigger.ts

@@ -8,7 +8,8 @@ import {
   type SlateTriggerPollingHandler,
   type SlateTriggerWebhookAutoRegistrationHandler,
   type SlateTriggerWebhookAutoUnregistrationHandler,
-  type SlateTriggerWebhookRequestHandler
+  type SlateTriggerWebhookRequestHandler,
+  type SlateWebhookHttpOptions
 } from './action';
 import { SlateActionBuilder } from './builder';
 
@@ -27,6 +28,7 @@ export interface SlateTriggerParameters<
   polling?: SlatePollingOptions;
   handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  http?: SlateWebhookHttpOptions;
   pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -44,6 +46,7 @@ export class SlateTrigger<
   #polling: SlatePollingOptions;
   #handleEvent: SlateTriggerMappingHandler<ConfigType, AuthType, InputType, OutputType>;
   #handleRequest?: SlateTriggerWebhookRequestHandler<ConfigType, AuthType, InputType>;
+  #http?: SlateWebhookHttpOptions;
   #pollEvents?: SlateTriggerPollingHandler<ConfigType, AuthType, InputType>;
   #autoRegisterWebhook?: SlateTriggerWebhookAutoRegistrationHandler<ConfigType, AuthType>;
   #autoUnregisterWebhook?: SlateTriggerWebhookAutoUnregistrationHandler<ConfigType, AuthType>;
@@ -62,6 +65,7 @@ export class SlateTrigger<
     };
     this.#handleEvent = params.handleEvent;
     this.#handleRequest = params.handleRequest;
+    this.#http = params.http;
     this.#pollEvents = params.pollEvents;
     this.#autoRegisterWebhook = params.autoRegisterWebhook;
     this.#autoUnregisterWebhook = params.autoUnregisterWebhook;
@@ -93,6 +97,10 @@ export class SlateTrigger<
     return this.#handleRequest;
   }
 
+  get http() {
+    return this.#http;
+  }
+
   get pollEvents() {
     return this.#pollEvents;
   }

package/src/auth/index.ts

@@ -1,2 +1,3 @@
 export * from './auth';
+export * from './oauth';
 export * from './types';

package/src/auth/oauth.test.ts

@@ -0,0 +1,83 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import type { ApiServiceError } from '../error/api';
+import { getOAuthExpiresAtFromExpiresIn, normalizeOAuthTokenResponse } from './oauth';
+
+describe('OAuth auth helpers', () => {
+  it('converts expires_in seconds to an ISO expiresAt timestamp', () => {
+    expect(getOAuthExpiresAtFromExpiresIn(60, { nowMs: 0 })).toBe('1970-01-01T00:01:00.000Z');
+  });
+
+  it('normalizes token responses and preserves omitted refresh tokens', () => {
+    expect(
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          expires_in: '120'
+        },
+        {
+          nowMs: 0,
+          previousRefreshToken: 'existing-refresh-token'
+        }
+      )
+    ).toEqual({
+      token: 'access-token',
+      refreshToken: 'existing-refresh-token',
+      expiresAt: '1970-01-01T00:02:00.000Z'
+    });
+  });
+
+  it('supports falsy refresh-token fallback semantics', () => {
+    expect(
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          refresh_token: ''
+        },
+        {
+          previousRefreshToken: 'existing-refresh-token',
+          refreshTokenFallbackMode: 'falsy'
+        }
+      ).refreshToken
+    ).toBe('existing-refresh-token');
+  });
+
+  it('throws ServiceError for missing access tokens', () => {
+    let call = () =>
+      normalizeOAuthTokenResponse(
+        {
+          expires_in: 120
+        },
+        {
+          providerLabel: 'Example',
+          operation: 'token exchange'
+        }
+      );
+
+    expect(call).toThrow(ServiceError);
+
+    try {
+      call();
+    } catch (error) {
+      expect(error).toBeInstanceOf(ServiceError);
+      expect((error as ApiServiceError).data.reason).toBe('oauth_token_response');
+    }
+  });
+
+  it('can require a numeric expires_in value', () => {
+    expect(() =>
+      normalizeOAuthTokenResponse(
+        {
+          access_token: 'access-token',
+          expires_in: '120'
+        },
+        {
+          providerLabel: 'Example',
+          operation: 'token exchange',
+          required: true,
+          expiresInType: 'number'
+        }
+      )
+    ).toThrow(ServiceError);
+  });
+});

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,10 @@ export type SlateAuthWithToken<InputType extends {}, OutputType extends { token?
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
 
   onInputChanged?: (params: {
     previousInput: InputType;
@@ -106,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>;
   }>;
 };
@@ -121,7 +129,10 @@ export type SlateAuthWithServiceAccount<InputType extends {}, OutputType extends
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
 
   onInputChanged?: (params: {
     previousInput: InputType;
@@ -130,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>;
   }>;
 };
@@ -145,7 +161,10 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
 
   docs?: SlateAuthDocsReference[];
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
 
   handleTokenRefresh?: (ctx: {
     output: OutputType;
@@ -153,6 +172,7 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    config?: SlateAuthCallbackConfig;
   }) => Promise<{
     output: OutputType;
     input?: InputType;
@@ -165,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';