@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/providers/openbanking.d.ts

@@ -0,0 +1,125 @@
+export type OpenBankingAccountOwnership = 'individual' | 'joint' | 'business' | 'unknown';
+export interface OpenBankingAccountSummary {
+    id: string;
+    externalId: string;
+    tenantId: string;
+    connectionId: string;
+    userId?: string;
+    displayName: string;
+    institutionId: string;
+    institutionName: string;
+    institutionLogoUrl?: string;
+    accountType: string;
+    iban?: string;
+    bic?: string;
+    currency: string;
+    accountNumberMasked?: string;
+    ownership?: OpenBankingAccountOwnership;
+    status?: 'active' | 'inactive' | 'closed' | 'suspended';
+    lastSyncedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OpenBankingAccountDetails extends OpenBankingAccountSummary {
+    productCode?: string;
+    openedAt?: string;
+    closedAt?: string;
+    availableBalance?: number;
+    currentBalance?: number;
+    creditLimit?: number;
+    customFields?: Record<string, unknown>;
+}
+export interface OpenBankingTransaction {
+    id: string;
+    externalId: string;
+    tenantId: string;
+    accountId: string;
+    connectionId: string;
+    amount: number;
+    currency: string;
+    direction: 'debit' | 'credit';
+    description?: string;
+    bookingDate?: string;
+    valueDate?: string;
+    postedAt?: string;
+    category?: string;
+    rawCategory?: string;
+    merchantName?: string;
+    merchantCategoryCode?: string;
+    counterpartyName?: string;
+    counterpartyAccount?: string;
+    reference?: string;
+    status?: 'pending' | 'booked' | 'cancelled';
+    metadata?: Record<string, unknown>;
+}
+export type OpenBankingBalanceType = 'current' | 'available' | 'authorised' | 'uncleared' | 'credit' | (string & {});
+export interface OpenBankingAccountBalance {
+    accountId: string;
+    connectionId: string;
+    tenantId: string;
+    type: OpenBankingBalanceType;
+    currency: string;
+    amount: number;
+    lastUpdatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OpenBankingConnectionStatus {
+    connectionId: string;
+    tenantId: string;
+    status: 'healthy' | 'degraded' | 'error' | 'disconnected';
+    lastCheckedAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    details?: Record<string, unknown>;
+}
+export interface OpenBankingListAccountsParams {
+    tenantId: string;
+    connectionId: string;
+    userId?: string;
+    cursor?: string;
+    pageSize?: number;
+    includeBalances?: boolean;
+    institutionId?: string;
+}
+export interface OpenBankingListAccountsResult {
+    accounts: OpenBankingAccountSummary[];
+    nextCursor?: string;
+    hasMore?: boolean;
+}
+export interface OpenBankingGetAccountDetailsParams {
+    tenantId: string;
+    accountId: string;
+    connectionId: string;
+    includeBalances?: boolean;
+}
+export interface OpenBankingListTransactionsParams {
+    tenantId: string;
+    accountId: string;
+    connectionId: string;
+    from?: string;
+    to?: string;
+    cursor?: string;
+    pageSize?: number;
+    includePending?: boolean;
+}
+export interface OpenBankingListTransactionsResult {
+    transactions: OpenBankingTransaction[];
+    nextCursor?: string;
+    hasMore?: boolean;
+}
+export interface OpenBankingGetBalancesParams {
+    tenantId: string;
+    accountId: string;
+    connectionId: string;
+    balanceTypes?: OpenBankingBalanceType[];
+}
+export interface OpenBankingGetConnectionStatusParams {
+    tenantId: string;
+    connectionId: string;
+}
+export interface OpenBankingProvider {
+    listAccounts(params: OpenBankingListAccountsParams): Promise<OpenBankingListAccountsResult>;
+    getAccountDetails(params: OpenBankingGetAccountDetailsParams): Promise<OpenBankingAccountDetails>;
+    listTransactions(params: OpenBankingListTransactionsParams): Promise<OpenBankingListTransactionsResult>;
+    getBalances(params: OpenBankingGetBalancesParams): Promise<OpenBankingAccountBalance[]>;
+    getConnectionStatus(params: OpenBankingGetConnectionStatusParams): Promise<OpenBankingConnectionStatus>;
+}

package/dist/integrations/providers/openbanking.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/providers/payments.d.ts

@@ -0,0 +1,106 @@
+export interface Money {
+    /** Amount denominated in the smallest currency unit (e.g., cents). */
+    amount: number;
+    currency: string;
+}
+export type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'canceled';
+export interface PaymentCustomer {
+    id: string;
+    email?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface CreateCustomerInput {
+    email?: string;
+    name?: string;
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface PaymentIntent {
+    id: string;
+    amount: Money;
+    status: PaymentIntentStatus;
+    customerId?: string;
+    clientSecret?: string;
+    description?: string;
+    metadata?: Record<string, string>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface CreatePaymentIntentInput {
+    amount: Money;
+    customerId?: string;
+    confirmationMethod?: 'automatic' | 'manual';
+    captureMethod?: 'automatic' | 'manual';
+    description?: string;
+    metadata?: Record<string, string>;
+    statementDescriptor?: string;
+    returnUrl?: string;
+}
+export interface CapturePaymentInput {
+    amount?: Money;
+    receiptEmail?: string;
+    metadata?: Record<string, string>;
+}
+export interface PaymentRefund {
+    id: string;
+    paymentIntentId: string;
+    amount: Money;
+    status: 'pending' | 'succeeded' | 'failed' | 'canceled';
+    reason?: string;
+    metadata?: Record<string, string>;
+    createdAt?: Date;
+}
+export interface RefundPaymentInput {
+    paymentIntentId: string;
+    amount?: Money;
+    reason?: string;
+    metadata?: Record<string, string>;
+}
+export interface PaymentInvoice {
+    id: string;
+    number?: string;
+    status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void' | 'deleted';
+    amountDue: Money;
+    amountPaid?: Money;
+    customerId?: string;
+    dueDate?: Date;
+    hostedInvoiceUrl?: string;
+    metadata?: Record<string, string>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface ListInvoicesQuery {
+    customerId?: string;
+    status?: PaymentInvoice['status'][];
+    limit?: number;
+    startingAfter?: string;
+}
+export interface PaymentTransaction {
+    id: string;
+    paymentIntentId?: string;
+    amount: Money;
+    type: 'capture' | 'refund' | 'payout';
+    status: 'pending' | 'succeeded' | 'failed';
+    description?: string;
+    createdAt: Date;
+    metadata?: Record<string, string>;
+}
+export interface ListTransactionsQuery {
+    customerId?: string;
+    paymentIntentId?: string;
+    limit?: number;
+    startingAfter?: string;
+}
+export interface PaymentsProvider {
+    createCustomer(input: CreateCustomerInput): Promise<PaymentCustomer>;
+    getCustomer(customerId: string): Promise<PaymentCustomer | null>;
+    createPaymentIntent(input: CreatePaymentIntentInput): Promise<PaymentIntent>;
+    capturePayment(paymentIntentId: string, input?: CapturePaymentInput): Promise<PaymentIntent>;
+    cancelPaymentIntent(paymentIntentId: string): Promise<PaymentIntent>;
+    refundPayment(input: RefundPaymentInput): Promise<PaymentRefund>;
+    listInvoices(query?: ListInvoicesQuery): Promise<PaymentInvoice[]>;
+    listTransactions(query?: ListTransactionsQuery): Promise<PaymentTransaction[]>;
+}

package/dist/integrations/providers/payments.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/providers/posthog-llm-telemetry.d.ts

@@ -0,0 +1,51 @@
+import type { TelemetrySpec } from '@contractspec/lib.contracts-spec/telemetry/spec';
+/**
+ * PostHog LLM Analytics telemetry spec.
+ *
+ * Defines the telemetry events captured by the @posthog/ai integration
+ * for LLM observability. Events are captured via withTracing() model wrapping
+ * or the PostHogTelemetryCollector bridge.
+ *
+ * PostHog Evaluations (Relevance, Helpfulness, Hallucination, Toxicity,
+ * Jailbreak, and custom prompts) run server-side on these events.
+ * No client-side code is needed beyond capturing $ai_generation events.
+ */
+export declare const posthogLLMTelemetrySpec: TelemetrySpec;
+/**
+ * PostHog LLM Analytics PII fields that may appear in generation events.
+ * These should be redacted when privacyMode is enabled.
+ */
+export declare const POSTHOG_LLM_PII_FIELDS: readonly ["$ai_input", "$ai_output_choices"];
+/**
+ * PostHog LLM Analytics telemetry event name constants.
+ */
+export declare const POSTHOG_LLM_TELEMETRY_EVENTS: {
+    /** Captured for every LLM generation call */
+    readonly generation: "$ai_generation";
+    /** Captured for LLM trace spans */
+    readonly span: "$ai_span";
+    /** Captured for LLM evaluation results (server-side) */
+    readonly evaluation: "$ai_evaluation";
+};
+export type PostHogLLMTelemetryEvent = (typeof POSTHOG_LLM_TELEMETRY_EVENTS)[keyof typeof POSTHOG_LLM_TELEMETRY_EVENTS];
+/**
+ * Built-in PostHog evaluation templates.
+ * These are configured in PostHog UI under LLM Analytics > Evaluations.
+ */
+export declare const POSTHOG_EVALUATION_TEMPLATES: {
+    /** Whether the output addresses the user's input */
+    readonly relevance: "relevance";
+    /** Whether the response is useful and actionable */
+    readonly helpfulness: "helpfulness";
+    /** Attempts to bypass safety guardrails */
+    readonly jailbreak: "jailbreak";
+    /** Made-up facts or unsupported claims */
+    readonly hallucination: "hallucination";
+    /** Harmful, offensive, or inappropriate content */
+    readonly toxicity: "toxicity";
+};
+export type PostHogEvaluationTemplate = (typeof POSTHOG_EVALUATION_TEMPLATES)[keyof typeof POSTHOG_EVALUATION_TEMPLATES];
+/**
+ * Redact PII fields from PostHog LLM telemetry payload.
+ */
+export declare function redactPostHogLLMTelemetryPayload<T extends Record<string, unknown>>(payload: T): T;

package/dist/integrations/providers/posthog-llm-telemetry.js

@@ -0,0 +1,176 @@
+// @bun
+// src/integrations/providers/posthog-llm-telemetry.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var posthogLLMTelemetrySpec = {
+  meta: {
+    key: "analytics.posthog.llm",
+    version: "1.0.0",
+    title: "PostHog LLM Analytics Telemetry",
+    description: "Telemetry events for PostHog LLM Analytics: generation tracing, token usage, and evaluation-ready metadata.",
+    domain: "analytics",
+    owners: ["@platform.integrations"],
+    tags: ["analytics", "posthog", "llm", "ai", "telemetry"],
+    stability: StabilityEnum.Beta
+  },
+  events: [
+    {
+      key: "posthog.llm.generation",
+      version: "1.0.0",
+      semantics: {
+        who: "AI agent or LLM consumer",
+        what: "Captures an LLM generation call with full observability metadata",
+        why: "Enable LLM performance monitoring, cost tracking, and automated quality evaluations via PostHog"
+      },
+      properties: {
+        $ai_model: {
+          type: "string",
+          required: true,
+          description: "The LLM model identifier (e.g., gpt-4o, claude-sonnet-4-20250514)"
+        },
+        $ai_provider: {
+          type: "string",
+          required: true,
+          description: "The LLM provider (e.g., openai, anthropic, contractspec)"
+        },
+        $ai_latency: {
+          type: "number",
+          required: false,
+          description: "LLM call latency in seconds"
+        },
+        $ai_input_tokens: {
+          type: "number",
+          required: false,
+          description: "Number of input/prompt tokens consumed"
+        },
+        $ai_output_tokens: {
+          type: "number",
+          required: false,
+          description: "Number of output/completion tokens generated"
+        },
+        $ai_total_cost_usd: {
+          type: "number",
+          required: false,
+          description: "Total cost in USD (input + output)"
+        },
+        $ai_is_error: {
+          type: "boolean",
+          required: false,
+          description: "Whether the generation resulted in an error"
+        },
+        $ai_trace_id: {
+          type: "string",
+          required: false,
+          description: "Trace ID for grouping related generations"
+        },
+        $ai_stream: {
+          type: "boolean",
+          required: false,
+          description: "Whether the response was streamed"
+        },
+        $ai_time_to_first_token: {
+          type: "number",
+          required: false,
+          description: "Time to first token in seconds (streaming only)"
+        },
+        $ai_tools: {
+          type: "json",
+          required: false,
+          description: "Tools/functions available to the LLM"
+        },
+        $ai_input: {
+          type: "json",
+          required: false,
+          pii: true,
+          redact: true,
+          description: "Messages sent to the LLM (may contain PII)"
+        },
+        $ai_output_choices: {
+          type: "json",
+          required: false,
+          pii: true,
+          redact: true,
+          description: "Response choices from the LLM (may contain PII)"
+        },
+        contractspec_operation: {
+          type: "string",
+          required: false,
+          description: "ContractSpec operation name"
+        },
+        contractspec_version: {
+          type: "string",
+          required: false,
+          description: "ContractSpec operation version"
+        },
+        contractspec_agent_id: {
+          type: "string",
+          required: false,
+          description: "ContractSpec agent identifier"
+        },
+        contractspec_finish_reason: {
+          type: "string",
+          required: false,
+          description: "AI SDK finish reason (stop, tool-calls, error, etc.)"
+        },
+        contractspec_tool_count: {
+          type: "number",
+          required: false,
+          description: "Number of tool calls made in this step"
+        }
+      },
+      privacy: "internal",
+      tags: ["llm", "generation", "posthog"]
+    }
+  ],
+  config: {
+    defaultRetentionDays: 90,
+    defaultSamplingRate: 1,
+    providers: [
+      {
+        type: "posthog",
+        config: {
+          eventName: "$ai_generation",
+          enableEvaluations: true,
+          evaluationTemplates: [
+            "relevance",
+            "helpfulness",
+            "jailbreak",
+            "hallucination",
+            "toxicity"
+          ]
+        }
+      }
+    ]
+  }
+};
+var POSTHOG_LLM_PII_FIELDS = [
+  "$ai_input",
+  "$ai_output_choices"
+];
+var POSTHOG_LLM_TELEMETRY_EVENTS = {
+  generation: "$ai_generation",
+  span: "$ai_span",
+  evaluation: "$ai_evaluation"
+};
+var POSTHOG_EVALUATION_TEMPLATES = {
+  relevance: "relevance",
+  helpfulness: "helpfulness",
+  jailbreak: "jailbreak",
+  hallucination: "hallucination",
+  toxicity: "toxicity"
+};
+function redactPostHogLLMTelemetryPayload(payload) {
+  const redacted = { ...payload };
+  for (const field of POSTHOG_LLM_PII_FIELDS) {
+    if (field in redacted) {
+      redacted[field] = "[REDACTED]";
+    }
+  }
+  return redacted;
+}
+export {
+  redactPostHogLLMTelemetryPayload,
+  posthogLLMTelemetrySpec,
+  POSTHOG_LLM_TELEMETRY_EVENTS,
+  POSTHOG_LLM_PII_FIELDS,
+  POSTHOG_EVALUATION_TEMPLATES
+};

package/dist/integrations/providers/posthog.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const posthogIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerPosthogIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/posthog.js

@@ -0,0 +1,106 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/posthog.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var posthogIntegrationSpec = defineIntegration({
+  meta: {
+    key: "analytics.posthog",
+    version: "1.1.0",
+    category: "analytics",
+    title: "PostHog",
+    description: "PostHog integration for product analytics, feature flags, HogQL queries, and LLM analytics with evaluations.",
+    domain: "analytics",
+    owners: ["@platform.integrations"],
+    tags: ["analytics", "posthog", "llm", "ai"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [
+      { key: "analytics.events", version: "1.0.0" },
+      { key: "analytics.feature-flags", version: "1.0.0" },
+      { key: "analytics.query", version: "1.0.0" },
+      { key: "analytics.events.read", version: "1.0.0" },
+      { key: "analytics.persons", version: "1.0.0" },
+      { key: "analytics.insights", version: "1.0.0" },
+      { key: "analytics.cohorts", version: "1.0.0" },
+      { key: "analytics.annotations", version: "1.0.0" },
+      { key: "analytics.llm-tracing", version: "1.0.0" },
+      { key: "analytics.llm-evaluations", version: "1.0.0" }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        host: {
+          type: "string",
+          description: "PostHog host (e.g., https://app.posthog.com or self-hosted URL)."
+        },
+        projectId: {
+          type: "string",
+          description: "PostHog project ID for API queries."
+        },
+        mcpUrl: {
+          type: "string",
+          description: "Optional MCP endpoint URL for PostHog tools."
+        }
+      }
+    },
+    example: {
+      host: "https://app.posthog.com",
+      projectId: "12345"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["personalApiKey"],
+      properties: {
+        personalApiKey: {
+          type: "string",
+          description: "PostHog personal API key (required for API reads/writes)."
+        },
+        projectApiKey: {
+          type: "string",
+          description: "PostHog project API key (required for capture/ingest events)."
+        }
+      }
+    },
+    example: {
+      personalApiKey: "phx_personal_api_key",
+      projectApiKey: "phc_project_api_key"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 5000
+  },
+  docsUrl: "https://posthog.com/docs",
+  byokSetup: {
+    setupInstructions: "Generate a PostHog personal API key for read/write operations and a project API key for event capture."
+  }
+});
+function registerPosthogIntegration(registry) {
+  return registry.register(posthogIntegrationSpec);
+}
+export {
+  registerPosthogIntegration,
+  posthogIntegrationSpec
+};

package/dist/integrations/providers/postmark.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const postmarkIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerPostmarkIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/postmark.js

@@ -0,0 +1,98 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/postmark.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var postmarkIntegrationSpec = defineIntegration({
+  meta: {
+    key: "email.postmark",
+    version: "1.0.0",
+    category: "email",
+    title: "Postmark Transactional Email",
+    description: "Postmark integration for transactional email delivery.",
+    domain: "communications",
+    owners: ["platform.messaging"],
+    tags: ["email", "transactional"],
+    stability: StabilityEnum.Stable
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "email.transactional", version: "1.0.0" }],
+    requires: [
+      {
+        key: "platform.webhooks",
+        optional: true,
+        reason: "Optional for inbound bounce handling"
+      }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        messageStream: {
+          type: "string",
+          description: "Optional message stream identifier (e.g., transactional)."
+        },
+        fromEmail: {
+          type: "string",
+          description: "Default From address used for outbound messages."
+        }
+      }
+    },
+    example: {
+      messageStream: "outbound",
+      fromEmail: "notifications@example.com"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["serverToken"],
+      properties: {
+        serverToken: {
+          type: "string",
+          description: "Server token for the Postmark account."
+        }
+      }
+    },
+    example: {
+      serverToken: "server-***"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 3000
+  },
+  docsUrl: "https://postmarkapp.com/developer",
+  constraints: {
+    rateLimit: {
+      rpm: 500
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create a Postmark server token with outbound send permissions and configure allowed from addresses."
+  }
+});
+function registerPostmarkIntegration(registry) {
+  return registry.register(postmarkIntegrationSpec);
+}
+export {
+  registerPostmarkIntegration,
+  postmarkIntegrationSpec
+};

package/dist/integrations/providers/powens.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const powensIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerPowensIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;