gate-carrier-sdk

TypeScript SDK for the BlockIntel Gate Carrier API -- underwriting intelligence for insurance carriers.

Installation

npm install gate-carrier-sdk

Quick Start

import { CarrierClient } from 'gate-carrier-sdk';

const client = new CarrierClient({
  apiKey: 'carrier_abc123...',
  baseUrl: 'https://api.gate.blockintelai.net/api/v1/gate',
  carrierId: 'carrier_xyz',
});

const portfolio = await client.getPortfolio();
console.log(`Tenants: ${portfolio.portfolio.aggregateMetrics.totalTenants}`);

API Reference

Trial Management

| Method | Description | |--------|-------------| | createUnderwritingTrial(request) | Create shadow-mode prospect tenant for underwriting | | getTrialStatus(trialId) | Get detailed trial status with observation progress | | listTrials(status?, nextToken?, limit?) | List all trials (paginated) | | convertTrial(trialId, request) | Convert completed trial to insured tenant |

Portfolio

| Method | Description | |--------|-------------| | getPortfolio() | Full portfolio dashboard -- risk summaries, metrics, alerts | | getPortfolioHealth() | High-level portfolio health status |

Bot Blast Radius (BBR)

| Method | Description | |--------|-------------| | createBBRTest(request) | Create BBR test for a tenant (10/month quota) | | getBBRReport(tenantId) | Get BBR report for a specific tenant | | getPortfolioSummary() | BBR metrics across all authorized tenants | | getMaxLossEstimate() | Portfolio max-loss at p50/p90/p99 |

Alerts

| Method | Description | |--------|-------------| | getAlerts(severity?) | Alert history across portfolio | | acknowledgeAlert(alertId) | Mark alert as reviewed |

Evidence & Claims

| Method | Description | |--------|-------------| | generateClaimPack(request) | Initiate async claim evidence pack generation | | getClaimPackStatus(jobId) | Poll claim pack job status | | getEvidenceBundle(tenantId) | Raw evidence bundle (decisions, snapshots, Merkle root) |

Underwriting Analytics

| Method | Description | |--------|-------------| | getUnderwritingReport(tenantId) | 30-day underwriting metrics for a tenant | | getRiskScore(tenantId) | Composite risk score (0--100) with factor breakdown |

Independent Evidence Verification

| Method | Description | |--------|-------------| | getActivePolicy(tenantId) | Active policy rules, enforcement level, snapshot hash | | getPolicyHistory(tenantId, options?) | Policy change history (paginated) | | getPolicyAt(tenantId, timestamp) | Policy active at a specific point in time | | getKmsInventory(tenantId) | KMS and IAM enforcement inventory | | setBaselinePolicy(baseline) | Set carrier's minimum policy baseline | | getBaselinePolicy() | Get current baseline policy | | simulateTransaction(tenantId, request) | Simulate transaction against tenant's policy |

Webhooks

| Method | Description | |--------|-------------| | registerPolicyChangeWebhook(params) | Register webhook for POLICY_CHANGED events | | listPolicyWebhooks() | List all policy-change webhook subscriptions |

Convenience Helpers

| Method | Description | |--------|-------------| | listAllTrials(status?, limit?) | Auto-paginating async iterator for trials | | waitForClaimPack(jobId, options?) | Poll claim pack until complete or timeout |

Client-Side Utilities

These are pure functions -- no API calls required.

verifyPolicyCompliance(activePolicy, baseline)

Check a tenant's active policy against the carrier's baseline specification. Returns a PolicyComplianceDiff with isCompliant, missingRules, weakerRules, satisfiedRules, and enforcement level comparison.

import { CarrierClient, verifyPolicyCompliance } from 'gate-carrier-sdk';

const client = new CarrierClient({ apiKey, baseUrl, carrierId });

const activePolicy = await client.getActivePolicy('tenant_xyz');
const { baseline } = await client.getBaselinePolicy();

const diff = verifyPolicyCompliance(activePolicy, baseline);

if (!diff.isCompliant) {
  console.log('Missing rules:', diff.missingRules);
  console.log('Weaker rules:', diff.weakerRules);
}

verifyWebhookSignature(payload, signature, secret)

Verify HMAC-SHA256 webhook signatures on incoming payloads. Uses timing-safe comparison to prevent timing oracle attacks.

import { verifyWebhookSignature } from 'gate-carrier-sdk';

app.post('/webhooks/gate', (req, res) => {
  const signature = req.headers['x-gate-webhook-signature'] as string;
  const isValid = verifyWebhookSignature(req.body, signature, webhookSecret);
  if (!isValid) return res.status(401).send('Invalid signature');
  // Process event...
});

Error Handling

All errors extend CarrierError so callers can catch either the base class or a specific subclass.

| Error Class | HTTP Status | Description | |-------------|-------------|-------------| | CarrierError | -- | Base error (all others extend this) | | CarrierAuthError | 401/403 | Invalid or missing carrier API key | | CarrierNotFoundError | 404 | Resource not found | | CarrierConflictError | 409 | Conflict (e.g. duplicate trial, already converted) | | CarrierQuotaExceededError | 429 | Monthly quota exhausted (has resetAt property) | | CarrierServerError | 5xx | Server-side error |

import {
  CarrierClient,
  CarrierAuthError,
  CarrierQuotaExceededError,
  CarrierError,
} from 'gate-carrier-sdk';

try {
  await client.createBBRTest({ tenantId: 'tenant_xyz' });
} catch (err) {
  if (err instanceof CarrierAuthError) {
    console.error('Invalid API key');
  } else if (err instanceof CarrierQuotaExceededError) {
    console.error(`Quota exceeded, resets at: ${err.resetAt}`);
  } else if (err instanceof CarrierError) {
    console.error(`API error: ${err.message} (HTTP ${err.statusCode})`);
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GATE_BASE_URL | Yes | Gate Control Plane base URL | | CARRIER_API_KEY | Yes | Carrier API key (format: carrier_<hex>) | | CARRIER_ID | Yes | Carrier identifier |

const client = new CarrierClient({
  apiKey: process.env.CARRIER_API_KEY!,
  baseUrl: process.env.GATE_BASE_URL!,
  carrierId: process.env.CARRIER_ID!,
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | -- | Carrier API key (required) | | baseUrl | string | -- | Gate Control Plane base URL (required) | | carrierId | string | -- | Carrier identifier (required) | | timeoutMs | number | 30000 | Request timeout in milliseconds | | maxRetries | number | 3 | Max retry attempts on transient failures | | userAgentSuffix | string | -- | Optional suffix for the User-Agent header |

Notes

• Zero runtime dependencies -- uses native fetch (Node.js 18+ or browser).
• Dual ESM/CJS support (built with tsup).
• All methods automatically retry on transient failures (5xx, network errors) with exponential backoff.
• URL path parameters are encoded with encodeURIComponent to prevent injection.

License

MIT

Looking for Python? See gate-carrier-sdk.