@contractspec/lib.contracts-spec 2.0.0

package/dist/integrations/providers/notion.js

@@ -0,0 +1,143 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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/notion.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var notionIntegrationSpec = defineIntegration({
+  meta: {
+    key: "project-management.notion",
+    version: "1.0.0",
+    category: "project-management",
+    title: "Notion",
+    description: "Notion integration for creating shared project summaries and task entries.",
+    domain: "productivity",
+    owners: ["@platform.integrations"],
+    tags: ["project-management", "notion"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "project-management.work-items", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        databaseId: {
+          type: "string",
+          description: "Optional Notion database ID to store tasks."
+        },
+        summaryParentPageId: {
+          type: "string",
+          description: "Optional parent page ID for summary pages."
+        },
+        titleProperty: {
+          type: "string",
+          description: 'Database title property name (defaults to "Name").'
+        },
+        statusProperty: {
+          type: "string",
+          description: "Database status/select property name."
+        },
+        priorityProperty: {
+          type: "string",
+          description: "Database priority/select property name."
+        },
+        tagsProperty: {
+          type: "string",
+          description: "Database multi-select tags property name."
+        },
+        dueDateProperty: {
+          type: "string",
+          description: "Database date property name for due dates."
+        },
+        descriptionProperty: {
+          type: "string",
+          description: "Database rich-text property for descriptions."
+        }
+      }
+    },
+    example: {
+      databaseId: "xxxxxxxxxxxxxxxx",
+      summaryParentPageId: "yyyyyyyyyyyyyyyy",
+      titleProperty: "Name",
+      statusProperty: "Status"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Notion integration secret token."
+        }
+      }
+    },
+    example: {
+      apiKey: "secret_notion_token"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://developers.notion.com",
+  constraints: {},
+  byokSetup: {
+    setupInstructions: "Create a Notion internal integration, share the target database/page with it, and store the secret token."
+  }
+});
+function registerNotionIntegration(registry) {
+  return registry.register(notionIntegrationSpec);
+}
+export {
+  registerNotionIntegration,
+  notionIntegrationSpec
+};

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,206 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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;