Integration Spec Model

Integrations in ContractSpec are defined through typed specifications that declare capabilities, configuration requirements, and connection details. This page covers IntegrationSpec and IntegrationConnection.

IntegrationSpec

The IntegrationSpec is a global definition of an integration provider. It declares what the integration provides and what it requires.

type IntegrationSpec = {
  id: string;
  label: string;
  description: string;
  category: IntegrationCategory;
  
  // Capabilities this integration provides
  providesCapabilities: {
    capabilityId: string;
    operation: string;
    description: string;
  }[];
  
  // Dependencies
  requirements: {
    capabilities?: string[];  // e.g., ["billing.core", "auth.session"]
    minVersion?: string;
  };
  
  // Configuration schema (non-secret)
  configSchema: {
    [key: string]: {
      type: string;
      description: string;
      required?: boolean;
      default?: unknown;
    };
  };
  
  // Secret schema (for keys, tokens)
  secretSchema: {
    [key: string]: {
      type: string;
      description: string;
      required: boolean;
    };
  };
  
  // Webhook support
  webhooks?: {
    supported: boolean;
    events: string[];
    signatureHeader?: string;
  };
  
  // Documentation
  docsUrl?: string;
  setupGuideUrl?: string;
  
  // Metadata
  version: string;
  createdAt: string;
  updatedAt: string;
};

Example: Stripe IntegrationSpec

{
  id: "stripe",
  label: "Stripe",
  description: "Payment processing and subscription management",
  category: "payments",
  
  providesCapabilities: [
    {
      capabilityId: "payments.createPaymentIntent",
      operation: "createPaymentIntent",
      description: "Create a payment intent for checkout"
    },
    {
      capabilityId: "payments.createSubscription",
      operation: "createSubscription",
      description: "Create a recurring subscription"
    },
    {
      capabilityId: "payments.refund",
      operation: "refund",
      description: "Refund a payment"
    }
  ],
  
  requirements: {
    capabilities: ["billing.core"],
    minVersion: "1.0.0"
  },
  
  configSchema: {
    webhookUrl: {
      type: "string",
      description: "URL to receive Stripe webhooks",
      required: false
    }
  },
  
  secretSchema: {
    apiKey: {
      type: "string",
      description: "Stripe secret API key (sk_...)",
      required: true
    },
    webhookSecret: {
      type: "string",
      description: "Webhook signing secret (whsec_...)",
      required: false
    }
  },
  
  webhooks: {
    supported: true,
    events: [
      "payment_intent.succeeded",
      "payment_intent.payment_failed",
      "customer.subscription.created",
      "customer.subscription.updated",
      "customer.subscription.deleted"
    ],
    signatureHeader: "stripe-signature"
  },
  
  docsUrl: "https://docs.contractspec.com/integrations/stripe",
  setupGuideUrl: "https://stripe.com/docs/keys",
  version: "1.0.0"
}

IntegrationConnection

An IntegrationConnection is a per-tenant instance of an integration with configured credentials and environment settings.

type IntegrationConnection = {
  id: string;
  tenantId: string;
  integrationId: string;
  
  // Environment
  environment: "sandbox" | "production";
  
  // Configuration (non-secret)
  config: Record<string, unknown>;
  
  // Secret reference (encrypted, never exposed)
  secretRef: string;
  
  // Status
  status: "connected" | "disconnected" | "error";
  lastHealthCheck?: string;
  lastHealthCheckStatus?: "success" | "failure";
  lastErrorMessage?: string;
  
  // Metadata
  createdAt: string;
  updatedAt: string;
  createdBy: string;
};

Example: Stripe IntegrationConnection

// Production connection
{
  id: "conn_stripe_acme_prod",
  tenantId: "acme-corp",
  integrationId: "stripe",
  environment: "production",
  config: {
    webhookUrl: "https://acme.app/webhooks/stripe"
  },
  secretRef: "secret_stripe_acme_prod_v1",
  status: "connected",
  lastHealthCheck: "2025-01-15T10:30:00Z",
  lastHealthCheckStatus: "success",
  createdAt: "2025-01-01T00:00:00Z",
  updatedAt: "2025-01-15T10:30:00Z",
  createdBy: "admin@acme.com"
}

// Sandbox connection
{
  id: "conn_stripe_acme_test",
  tenantId: "acme-corp",
  integrationId: "stripe",
  environment: "sandbox",
  config: {
    webhookUrl: "https://sandbox.acme.app/webhooks/stripe"
  },
  secretRef: "secret_stripe_acme_test_v1",
  status: "connected",
  lastHealthCheck: "2025-01-15T10:25:00Z",
  lastHealthCheckStatus: "success",
  createdAt: "2025-01-01T00:00:00Z",
  updatedAt: "2025-01-15T10:25:00Z",
  createdBy: "dev@acme.com"
}

Health checks

IntegrationConnections are periodically health-checked to ensure they remain valid:

  • API key validation - Test that credentials are still valid
  • Connectivity check - Verify network access to the provider
  • Permission verification - Ensure required scopes are granted
  • Webhook validation - Test webhook endpoint reachability

Failed health checks update the connection status to "error" and trigger alerts.

Secret management

Secrets (API keys, tokens) are never stored in plaintext:

  1. User provides secrets through secure UI or API
  2. Secrets are encrypted using tenant-specific keys
  3. Encrypted secrets are stored in secure vault (e.g., AWS Secrets Manager)
  4. IntegrationConnection stores only a reference (secretRef)
  5. At runtime, secrets are decrypted on-demand and never logged

Best practices

  • Always maintain separate sandbox and production connections
  • Use descriptive connection IDs that include tenant and environment
  • Monitor health check status and set up alerts for failures
  • Rotate secrets regularly and update secretRef accordingly
  • Document the purpose and ownership of each connection
  • Test connections in sandbox before enabling in production
Back to IntegrationsIntegration Binding