Skip to content
VentureKit

@venturekit/integrations

Installation

Section titled “Installation”
Terminal window
npm install @venturekit/integrations

What It Provides

Section titled “What It Provides”

HTTP Client

Section titled “HTTP Client”
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: 5000,
});


// The second argument is `ApiRequestOptions` (`{ body?, headers?, params?, ... }`).
// Pass the JSON payload via `body` — it is auto-stringified.
const res = await stripe.post('/charges', {
  body: { amount: 1000, currency: 'usd' },
});
  • Automatic retries with exponential backoff
  • Configurable timeouts
  • Request/response/error interceptors
  • Structured ApiError class

OAuth2

Section titled “OAuth2”
import { oauth2 } 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!,
});


const client = apiClient({
  baseUrl: 'https://api.provider.com',
  onRequest: [auth.interceptor()],
});
  • Client credentials and authorization code flows
  • Automatic token refresh
  • Token storage: in-memory (default) or DynamoDB

API Key Management

Section titled “API Key Management”
import { apiKey, apiKeyHeader } from '@venturekit/integrations';


const key = apiKey({ ssm: '/myapp/prod/api-key' });


const client = apiClient({
  baseUrl: 'https://api.example.com',
  onRequest: [apiKeyHeader(key, 'X-Api-Key', '')],
});
  • Retrieve keys from environment variables, SSM Parameter Store, or Secrets Manager
  • Built-in caching to avoid repeated AWS calls

Outbound Webhooks

Section titled “Outbound Webhooks”

The other direction: deliver your events to your customers’ endpoints, the way Stripe and GitHub do. Endpoints and a delivery log live in vk_webhook_endpoints / vk_webhook_deliveries (this package’s migrations, applied by vk migrate / vk deploy); every function takes a querier — @venturekit/data’s query or a transaction’s tx.query — so the module has no database dependency of its own.

import { createWebhookEndpoint, enqueueWebhook, deliverWebhooksOnce } from '@venturekit/integrations';
import { query } from '@venturekit/data';


// 1. The customer registers an endpoint — the secret is shown once
const { endpoint, secret } = await createWebhookEndpoint(query, {
  url: 'https://customer.example/hooks/vk',
  tenantId: ctx.tenant!.id,
  eventTypes: ['invoice.paid', 'invoice.failed'],   // empty = every event
});


// 2. In the same transaction as the state change: fan out one delivery per subscribed endpoint
await enqueueWebhook(ctx.tx!.query, {
  eventId: invoice.id + ':paid',   // stable → re-running the producer is idempotent
  eventType: 'invoice.paid',
  payload: { invoiceId: invoice.id, amount: invoice.total },
  tenantId: ctx.tenant!.id,
});


// 3. schedules[]: every minute
export const main = taskHandler(async () => deliverWebhooksOnce(query, { limit: 25, timeoutMs: 10_000 }));
  • Endpoints must be https:// (http:// only for localhost); updateWebhookEndpoint, rotateWebhookEndpointSecret, deleteWebhookEndpoint, listWebhookEndpoints manage them
  • Deliveries are claimed with FOR UPDATE SKIP LOCKED (safe to run several relays), POSTed as signed JSON, and retried with exponential backoff — 30 s, 1 min, 2 min, … capped at 6 h — until maxAttempts (default 8, ≈ 4 h) marks them dead; listWebhookDeliveries and replayWebhookDelivery back the customer’s delivery log
  • Receivers verify X-VK-Signature (v1=<hex> HMAC-SHA256 over ${timestamp}.${rawBody}, 5-minute replay window) with verifyWebhookSignature and dedupe on X-VK-Event-Id

Types

Section titled “Types”
  • ApiClient, ApiClientOptions, ApiRequestOptions, ApiResponse — HTTP client types
  • RetryOptions, RequestInterceptor, ResponseInterceptor, ErrorInterceptor — interceptor types
  • OAuth2Client, OAuth2Options, TokenSet, TokenStore — OAuth2 types
  • ApiKeyHandle, ApiKeySource, ApiKeyFromEnv, ApiKeyFromSSM, ApiKeyFromSecret — API key types
  • WebhookEndpoint, WebhookDelivery, WebhookDeliveryStatus, CreateWebhookEndpointInput, EnqueueWebhookInput, DeliverWebhooksOptions, DeliverWebhooksResult, WebhookQuerier — outbound webhook types

Dependencies

Section titled “Dependencies”
  • @venturekit/core — required
  • @aws-sdk/client-dynamodb, @aws-sdk/lib-dynamodb — peer (for DynamoDB token store)
  • @aws-sdk/client-ssm — peer (for SSM parameter store)
  • @aws-sdk/client-secrets-manager — peer (for Secrets Manager)
Section titled “Related”