@contractspec/bundle.library 0.0.0-canary-20260206014742

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

@@ -0,0 +1,435 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Integrations: ContractSpec Docs',
+//   description:
+//     'Connect ContractSpec to payments, email, AI, storage, and other services through built-in integrations.',
+// };
+
+export function IntegrationsOverviewPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Integrations</h1>
+        <p className="text-muted-foreground">
+          ContractSpec provides first-class integration support through a
+          spec-first architecture. Integrations are defined globally, connected
+          per-tenant, and bound to apps through typed specifications, ensuring
+          type-safe, policy-enforced access to external services.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Spec-first architecture</h2>
+        <p className="text-muted-foreground">
+          Integrations in ContractSpec follow a three-layer model:
+        </p>
+        <div className="space-y-3">
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 font-semibold">1. IntegrationSpec (Global)</h3>
+            <p className="text-muted-foreground text-sm">
+              Defines what an integration provides: capabilities, configuration
+              schema, secrets, webhooks, and requirements.
+            </p>
+            <Link
+              href="/docs/integrations/spec-model"
+              className="mt-2 inline-block text-sm text-violet-400 hover:text-violet-300"
+            >
+              Learn more →
+            </Link>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 font-semibold">
+              2. IntegrationConnection (Per-Tenant)
+            </h3>
+            <p className="text-muted-foreground text-sm">
+              A tenant's configured connection with credentials, environment
+              (sandbox/production), and health status.
+            </p>
+            <Link
+              href="/docs/architecture/integration-binding"
+              className="mt-2 inline-block text-sm text-violet-400 hover:text-violet-300"
+            >
+              Learn more →
+            </Link>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="mb-2 font-semibold">
+              3. AppIntegrationBinding (Per-App)
+            </h3>
+            <p className="text-muted-foreground text-sm">
+              Maps tenant connections to app capabilities and workflows,
+              defining which operations can use which integrations.
+            </p>
+            <Link
+              href="/docs/architecture/integration-binding"
+              className="mt-2 inline-block text-sm text-violet-400 hover:text-violet-300"
+            >
+              Learn more →
+            </Link>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Integration categories</h2>
+        <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
+  | "email"         // Postmark, Resend, Gmail
+  | "calendar"      // Google Calendar
+  | "sms"           // Twilio
+  | "ai-llm"        // OpenAI
+  | "ai-voice"      // ElevenLabs
+  | "speech-to-text" // OpenAI Whisper
+  | "vector-db"     // Qdrant
+  | "storage"       // S3-compatible
+  | "open-banking"  // Powens (read-only)
+  | "accounting"    // Coming soon
+  | "crm"           // Coming soon
+  | "helpdesk"      // Coming soon
+  | "custom";       // User-defined`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Available integrations</h2>
+        <div className="space-y-6">
+          {/* Payments */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Payments</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/stripe"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Stripe
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Payment processing, subscriptions, and invoicing
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Open Banking */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Open Banking</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/powens"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Powens (Read-Only)
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Account, transaction, and balance synchronisation via Powens
+                  with tenant-owned credentials.
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Email */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Email</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/postmark"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Postmark
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Transactional email delivery with high deliverability
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/resend"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Resend
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Modern email API for developers
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/gmail"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Gmail API
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Inbound email processing and thread management
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Calendar & Scheduling */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Calendar & Scheduling</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/google-calendar"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Google Calendar
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Event scheduling and calendar management
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* AI & Machine Learning */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">AI & Machine Learning</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/openai"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  OpenAI
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  LLMs, embeddings, and Whisper speech-to-text
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/elevenlabs"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  ElevenLabs
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Text-to-speech and voice synthesis
+                </p>
+              </Link>
+              <Link
+                href="/docs/integrations/qdrant"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  Qdrant
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Vector database for semantic search and RAG
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* Storage */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">Storage</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/s3"
+                className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+              >
+                <h4 className="font-bold transition-colors group-hover:text-violet-400">
+                  S3-Compatible Storage
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Object storage (AWS S3, Scaleway, MinIO, etc.)
+                </p>
+              </Link>
+            </div>
+          </div>
+
+          {/* SMS */}
+          <div className="space-y-3">
+            <h3 className="text-xl font-semibold">SMS & Messaging</h3>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Link
+                href="/docs/integrations/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">
+                  Twilio
+                </h4>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  SMS notifications and messaging
+                </p>
+              </Link>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">How integrations work</h2>
+        <p className="text-muted-foreground">
+          ContractSpec integrations are implemented as{' '}
+          <Link
+            href="/docs/specs/capabilities"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            capability providers
+          </Link>
+          . This means:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Type safety</strong> – All API calls are type-checked by
+            TypeScript and validated at runtime via Zod
+          </li>
+          <li>
+            <strong>Policy enforcement</strong> – Access to external services is
+            governed by your{' '}
+            <Link
+              href="/docs/specs/policy"
+              className="text-violet-400 hover:text-violet-300"
+            >
+              PolicySpecs
+            </Link>
+          </li>
+          <li>
+            <strong>Audit logging</strong> – All integration calls are
+            automatically logged
+          </li>
+          <li>
+            <strong>Error handling</strong> – Built-in retries and fallback
+            strategies
+          </li>
+          <li>
+            <strong>Environment-based config</strong> – API keys and secrets are
+            managed through environment variables
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Secret management</h2>
+        <p className="text-muted-foreground">
+          Secrets are resolved through a layered secret provider manager. It
+          checks lightweight environment overrides first, then falls back to a
+          managed vault (Google Cloud Secret Manager) for production.
+        </p>
+        <div className="grid gap-4 md:grid-cols-2">
+          <div className="card-subtle p-4">
+            <h3 className="text-xl font-semibold">Environment variables</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Perfect for local development and secure staging overrides. Use
+              the <code>env://</code> scheme or append <code>?env=</code> to
+              another reference to map an explicit variable.
+            </p>
+            <div className="bg-background/60 border-border mt-3 overflow-auto rounded-lg border p-3 font-mono text-xs">
+              <pre className="whitespace-pre-wrap">{`# Override a production secret locally
+CONTRACTSPEC__SECRET__STRIPE=sk_test_123
+
+# Reference
+env://CONTRACTSPEC__SECRET__STRIPE`}</pre>
+            </div>
+          </div>
+          <div className="card-subtle p-4">
+            <h3 className="text-xl font-semibold">GCP Secret Manager</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              Used in production to store versioned credentials with rotation
+              support. References follow the{' '}
+              <code>gcp://projects/.../secrets/.../versions/latest</code>{' '}
+              format.
+            </p>
+            <div className="bg-background/60 border-border mt-3 overflow-auto rounded-lg border p-3 font-mono text-xs">
+              <pre className="whitespace-pre-wrap">{`# Production reference
+gcp://projects/tenant/secrets/stripe-secret-key/versions/latest`}</pre>
+            </div>
+          </div>
+        </div>
+        <p className="text-muted-foreground text-sm">
+          The secret manager chooses the first provider that can resolve a
+          reference, so local environment variables can override the managed
+          vault without changing blueprints or tenant configs.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Configuration</h2>
+        <p className="text-muted-foreground">
+          Integrations are configured through environment variables and secret
+          references. Here's a typical setup:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# .env
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+POSTMARK_API_TOKEN=...
+POSTMARK_FROM_EMAIL=noreply@example.com
+
+OPENAI_API_KEY=sk-...
+OPENAI_ORGANIZATION=org-...
+
+QDRANT_URL=https://...
+QDRANT_API_KEY=...
+
+S3_ENDPOINT=https://s3.fr-par.scw.cloud
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+S3_BUCKET=my-bucket
+S3_REGION=fr-par
+
+# Secret references
+STRIPE_SECRET_REF=gcp://projects/tenant/secrets/stripe-secret-key/versions/latest
+STRIPE_SECRET_OVERRIDE=env://STRIPE_SECRET_KEY`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Integration categories</h2>
+        <p className="text-muted-foreground">
+          ContractSpec supports the following integration categories:
+        </p>
+        <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.
+  | "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
+  | "vector-db"       // Qdrant, Pinecone, Weaviate
+  | "storage"         // S3, GCS, Azure Blob
+  | "accounting"      // QuickBooks, Xero (coming soon)
+  | "crm"             // Salesforce, HubSpot (coming soon)
+  | "helpdesk"        // Zendesk, Intercom (coming soon)
+  | "custom";         // Your own integrations`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Custom integrations</h2>
+        <p className="text-muted-foreground">
+          You can create custom integrations by implementing a capability
+          provider. See the{' '}
+          <Link
+            href="/docs/advanced/custom-providers"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            Custom Providers
+          </Link>{' '}
+          guide for details.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/stripe" className="btn-primary">
+          Get Started with Stripe <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,161 @@
+/* eslint-disable no-useless-escape */
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Postmark Integration: ContractSpec Docs',
+//   description:
+//     'Send transactional emails with high deliverability using Postmark in ContractSpec.',
+// };
+
+export function IntegrationsPostmarkPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Postmark</h1>
+        <p className="text-muted-foreground">
+          Postmark is a transactional email service with industry-leading
+          deliverability. Use it to send order confirmations, password resets,
+          notifications, and other critical emails.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Setup</h2>
+        <p className="text-muted-foreground">
+          Add your Postmark credentials to your environment variables:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# .env
+POSTMARK_API_TOKEN=...
+POSTMARK_FROM_EMAIL=noreply@example.com
+POSTMARK_FROM_NAME="Your App Name"`}</pre>
+        </div>
+        <p className="text-muted-foreground text-sm">
+          Get your API token from the{' '}
+          <a
+            href="https://account.postmarkapp.com/servers"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            Postmark Dashboard
+          </a>
+          .
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Sending emails</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`capabilityId: send-email
+provider:
+  type: postmark
+  operation: sendEmail
+
+inputs:
+  to:
+    type: string
+    description: "Recipient email address"
+  subject:
+    type: string
+  htmlBody:
+    type: string
+    optional: true
+  textBody:
+    type: string
+    optional: true
+  templateId:
+    type: string
+    optional: true
+  templateData:
+    type: object
+    optional: true
+
+outputs:
+  messageId:
+    type: string
+  submittedAt:
+    type: timestamp`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Using templates</h2>
+        <p className="text-muted-foreground">
+          Postmark templates allow you to design emails in their dashboard and
+          populate them with data:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`capabilityId: send-welcome-email
+provider:
+  type: postmark
+  operation: sendEmail
+
+inputs:
+  to:
+    type: string
+  userName:
+    type: string
+
+config:
+  templateId: "welcome-email"
+  templateData:
+    user_name: \$\{input.userName\}
+    login_url: "https://app.example.com/login"`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Webhooks</h2>
+        <p className="text-muted-foreground">
+          Postmark can notify your app about delivery, bounces, and opens:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`https://your-app.com/api/webhooks/postmark`}</pre>
+        </div>
+        <p className="text-muted-foreground">
+          ContractSpec automatically processes these webhook events:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Delivery</strong> – Email was successfully delivered
+          </li>
+          <li>
+            <strong>Bounce</strong> – Email bounced (hard or soft)
+          </li>
+          <li>
+            <strong>SpamComplaint</strong> – Recipient marked email as spam
+          </li>
+          <li>
+            <strong>Open</strong> – Recipient opened the email
+          </li>
+          <li>
+            <strong>Click</strong> – Recipient clicked a link
+          </li>
+        </ul>
+      </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 templates for consistent branding</li>
+          <li>Always provide both HTML and plain text versions</li>
+          <li>Monitor bounce rates and remove invalid addresses</li>
+          <li>Use message streams to separate different email types</li>
+          <li>Test emails in the Postmark sandbox before going live</li>
+          <li>Set up DKIM and SPF records for your domain</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/stripe" className="btn-ghost">
+          Previous: Stripe
+        </Link>
+        <Link href="/docs/integrations/resend" className="btn-primary">
+          Next: Resend <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}