@contractspec/lib.contracts-integrations 2.0.0

package/dist/node/integrations/providers/jira.js

@@ -0,0 +1,107 @@
+// 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/jira.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var jiraIntegrationSpec = defineIntegration({
+  meta: {
+    key: "project-management.jira",
+    version: "1.0.0",
+    category: "project-management",
+    title: "Jira Cloud",
+    description: "Jira Cloud integration for creating and tracking work items.",
+    domain: "productivity",
+    owners: ["@platform.integrations"],
+    tags: ["project-management", "jira"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "project-management.work-items", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      required: ["siteUrl"],
+      properties: {
+        siteUrl: {
+          type: "string",
+          description: "Jira Cloud site URL (e.g., https://acme.atlassian.net)."
+        },
+        projectKey: {
+          type: "string",
+          description: "Default Jira project key for new issues."
+        },
+        issueType: {
+          type: "string",
+          description: "Default Jira issue type (e.g., Task, Story)."
+        },
+        defaultLabels: {
+          type: "array",
+          items: { type: "string" },
+          description: "Labels applied to each issue by default."
+        },
+        issueTypeMap: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Optional mapping from work item types to Jira issue types."
+        }
+      }
+    },
+    example: {
+      siteUrl: "https://acme.atlassian.net",
+      projectKey: "PM",
+      issueType: "Task"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["email", "apiToken"],
+      properties: {
+        email: {
+          type: "string",
+          description: "Jira account email used for API token auth."
+        },
+        apiToken: {
+          type: "string",
+          description: "Jira Cloud API token for the account."
+        }
+      }
+    },
+    example: {
+      email: "user@acme.com",
+      apiToken: "jira_api_token"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/",
+  constraints: {},
+  byokSetup: {
+    setupInstructions: "Create a Jira API token and store it with the associated account email."
+  }
+});
+function registerJiraIntegration(registry) {
+  return registry.register(jiraIntegrationSpec);
+}
+export {
+  registerJiraIntegration,
+  jiraIntegrationSpec
+};

package/dist/node/integrations/providers/linear.js

@@ -0,0 +1,106 @@
+// 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/linear.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var linearIntegrationSpec = defineIntegration({
+  meta: {
+    key: "project-management.linear",
+    version: "1.0.0",
+    category: "project-management",
+    title: "Linear",
+    description: "Linear integration for issue tracking and project management workflows.",
+    domain: "productivity",
+    owners: ["@platform.integrations"],
+    tags: ["project-management", "linear"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "project-management.work-items", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      required: ["teamId"],
+      properties: {
+        teamId: {
+          type: "string",
+          description: "Linear team ID that owns created issues."
+        },
+        projectId: {
+          type: "string",
+          description: "Optional default project ID for new issues."
+        },
+        stateId: {
+          type: "string",
+          description: "Optional default workflow state ID."
+        },
+        assigneeId: {
+          type: "string",
+          description: "Optional default assignee ID."
+        },
+        labelIds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional label IDs applied to each issue."
+        },
+        tagLabelMap: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Optional mapping of tags to Linear label IDs (tag -> labelId)."
+        }
+      }
+    },
+    example: {
+      teamId: "team_123",
+      projectId: "proj_456",
+      labelIds: ["label_1", "label_2"]
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Linear API key (personal or service token)."
+        }
+      }
+    },
+    example: {
+      apiKey: "lin_api_key"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://developers.linear.app",
+  constraints: {},
+  byokSetup: {
+    setupInstructions: "Create a Linear API key with issue:write permission and store it as a secret."
+  }
+});
+function registerLinearIntegration(registry) {
+  return registry.register(linearIntegrationSpec);
+}
+export {
+  registerLinearIntegration,
+  linearIntegrationSpec
+};

package/dist/node/integrations/providers/mistral.js

@@ -0,0 +1,93 @@
+// 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/mistral.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var mistralIntegrationSpec = defineIntegration({
+  meta: {
+    key: "ai-llm.mistral",
+    version: "1.0.0",
+    category: "ai-llm",
+    title: "Mistral Large Language Model",
+    description: "Mistral integration providing chat completions and embedding generation.",
+    domain: "ai",
+    owners: ["platform.ai"],
+    tags: ["ai", "llm", "embeddings"],
+    stability: StabilityEnum.Experimental
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [
+      { key: "ai.chat", version: "1.0.0" },
+      { key: "ai.embeddings", version: "1.0.0" }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        model: {
+          type: "string",
+          description: "Default chat completion model (e.g., mistral-large-latest)."
+        },
+        embeddingModel: {
+          type: "string",
+          description: "Embedding model identifier."
+        }
+      }
+    },
+    example: {
+      model: "mistral-large-latest",
+      embeddingModel: "mistral-embed"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Mistral API key with access to chat and embeddings endpoints."
+        }
+      }
+    },
+    example: {
+      apiKey: "mistral-***"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 5000
+  },
+  docsUrl: "https://docs.mistral.ai/platform/endpoints",
+  constraints: {
+    rateLimit: {
+      rpm: 600
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Generate an API key within the Mistral console and ensure the selected models are enabled for the account."
+  }
+});
+function registerMistralIntegration(registry) {
+  return registry.register(mistralIntegrationSpec);
+}
+export {
+  registerMistralIntegration,
+  mistralIntegrationSpec
+};

package/dist/node/integrations/providers/notion.js

@@ -0,0 +1,112 @@
+// 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/node/integrations/providers/posthog-llm-telemetry.js

@@ -0,0 +1,175 @@
+// 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
+};