@contractspec/bundle.library 0.0.0-canary-20260206014742

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

@@ -0,0 +1,231 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Powens Open Banking: ContractSpec Docs',
+//   description:
+//     'Synchronise bank accounts, transactions, and balances with Powens in read-only mode for the Pocket Family Office vertical.',
+// };
+
+export function IntegrationsPowensPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Powens Open Banking</h1>
+        <p className="text-muted-foreground">
+          Powens provides read-only open banking connectivity for ContractSpec
+          applications. The reference integration powers Pocket Family Office by
+          synchronising household bank accounts, transactions, and balances
+          while keeping all raw PII protected.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Setup</h2>
+        <p className="text-muted-foreground">
+          Create a Powens BYOK project, then store the credentials in your
+          secret manager. The ContractSpec integration expects the following
+          fields:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`{
+  "clientId": "powens-client-id",
+  "clientSecret": "powens-client-secret",
+  "apiKey": "optional-api-key",
+  "webhookSecret": "optional-webhook-secret"
+}`}</pre>
+        </div>
+        <p className="text-muted-foreground text-sm">
+          Configure non-secret settings on the integration connection:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`environment: sandbox | production
+baseUrl?: https://api-sandbox.powens.com/v2
+region?: eu-west-1
+pollingIntervalMs?: 300000`}</pre>
+        </div>
+        <p className="text-muted-foreground text-sm">
+          See the{' '}
+          <a
+            href="https://docs.powens.com/documentation/integration-guides/quick-start/api-overview"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            Powens API documentation
+          </a>{' '}
+          for information on generating credentials and managing BYOK projects.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Capabilities</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: openbanking.accounts.read
+provider:
+  type: openbanking.powens
+  operation: listAccounts
+
+outputs:
+  accounts:
+    type: BankAccountRecord[]
+    description: "Canonical bank account metadata (institution, currency, balances)"
+
+---
+
+capabilityId: openbanking.transactions.read
+provider:
+  type: openbanking.powens
+  operation: listTransactions
+
+inputs:
+  accountId:
+    type: string
+  from?:
+    type: string
+    description: "ISO timestamp lower bound"
+  to?:
+    type: string
+
+outputs:
+  transactions:
+    type: BankTransactionRecord[]
+    description: "Canonical transaction ledger entries"
+
+---
+
+capabilityId: openbanking.balances.read
+provider:
+  type: openbanking.powens
+  operation: getBalances
+
+inputs:
+  accountId:
+    type: string
+  balanceTypes?:
+    type: string[]
+
+outputs:
+  balances:
+    type: AccountBalanceRecord[]
+    description: "Current/available balances with timestamps"`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Primary workflows</h2>
+        <div className="space-y-3">
+          <h3 className="text-lg font-semibold">Account sync</h3>
+          <p className="text-muted-foreground">
+            The workflow{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              pfo.workflow.sync-openbanking-accounts
+            </code>{' '}
+            refreshes account metadata, then surfaces canonical records to other
+            automations.
+          </p>
+        </div>
+        <div className="space-y-3">
+          <h3 className="text-lg font-semibold">Transaction sync</h3>
+          <p className="text-muted-foreground">
+            <code className="bg-background/50 rounded px-2 py-1">
+              pfo.workflow.sync-openbanking-transactions
+            </code>{' '}
+            ingests incremental transactions for each linked account and stores
+            them in the canonical ledger.
+          </p>
+        </div>
+        <div className="space-y-3">
+          <h3 className="text-lg font-semibold">Balance refresh</h3>
+          <p className="text-muted-foreground">
+            <code className="bg-background/50 rounded px-2 py-1">
+              pfo.workflow.refresh-openbanking-balances
+            </code>{' '}
+            retrieves current and available balances to power dashboards and
+            anomaly detection.
+          </p>
+        </div>
+        <div className="space-y-3">
+          <h3 className="text-lg font-semibold">Derived financial overview</h3>
+          <p className="text-muted-foreground">
+            <code className="bg-background/50 rounded px-2 py-1">
+              pfo.workflow.generate-openbanking-overview
+            </code>{' '}
+            aggregates balances, category breakdowns, and cashflow trends into
+            the <code>knowledge.financial-overview</code> space. Only derived
+            summaries are exposed to LLMs.
+          </p>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Telemetry & guardrails</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Telemetry events such as{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              openbanking.accounts.synced
+            </code>{' '}
+            and{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              openbanking.transactions.synced
+            </code>{' '}
+            are emitted automatically with tenant, slot, and config metadata.
+          </li>
+          <li>
+            Guard helpers ensure the{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              primaryOpenBanking
+            </code>{' '}
+            slot is bound and healthy before workflows execute.
+          </li>
+          <li>
+            PII fields (IBAN, counterparty names, descriptions) are redacted via{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              redactOpenBankingTelemetryPayload
+            </code>{' '}
+            before logging or sending telemetry.
+          </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 BYOK credentials per tenant to avoid cross-tenant exposure.
+          </li>
+          <li>
+            Store only canonical entities (BankAccountRecord,
+            BankTransactionRecord). Never persist raw Powens payloads or
+            customer PII in logs.
+          </li>
+          <li>
+            Run the transaction sync on a schedule appropriate for banking SLAs
+            (e.g. every 15 minutes for cashflow dashboards).
+          </li>
+          <li>
+            Pair ledger updates with derived summaries to feed the knowledge
+            layer instead of exposing raw transactions to agents.
+          </li>
+          <li>
+            Monitor telemetry for{' '}
+            <code className="bg-background/50 rounded px-2 py-1">
+              openbanking.*.sync_failed
+            </code>{' '}
+            events to detect credential issues early.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations" className="btn-ghost">
+          Back to Integrations
+        </Link>
+        <Link href="/docs/integrations/stripe" className="btn-primary">
+          Next: Stripe <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,132 @@
+/* eslint-disable no-useless-escape */
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Qdrant Integration: ContractSpec Docs',
+//   description:
+//     'Build semantic search and RAG applications with Qdrant vector database in ContractSpec.',
+// };
+
+export function IntegrationsQdrantPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Qdrant</h1>
+        <p className="text-muted-foreground">
+          Qdrant is a high-performance vector database for semantic search,
+          recommendations, and RAG (Retrieval-Augmented Generation)
+          applications.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Setup</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# .env
+QDRANT_URL=https://...
+QDRANT_API_KEY=...
+QDRANT_COLLECTION=documents`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Storing vectors</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: qdrant-upsert
+provider:
+  type: qdrant
+  operation: upsert
+
+inputs:
+  collection:
+    type: string
+  points:
+    type: array
+    items:
+      type: object
+      properties:
+        id: string
+        vector: array
+        payload: object
+
+outputs:
+  status:
+    type: string`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Semantic search</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: qdrant-search
+provider:
+  type: qdrant
+  operation: search
+
+inputs:
+  collection:
+    type: string
+  vector:
+    type: array
+    items:
+      type: number
+  limit:
+    type: number
+    default: 10
+
+outputs:
+  results:
+    type: array
+    items:
+      type: object
+      properties:
+        id: string
+        score: number
+        payload: object`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">RAG workflow example</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`workflowId: rag-query
+version: '1.0.0'.0.0
+
+steps:
+  - id: generate-embedding
+    capability: openai-embeddings
+    inputs:
+      text: \$\{input.query\}
+
+  - id: search-documents
+    capability: qdrant-search
+    inputs:
+      collection: "documents"
+      vector: \$\{steps.generate-embedding.output.embedding\}
+      limit: 5
+
+  - id: generate-answer
+    capability: openai-chat
+    inputs:
+      messages:
+        - role: "system"
+          content: "Answer based on the context provided"
+        - role: "user"
+          content: |
+            Context: \$\{steps.search-documents.output.results\}
+            Question: \$\{input.query\}`}</pre>
+        </div>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/elevenlabs" className="btn-ghost">
+          Previous: ElevenLabs
+        </Link>
+        <Link href="/docs/integrations/s3" className="btn-primary">
+          Next: S3 Storage <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,78 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Resend Integration: ContractSpec Docs',
+//   description:
+//     "Send transactional emails with Resend's modern API in ContractSpec.",
+// };
+
+export function IntegrationsResendPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Resend</h1>
+        <p className="text-muted-foreground">
+          Resend is a modern email API built for developers. It provides a
+          simple, reliable way to send transactional emails with React Email
+          templates.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Setup</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# .env
+RESEND_API_KEY=re_...
+RESEND_FROM_EMAIL=onboarding@resend.dev`}</pre>
+        </div>
+      </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: resend-send-email
+provider:
+  type: resend
+  operation: sendEmail
+
+inputs:
+  to:
+    type: string
+  subject:
+    type: string
+  html:
+    type: string
+  text:
+    type: string
+    optional: true
+  replyTo:
+    type: string
+    optional: true
+
+outputs:
+  id:
+    type: string`}</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 React Email for type-safe templates</li>
+          <li>Verify your domain for better deliverability</li>
+          <li>Monitor email analytics in the Resend dashboard</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/postmark" className="btn-ghost">
+          Previous: Postmark
+        </Link>
+        <Link href="/docs/integrations/gmail" className="btn-primary">
+          Next: Gmail API <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,106 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'S3-Compatible Storage Integration: ContractSpec Docs',
+//   description:
+//     'Store and retrieve files with S3-compatible object storage in ContractSpec.',
+// };
+
+export function IntegrationsS3Page() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">S3-Compatible Storage</h1>
+        <p className="text-muted-foreground">
+          Store files, images, and documents using any S3-compatible object
+          storage service including AWS S3, Scaleway Object Storage, MinIO,
+          DigitalOcean Spaces, and more.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Setup</h2>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`# .env
+S3_ENDPOINT=https://s3.fr-par.scw.cloud
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+S3_BUCKET=my-bucket
+S3_REGION=fr-par`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Uploading files</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: s3-upload
+provider:
+  type: s3
+  operation: upload
+
+inputs:
+  key:
+    type: string
+    description: "File path in bucket"
+  file:
+    type: file
+  contentType:
+    type: string
+    optional: true
+  metadata:
+    type: object
+    optional: true
+
+outputs:
+  url:
+    type: string
+  etag:
+    type: string`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Generating presigned URLs</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: s3-presigned-url
+provider:
+  type: s3
+  operation: getPresignedUrl
+
+inputs:
+  key:
+    type: string
+  expiresIn:
+    type: number
+    default: 3600
+    description: "Expiration in seconds"
+
+outputs:
+  url:
+    type: string`}</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 presigned URLs for secure, temporary access</li>
+          <li>Set appropriate CORS policies for browser uploads</li>
+          <li>Enable versioning for important files</li>
+          <li>Use lifecycle policies to archive old files</li>
+          <li>Organize files with a clear key structure</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/integrations/qdrant" className="btn-ghost">
+          Previous: Qdrant
+        </Link>
+        <Link href="/docs/integrations/twilio" className="btn-primary">
+          Next: Twilio <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}