// @bun
// src/components/docs/integrations/IntegrationsSpecModelPage.tsx
import Link from "@contractspec/lib.ui-link";
import { ChevronRight } from "lucide-react";
import { jsx, jsxs } from "react/jsx-runtime";
function IntegrationsSpecModelPage() {
  return /* @__PURE__ */ jsxs("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h1", {
            className: "text-4xl font-bold",
            children: "Integration Spec Model"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Integrations in ContractSpec are defined through typed specifications that declare capabilities, configuration requirements, and connection details. This page covers IntegrationSpec and IntegrationConnection."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "IntegrationSpec"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "The ",
              /* @__PURE__ */ jsx("strong", {
                children: "IntegrationSpec"
              }),
              " is a global definition of an integration provider. It declares what the integration provides and what it requires."
            ]
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `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;
};`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example: Stripe IntegrationSpec"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `{
  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"
}`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "IntegrationConnection"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "An ",
              /* @__PURE__ */ jsx("strong", {
                children: "IntegrationConnection"
              }),
              " is a per-tenant instance of an integration with configured credentials and environment settings."
            ]
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `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;
};`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example: Stripe IntegrationConnection"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `// 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"
}`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example: Messaging IntegrationConnection"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "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."
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `{
  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": "..."
}`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Health transport strategy config"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Health providers support deterministic transport routing and explicit unofficial gating in connection config."
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `{
  "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": "..."
}`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Health checks"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "IntegrationConnections are periodically health-checked to ensure they remain valid:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "API key validation"
                  }),
                  " - Test that credentials are still valid"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Connectivity check"
                  }),
                  " - Verify network access to the provider"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Permission verification"
                  }),
                  " - Ensure required scopes are granted"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Webhook validation"
                  }),
                  " - Test webhook endpoint reachability"
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: 'Failed health checks update the connection status to "error" and trigger alerts.'
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Secret management"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Secrets (API keys, tokens) are never stored in plaintext:"
          }),
          /* @__PURE__ */ jsxs("ol", {
            className: "text-muted-foreground list-inside list-decimal space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "User provides secrets through secure UI or API"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Secrets are encrypted using tenant-specific keys"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Encrypted secrets are stored in secure vault (e.g., AWS Secrets Manager)"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "IntegrationConnection stores only a reference (secretRef)"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "At runtime, secrets are decrypted on-demand and never logged"
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Always maintain separate sandbox and production connections"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Use descriptive connection IDs that include tenant and environment"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Monitor health check status and set up alerts for failures"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Rotate secrets regularly and update secretRef accordingly"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Document the purpose and ownership of each connection"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Test connections in sandbox before enabling in production"
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx(Link, {
            href: "/docs/integrations",
            className: "btn-ghost",
            children: "Back to Integrations"
          }),
          /* @__PURE__ */ jsxs(Link, {
            href: "/docs/architecture/integration-binding",
            className: "btn-primary",
            children: [
              "Integration Binding ",
              /* @__PURE__ */ jsx(ChevronRight, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}
export {
  IntegrationsSpecModelPage
};
