@contractspec/bundle.library 2.9.1 → 3.0.0

package/src/components/docs/integrations/IntegrationsOverviewPage.tsx

@@ -77,15 +77,22 @@ export function IntegrationsOverviewPage() {
         <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
           <pre>{`type IntegrationCategory =
   | "payments"      // Stripe
+  | "open-banking"  // Powens
   | "email"         // Postmark, Resend, Gmail
   | "calendar"      // Google Calendar
   | "sms"           // Twilio
-  | "ai-llm"        // OpenAI
-  | "ai-voice"      // ElevenLabs
-  | "speech-to-text" // OpenAI Whisper
+  | "messaging"     // Slack, GitHub, WhatsApp
+  | "health"        // Whoop, Oura, Strava, Fitbit
+  | "ai-llm"        // OpenAI, Mistral
+  | "ai-voice-tts"  // ElevenLabs
+  | "ai-voice-stt"  // OpenAI Whisper, Mistral Voxtral
+  | "ai-voice-conversational" // OpenAI Realtime, Mistral Voice
+  | "ai-image"      // OpenAI Image, Fal
   | "vector-db"     // Qdrant
+  | "database"      // Supabase Postgres
   | "storage"       // S3-compatible
-  | "open-banking"  // Powens (read-only)
+  | "meeting-recorder" // Fireflies, tl;dv
+  | "project-management" // Linear, Jira, Notion
   | "accounting"    // Coming soon
   | "crm"           // Coming soon
   | "helpdesk"      // Coming soon
@@ -206,6 +213,17 @@ export function IntegrationsOverviewPage() {
                   LLMs, embeddings, and Whisper speech-to-text
                 </p>
               </Link>
+              <Link
+                href="/docs/integrations/mistral"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Mistral
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  LLMs, embeddings, Voxtral STT, and conversational voice
+                </p>
+              </Link>
               <Link
                 href="/docs/integrations/elevenlabs"
                 className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
@@ -251,7 +269,7 @@ export function IntegrationsOverviewPage() {
 
           {/* SMS */}
           <div className="space-y-3">
-            <h3 className="text-xl font-semibold">SMS & Messaging</h3>
+            <h3 className="text-xl font-semibold">SMS</h3>
             <div className="grid gap-4 md:grid-cols-2">
               <Link
                 href="/docs/integrations/twilio"
@@ -261,7 +279,78 @@ export function IntegrationsOverviewPage() {
                   Twilio
                 </h4>
                 <p className="text-muted-foreground mt-1 text-sm">
-                  SMS notifications and messaging
+                  SMS notifications and transactional messaging
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Messaging channels */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Messaging channels</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/slack"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Slack
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Signed event ingestion and outbox-backed replies
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/github"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  GitHub
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Issue and PR comment workflows with webhook verification
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/whatsapp-meta"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  WhatsApp Meta
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Primary WhatsApp Business API transport for inbound and
+                  outbound
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/whatsapp-twilio"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  WhatsApp Twilio
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Fallback WhatsApp route with Twilio signature validation
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Health */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Health & wearables</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/health-routing"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Health routing strategy
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Official vs aggregator transport order, unofficial gating, and
+                  OAuth refresh config
                 </p>
               </Link>
             </div>
@@ -372,6 +461,8 @@ POSTMARK_FROM_EMAIL=noreply@example.com
 OPENAI_API_KEY=sk-...
 OPENAI_ORGANIZATION=org-...
 
+MISTRAL_API_KEY=...
+
 QDRANT_URL=https://...
 QDRANT_API_KEY=...
 
@@ -395,14 +486,22 @@ STRIPE_SECRET_OVERRIDE=env://STRIPE_SECRET_KEY`}</pre>
         <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
           <pre>{`type IntegrationCategory =
   | "payments"        // Stripe, PayPal, etc.
+  | "open-banking"    // Powens and open banking providers
   | "email"           // Postmark, Resend, Gmail
   | "calendar"        // Google Calendar, Outlook
   | "sms"             // Twilio, MessageBird
-  | "ai-llm"          // OpenAI, Anthropic, Cohere
-  | "ai-voice"        // ElevenLabs, Google TTS
-  | "speech-to-text"  // OpenAI Whisper, Google STT
+  | "messaging"       // Slack, GitHub, WhatsApp
+  | "health"          // Whoop, Oura, Strava, Fitbit
+  | "ai-llm"          // OpenAI, Anthropic, Cohere, Mistral
+  | "ai-voice-tts"    // ElevenLabs, Google TTS
+  | "ai-voice-stt"    // OpenAI Whisper, Google STT, Mistral Voxtral
+  | "ai-voice-conversational" // OpenAI Realtime, Mistral Voice
+  | "ai-image"        // OpenAI Image, Fal
   | "vector-db"       // Qdrant, Pinecone, Weaviate
+  | "database"        // Supabase, Postgres
   | "storage"         // S3, GCS, Azure Blob
+  | "meeting-recorder" // Fireflies, tl;dv, Granola
+  | "project-management" // Linear, Jira, Notion
   | "accounting"      // QuickBooks, Xero (coming soon)
   | "crm"             // Salesforce, HubSpot (coming soon)
   | "helpdesk"        // Zendesk, Intercom (coming soon)

package/src/components/docs/integrations/IntegrationsSlackPage.tsx

@@ -0,0 +1,98 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function IntegrationsSlackPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Slack Messaging</h1>
+        <p className="text-muted-foreground">
+          ContractSpec supports signed Slack event ingestion and outbox-backed
+          outbound replies through the channel runtime.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Required secrets and config</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`// secret payload
+{
+  "botToken": "xoxb-...",
+  "signingSecret": "..."
+}
+
+// optional connection config
+{
+  "defaultChannelId": "C0123456789",
+  "apiBaseUrl": "https://slack.com/api"
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Webhook ingress</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Inbound events are accepted on{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              /webhooks/slack/events
+            </code>
+            .
+          </li>
+          <li>
+            Requests are validated with Slack signatures (
+            <code className="bg-background/50 rounded px-2 py-1">
+              x-slack-signature
+            </code>{' '}
+            + timestamp tolerance).
+          </li>
+          <li>
+            Normalized events are deduplicated and persisted before any outbound
+            side effects.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Workspace routing and dispatch</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# Workspace mapping (recommended)
+CHANNEL_WORKSPACE_MAP_SLACK={"T123":"workspace-acme"}
+
+# Dispatch protection
+CHANNEL_DISPATCH_TOKEN=...
+
+# Optional scheduler
+CHANNEL_DISPATCH_INTERVAL_MS=120000
+CHANNEL_DISPATCH_RUN_ON_START=1`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Keep bot tokens and signing secrets in a managed secret provider.
+          </li>
+          <li>Use workspace mapping to prevent cross-tenant event leakage.</li>
+          <li>
+            Keep dispatch asynchronous so webhook handlers stay fast and
+            reliable.
+          </li>
+          <li>
+            Monitor telemetry for ingest, decision, outbox, and dispatch stages.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/twilio" className="btn-ghost">
+          Previous: Twilio SMS
+        </Link>
+        <Link href="/docs/integrations/github" className="btn-primary">
+          Next: GitHub Messaging <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/integrations/IntegrationsSpecModelPage.tsx

@@ -234,6 +234,65 @@ export function IntegrationsSpecModelPage() {
         </div>
       </div>
 
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">
+          Example: Messaging IntegrationConnection
+        </h2>
+        <p className="text-muted-foreground">
+          Messaging providers use the same spec + connection model, then route
+          inbound events through the channel runtime for signature validation,
+          idempotent ingestion, policy decisions, and outbox-backed dispatch.
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`{
+  id: "conn_slack_acme_prod",
+  tenantId: "acme-corp",
+  integrationId: "messaging.slack",
+  environment: "production",
+  config: {
+    defaultChannelId: "C0123456789",
+    apiBaseUrl: "https://slack.com/api"
+  },
+  secretRef: "secret_slack_acme_prod_v1",
+  status: "connected"
+}
+
+// secret payload behind secretRef
+{
+  "botToken": "xoxb-...",
+  "signingSecret": "..."
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Health transport strategy config</h2>
+        <p className="text-muted-foreground">
+          Health providers support deterministic transport routing and explicit
+          unofficial gating in connection config.
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`{
+  "defaultTransport": "official-api",
+  "strategyOrder": ["official-api", "aggregator-api", "unofficial"],
+  "allowUnofficial": false,
+  "unofficialAllowList": ["health.peloton"],
+  "mcpUrl": "https://mcp.provider.example",
+  "oauthTokenUrl": "https://api.provider.example/oauth/token"
+}
+
+// secret payload behind secretRef
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "clientId": "...",
+  "clientSecret": "...",
+  "tokenExpiresAt": "2026-02-01T00:00:00.000Z",
+  "mcpAccessToken": "..."
+}`}</pre>
+        </div>
+      </div>
+
       <div className="space-y-4">
         <h2 className="text-2xl font-bold">Health checks</h2>
         <p className="text-muted-foreground">

package/src/components/docs/integrations/IntegrationsTwilioPage.tsx

@@ -76,8 +76,8 @@ outputs:
         <Link href="/docs/integrations/s3" className="btn-ghost">
           Previous: S3 Storage
         </Link>
-        <Link href="/docs/integrations" className="btn-primary">
-          Back to Integrations
+        <Link href="/docs/integrations/slack" className="btn-primary">
+          Next: Slack Messaging
         </Link>
       </div>
     </div>

package/src/components/docs/integrations/IntegrationsWhatsappMetaPage.tsx

@@ -0,0 +1,90 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function IntegrationsWhatsappMetaPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">WhatsApp Meta</h1>
+        <p className="text-muted-foreground">
+          Meta WhatsApp is the primary WhatsApp channel for ContractSpec's
+          messaging runtime, with signed webhook verification and reliable
+          outbound delivery.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Required secrets and config</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`// secret payload
+{
+  "accessToken": "...",
+  "appSecret": "...",
+  "verifyToken": "..."
+}
+
+// required connection config
+{
+  "phoneNumberId": "120000000001",
+  "apiVersion": "v22.0"
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Webhook endpoints</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Verification challenge:{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              GET /webhooks/whatsapp/meta
+            </code>
+          </li>
+          <li>
+            Inbound messages:{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              POST /webhooks/whatsapp/meta
+            </code>
+          </li>
+          <li>
+            Signatures are validated with{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              x-hub-signature-256
+            </code>
+            .
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Workspace mapping</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`CHANNEL_WORKSPACE_MAP_WHATSAPP_META={"120000000001":"workspace-acme"}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>Keep verify and app secrets separate from access tokens.</li>
+          <li>
+            Map each phone number ID to a workspace for strict tenant routing.
+          </li>
+          <li>
+            Use Twilio WhatsApp only as fallback when you need active-passive
+            routing.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/github" className="btn-ghost">
+          Previous: GitHub Messaging
+        </Link>
+        <Link href="/docs/integrations/whatsapp-twilio" className="btn-primary">
+          Next: WhatsApp Twilio <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/integrations/IntegrationsWhatsappTwilioPage.tsx

@@ -0,0 +1,92 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function IntegrationsWhatsappTwilioPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">WhatsApp Twilio</h1>
+        <p className="text-muted-foreground">
+          Twilio WhatsApp support provides a durable fallback channel with
+          signature verification and outbox-backed outbound dispatch.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Required secrets and config</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`// secret payload
+{
+  "accountSid": "AC123",
+  "authToken": "..."
+}
+
+// optional connection config
+{
+  "fromNumber": "whatsapp:+15550002"
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Webhook ingress</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Inbound Twilio form payloads are accepted on{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              /webhooks/whatsapp/twilio
+            </code>
+            .
+          </li>
+          <li>
+            Signatures are validated with{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              x-twilio-signature
+            </code>{' '}
+            and the configured auth token.
+          </li>
+          <li>
+            For deterministic verification, set the exact public webhook URL in{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              WHATSAPP_TWILIO_WEBHOOK_URL
+            </code>
+            .
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Workspace mapping</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`CHANNEL_WORKSPACE_MAP_WHATSAPP_TWILIO={"AC123":"workspace-acme"}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Use Twilio as fallback when Meta WhatsApp is your primary route.
+          </li>
+          <li>Keep account SID mapping explicit to avoid tenant misrouting.</li>
+          <li>
+            Protect internal dispatch endpoints with
+            <code className="bg-background/50 ml-1 rounded px-2 py-1">
+              CHANNEL_DISPATCH_TOKEN
+            </code>
+            .
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/whatsapp-meta" className="btn-ghost">
+          Previous: WhatsApp Meta
+        </Link>
+        <Link href="/docs/integrations/health-routing" className="btn-primary">
+          Next: Health Routing <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/integrations/index.ts

@@ -1,14 +1,20 @@
 export { IntegrationsOverviewPage } from './IntegrationsOverviewPage';
 export { IntegrationsCircuitBreakersPage } from './IntegrationsCircuitBreakersPage';
 export { IntegrationsElevenLabsPage } from './IntegrationsElevenLabsPage';
+export { IntegrationsGithubPage } from './IntegrationsGithubPage';
 export { IntegrationsGmailPage } from './IntegrationsGmailPage';
 export { IntegrationsGoogleCalendarPage } from './IntegrationsGoogleCalendarPage';
+export { IntegrationsHealthRoutingPage } from './IntegrationsHealthRoutingPage';
+export { IntegrationsMistralPage } from './IntegrationsMistralPage';
 export { IntegrationsOpenAIPage } from './IntegrationsOpenAIPage';
 export { IntegrationsPostmarkPage } from './IntegrationsPostmarkPage';
 export { IntegrationsPowensPage } from './IntegrationsPowensPage';
 export { IntegrationsQdrantPage } from './IntegrationsQdrantPage';
 export { IntegrationsResendPage } from './IntegrationsResendPage';
 export { IntegrationsS3Page } from './IntegrationsS3Page';
+export { IntegrationsSlackPage } from './IntegrationsSlackPage';
 export { IntegrationsSpecModelPage } from './IntegrationsSpecModelPage';
 export { IntegrationsStripePage } from './IntegrationsStripePage';
 export { IntegrationsTwilioPage } from './IntegrationsTwilioPage';
+export { IntegrationsWhatsappMetaPage } from './IntegrationsWhatsappMetaPage';
+export { IntegrationsWhatsappTwilioPage } from './IntegrationsWhatsappTwilioPage';