@venturekit/integrations API

Overview

@venturekit/integrations provides tools for calling third-party APIs from your Lambda functions:

• HTTP Client — configurable fetch-based client with retry, timeout, interceptors
• OAuth2 — client credentials & authorization code flows with automatic token refresh
• API Key Management — retrieve and cache keys from env vars, SSM, or Secrets Manager

npm install @venturekit/integrations

---

HTTP Client

apiClient(options)

Create a configured HTTP client for calling external APIs.

import { apiClient } from '@venturekit/integrations';

const stripe = apiClient({
  baseUrl: 'https://api.stripe.com/v1',
  headers: { Authorization: `Bearer ${process.env.STRIPE_KEY}` },
  retry: { maxRetries: 3 },
  timeout: 10_000,
});

const customer = await stripe.post<StripeCustomer>('/customers', {
  body: { email: 'user@example.com' },
});
// customer.data, customer.status, customer.headers

ApiClientOptions

Option	Type	Description
baseUrl	string	Base URL for all requests
headers	Record<string, string>	Default headers
timeout	number	Default timeout in ms (default: 30000)
retry	RetryOptions	Retry configuration
onRequest	RequestInterceptor[]	Interceptors called before each request
onResponse	ResponseInterceptor[]	Interceptors called after each response
onError	ErrorInterceptor	Called on any error before it’s thrown

RetryOptions

Option	Type	Default	Description
maxRetries	number	0	Max retry attempts
initialDelayMs	number	1000	Initial backoff delay
backoffMultiplier	number	2	Exponential backoff multiplier
retryableStatuses	number[]	[408, 429, 500, 502, 503, 504]	HTTP statuses that trigger retry

ApiRequestOptions

Option	Type	Description
body	unknown	Request body (auto-JSON-stringified)
headers	Record<string, string>	Per-request headers
params	Record<string, string>	Query parameters
timeout	number	Timeout override (ms)
form	boolean	Send as application/x-www-form-urlencoded
signal	AbortSignal	Cancellation signal

ApiResponse<T>

interface ApiResponse<T> {
  status: number;
  headers: Record<string, string>;
  data: T;
  retried: boolean;
  attempts: number;
}

ApiError

Thrown on non-2xx responses or network errors.

class ApiError extends Error {
  status: number;
  headers: Record<string, string>;
  data: unknown;
  url: string;
  method: string;
}

---

OAuth2

oauth2(options)

Create an OAuth2 client for automatic token management.

Client Credentials Flow

Server-to-server authentication (no user interaction):

import { oauth2, apiClient } from '@venturekit/integrations';

const auth = oauth2({
  flow: 'client_credentials',
  tokenUrl: 'https://oauth.provider.com/token',
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  scopes: ['read', 'write'],
});

// Attach to an API client — tokens refresh automatically
const client = apiClient({
  baseUrl: 'https://api.provider.com',
  onRequest: [auth.interceptor()],
});

Authorization Code Flow

User-delegated authentication (e.g. Google, Slack):

const auth = oauth2({
  flow: 'authorization_code',
  tokenUrl: 'https://oauth2.googleapis.com/token',
  authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  redirectUri: 'https://myapp.com/callback',
  scopes: ['profile', 'email'],
  store: await createDynamoDBTokenStore({ tableName: 'oauth-tokens' }),
});

// 1. Redirect user to authorize
const url = auth.getAuthorizeUrl!('random-state');

// 2. Exchange code in callback handler
const token = await auth.exchangeCode!('auth-code-from-callback');

// 3. Use with API client
const google = apiClient({
  baseUrl: 'https://www.googleapis.com',
  onRequest: [auth.interceptor()],
});

OAuth2Client Methods

Method	Description
getToken()	Get a valid access token (auto-refreshes)
refreshToken()	Force a token refresh
interceptor()	Returns a request interceptor that attaches the Bearer token
exchangeCode(code)	Exchange an authorization code (auth code flow only)
getAuthorizeUrl(state?)	Build the authorization URL (auth code flow only)

Token Storage

Store	Description
createMemoryTokenStore()	In-memory (default) — resets on cold start
createDynamoDBTokenStore({ tableName })	DynamoDB — persists across invocations

---

API Key Management

apiKey(source)

Create a handle for retrieving and caching an API key.

import { apiKey, apiKeyHeader, apiClient } from '@venturekit/integrations';

// From environment variable
const stripeKey = apiKey({ env: 'STRIPE_SECRET_KEY' });

// From SSM Parameter Store
const twilioKey = apiKey({ ssm: '/myapp/prod/twilio-key' });

// From Secrets Manager (with JSON field extraction)
const slackToken = apiKey({
  secret: 'myapp/slack-bot-token',
  field: 'token',
});

// Use with apiClient
const stripe = apiClient({
  baseUrl: 'https://api.stripe.com/v1',
  onRequest: [apiKeyHeader(stripeKey)],
});

Sources

Source	Fields	Description
{ env: string }	Environment variable name	Reads from process.env
{ ssm: string, region?, withDecryption? }	SSM path	Reads from Parameter Store
{ secret: string, field?, region? }	Secret name/ARN	Reads from Secrets Manager

ApiKeyHandle

Method	Description
get()	Get the key (cached after first call, 5-min TTL)
refresh()	Force a re-fetch
clear()	Clear the cache

apiKeyHeader(handle, headerName?, prefix?)

Convenience function that returns a request interceptor attaching the key as a header.

// Default: Authorization: Bearer <key>
apiKeyHeader(myKey)

// Custom header, no prefix: X-Api-Key: <key>
apiKeyHeader(myKey, 'X-Api-Key', '')