@venturekit/integrations

Warning: This package is in active development and not production-ready. APIs may change without notice.

Third-party integration layer for VentureKit — an HTTP client with retry, OAuth2 token management, API-key handling for the APIs you call, and outbound webhooks for the events you deliver to customers.

Installation

npm install @venturekit/integrations

Outbound webhooks

Deliver your domain events to your customers' endpoints the way Stripe / GitHub do: registered endpoints with a signing secret, one delivery row per event × endpoint, retries with backoff, a delivery log with replay.

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

// 1. A customer registers an endpoint — the secret is returned once
const { endpoint, secret } = await createWebhookEndpoint(query, {
  url: 'https://customer.example/hooks', tenantId, eventTypes: ['invoice.paid'],
});

// 2. Your code enqueues in the same transaction as the state change
await withTransaction(async (tx) => {
  await invoices.markPaid(tx, invoice.id);
  await enqueueWebhook(tx.query, { eventId: `invoice.paid:${invoice.id}`, eventType: 'invoice.paid', payload: invoice, tenantId });
});

// 3. A schedules[] cron (every minute) drains the queue
export const main = taskHandler(async () => deliverWebhooksOnce(query, { limit: 50 }));

// 4. The customer verifies (constant-time, 5-minute replay window)
verifyWebhookSignature({ secret, timestamp: req.headers['x-vk-timestamp'], rawBody, signature: req.headers['x-vk-signature'] });

Deliveries are claimed with FOR UPDATE SKIP LOCKED (safe to run several relays), retried at 30 s → 1 min → 2 min … capped at 6 h, and marked dead after maxAttempts (default 8); listWebhookDeliveries / replayWebhookDelivery back a customer-facing log. The request carries X-VK-Webhook-Id, X-VK-Event-Id (the receiver's idempotency key), X-VK-Event-Type, X-VK-Timestamp and X-VK-Signature: v1=<HMAC-SHA256("${timestamp}.${body}")>. Endpoints must be https:// (http only on localhost).

Tables vk_webhook_endpoints / vk_webhook_deliveries ship with the package's migrations and are applied by vk migrate / vk deploy like every other package migration.

HTTP client, OAuth2, API keys (outbound)

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

const auth = oauth2({ flow: 'client_credentials', tokenUrl: '…', clientId: '…', clientSecret: '…' });
const provider = apiClient({ baseUrl: 'https://api.provider.com', onRequest: [auth.interceptor()], retry: { maxRetries: 3 } });

const key = apiKey({ ssm: '/myapp/prod/api-key' });
const client = apiClient({ baseUrl: 'https://api.example.com', onRequest: [apiKeyHeader(key, 'X-Api-Key', '')] });

For keys your customers present to your API, see @venturekit/auth/server's createApiKey / apiKeyAuth.

License

Apache-2.0 — see LICENSE for details.