@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,206 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/node/integrations/providers/posthog.js

@@ -0,0 +1,136 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/node/integrations/providers/postmark.js

@@ -0,0 +1,128 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/node/integrations/providers/powens.js

@@ -0,0 +1,154 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/powens.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var powensIntegrationSpec = defineIntegration({
+  meta: {
+    key: "openbanking.powens",
+    version: "1.0.0",
+    category: "open-banking",
+    title: "Powens Open Banking (Read)",
+    description: "Read-only Open Banking integration powered by Powens, exposing accounts, transactions, and balances.",
+    domain: "finance",
+    owners: ["platform.finance"],
+    tags: ["open-banking", "powens", "finance"],
+    stability: StabilityEnum.Experimental
+  },
+  supportedModes: ["byok"],
+  capabilities: {
+    provides: [
+      { key: "openbanking.accounts.read", version: "1.0.0" },
+      { key: "openbanking.transactions.read", version: "1.0.0" },
+      { key: "openbanking.balances.read", version: "1.0.0" }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      required: ["environment"],
+      properties: {
+        environment: {
+          type: "string",
+          enum: ["sandbox", "production"],
+          description: "Powens environment to target. Sandbox uses Powens test API base URL, production uses live endpoints."
+        },
+        baseUrl: {
+          type: "string",
+          description: "Optional override for the Powens API base URL. Defaults to Powens environment defaults."
+        },
+        region: {
+          type: "string",
+          description: "Optional Powens region identifier when targeting a specific data residency cluster."
+        },
+        pollingIntervalMs: {
+          type: "number",
+          description: "Optional custom polling interval in milliseconds for background sync jobs (defaults to platform standard)."
+        }
+      }
+    },
+    example: {
+      environment: "sandbox",
+      baseUrl: "https://api-sandbox.powens.com/v2",
+      region: "eu-west-1",
+      pollingIntervalMs: 300000
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["clientId", "clientSecret"],
+      properties: {
+        clientId: {
+          type: "string",
+          description: "Powens OAuth client identifier obtained from the Powens Console (BYOK project)."
+        },
+        clientSecret: {
+          type: "string",
+          description: "Powens OAuth client secret used to exchange for access tokens."
+        },
+        apiKey: {
+          type: "string",
+          description: "Optional Powens API key (if the tenant project exposes a dedicated API token)."
+        },
+        webhookSecret: {
+          type: "string",
+          description: "Optional webhook signing secret used to verify Powens webhook payloads."
+        }
+      }
+    },
+    example: {
+      clientId: "powens-client-id",
+      clientSecret: "powens-client-secret",
+      apiKey: "powens-api-key",
+      webhookSecret: "powens-webhook-secret"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 8000
+  },
+  docsUrl: "https://docs.powens.com/",
+  constraints: {
+    rateLimit: {
+      rph: 1e4,
+      rpm: 600
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create a Powens BYOK project, generate OAuth credentials, and optionally configure webhook delivery for account/transaction updates.",
+    requiredScopes: ["accounts:read", "transactions:read", "balances:read"]
+  }
+});
+function registerPowensIntegration(registry) {
+  return registry.register(powensIntegrationSpec);
+}
+export {
+  registerPowensIntegration,
+  powensIntegrationSpec
+};