@contractspec/integration.providers-impls 1.57.0 → 1.58.0

package/dist/node/impls/posthog-reader.js

@@ -0,0 +1,159 @@
+// src/impls/posthog-reader.ts
+class PosthogAnalyticsReader {
+  projectId;
+  client;
+  constructor(options) {
+    this.projectId = options.projectId;
+    this.client = options.client;
+  }
+  async queryHogQL(input) {
+    const projectId = resolveProjectId(undefined, this.projectId);
+    const response = await this.client.request({
+      method: "POST",
+      path: `/api/projects/${projectId}/query`,
+      body: {
+        query: {
+          kind: "HogQLQuery",
+          query: input.query,
+          values: input.values
+        }
+      }
+    });
+    return response.data;
+  }
+  async getEvents(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/events/`,
+      query: {
+        event: input.event ?? resolveSingleEvent(input.events),
+        events: resolveEventList(input.events),
+        distinct_id: input.distinctId,
+        order_by: input.orderBy,
+        limit: input.limit,
+        offset: input.offset,
+        properties: input.properties ? JSON.stringify(input.properties) : undefined,
+        ...buildEventDateQuery(input.dateRange)
+      }
+    });
+    return response.data;
+  }
+  async getPersons(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/persons/`,
+      query: {
+        cohort_id: input.cohortId,
+        search: input.search,
+        limit: input.limit,
+        offset: input.offset,
+        properties: input.properties ? JSON.stringify(input.properties) : undefined
+      }
+    });
+    return response.data;
+  }
+  async getInsights(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/insights/`,
+      query: {
+        insight: input.insightType,
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getInsightResult(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/insights/${input.insightId}/`
+    });
+    return response.data;
+  }
+  async getCohorts(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/cohorts/`,
+      query: {
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getFeatureFlags(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/feature_flags/`,
+      query: {
+        active: input.active,
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getAnnotations(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/annotations/`,
+      query: {
+        limit: input.limit,
+        offset: input.offset,
+        ...buildAnnotationDateQuery(input.dateRange)
+      }
+    });
+    return response.data;
+  }
+}
+function resolveProjectId(inputProjectId, defaultProjectId) {
+  const projectId = inputProjectId ?? defaultProjectId;
+  if (!projectId) {
+    throw new Error("PostHog projectId is required for API reads.");
+  }
+  return projectId;
+}
+function resolveSingleEvent(events) {
+  if (!events || events.length !== 1)
+    return;
+  return events[0];
+}
+function resolveEventList(events) {
+  if (!events || events.length <= 1)
+    return;
+  return events.join(",");
+}
+function buildEventDateQuery(range) {
+  const after = formatDate(range?.from);
+  const before = formatDate(range?.to);
+  return {
+    after,
+    before,
+    timezone: range?.timezone
+  };
+}
+function buildAnnotationDateQuery(range) {
+  const dateFrom = formatDate(range?.from);
+  const dateTo = formatDate(range?.to);
+  return {
+    date_from: dateFrom,
+    date_to: dateTo,
+    timezone: range?.timezone
+  };
+}
+function formatDate(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+export {
+  PosthogAnalyticsReader
+};

package/dist/node/impls/posthog-utils.js

@@ -0,0 +1,38 @@
+// src/impls/posthog-utils.ts
+function normalizeHost(host) {
+  return host.replace(/\/$/, "");
+}
+function buildUrl(host, path, query) {
+  if (/^https?:\/\//.test(path)) {
+    return appendQuery(path, query);
+  }
+  const normalizedPath = path.replace(/^\/+/, "");
+  return appendQuery(`${host}/${normalizedPath}`, query);
+}
+function appendQuery(url, query) {
+  if (!query)
+    return url;
+  const params = new URLSearchParams;
+  Object.entries(query).forEach(([key, value]) => {
+    if (value === undefined)
+      return;
+    params.set(key, String(value));
+  });
+  const suffix = params.toString();
+  return suffix ? `${url}?${suffix}` : url;
+}
+function parseJson(value) {
+  if (!value)
+    return {};
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+export {
+  parseJson,
+  normalizeHost,
+  buildUrl,
+  appendQuery
+};

package/dist/node/impls/posthog.js

@@ -0,0 +1,322 @@
+// src/impls/posthog-reader.ts
+class PosthogAnalyticsReader {
+  projectId;
+  client;
+  constructor(options) {
+    this.projectId = options.projectId;
+    this.client = options.client;
+  }
+  async queryHogQL(input) {
+    const projectId = resolveProjectId(undefined, this.projectId);
+    const response = await this.client.request({
+      method: "POST",
+      path: `/api/projects/${projectId}/query`,
+      body: {
+        query: {
+          kind: "HogQLQuery",
+          query: input.query,
+          values: input.values
+        }
+      }
+    });
+    return response.data;
+  }
+  async getEvents(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/events/`,
+      query: {
+        event: input.event ?? resolveSingleEvent(input.events),
+        events: resolveEventList(input.events),
+        distinct_id: input.distinctId,
+        order_by: input.orderBy,
+        limit: input.limit,
+        offset: input.offset,
+        properties: input.properties ? JSON.stringify(input.properties) : undefined,
+        ...buildEventDateQuery(input.dateRange)
+      }
+    });
+    return response.data;
+  }
+  async getPersons(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/persons/`,
+      query: {
+        cohort_id: input.cohortId,
+        search: input.search,
+        limit: input.limit,
+        offset: input.offset,
+        properties: input.properties ? JSON.stringify(input.properties) : undefined
+      }
+    });
+    return response.data;
+  }
+  async getInsights(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/insights/`,
+      query: {
+        insight: input.insightType,
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getInsightResult(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/insights/${input.insightId}/`
+    });
+    return response.data;
+  }
+  async getCohorts(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/cohorts/`,
+      query: {
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getFeatureFlags(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/feature_flags/`,
+      query: {
+        active: input.active,
+        limit: input.limit,
+        offset: input.offset
+      }
+    });
+    return response.data;
+  }
+  async getAnnotations(input) {
+    const projectId = resolveProjectId(input.projectId, this.projectId);
+    const response = await this.client.request({
+      method: "GET",
+      path: `/api/projects/${projectId}/annotations/`,
+      query: {
+        limit: input.limit,
+        offset: input.offset,
+        ...buildAnnotationDateQuery(input.dateRange)
+      }
+    });
+    return response.data;
+  }
+}
+function resolveProjectId(inputProjectId, defaultProjectId) {
+  const projectId = inputProjectId ?? defaultProjectId;
+  if (!projectId) {
+    throw new Error("PostHog projectId is required for API reads.");
+  }
+  return projectId;
+}
+function resolveSingleEvent(events) {
+  if (!events || events.length !== 1)
+    return;
+  return events[0];
+}
+function resolveEventList(events) {
+  if (!events || events.length <= 1)
+    return;
+  return events.join(",");
+}
+function buildEventDateQuery(range) {
+  const after = formatDate(range?.from);
+  const before = formatDate(range?.to);
+  return {
+    after,
+    before,
+    timezone: range?.timezone
+  };
+}
+function buildAnnotationDateQuery(range) {
+  const dateFrom = formatDate(range?.from);
+  const dateTo = formatDate(range?.to);
+  return {
+    date_from: dateFrom,
+    date_to: dateTo,
+    timezone: range?.timezone
+  };
+}
+function formatDate(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+
+// src/impls/posthog-utils.ts
+function normalizeHost(host) {
+  return host.replace(/\/$/, "");
+}
+function buildUrl(host, path, query) {
+  if (/^https?:\/\//.test(path)) {
+    return appendQuery(path, query);
+  }
+  const normalizedPath = path.replace(/^\/+/, "");
+  return appendQuery(`${host}/${normalizedPath}`, query);
+}
+function appendQuery(url, query) {
+  if (!query)
+    return url;
+  const params = new URLSearchParams;
+  Object.entries(query).forEach(([key, value]) => {
+    if (value === undefined)
+      return;
+    params.set(key, String(value));
+  });
+  const suffix = params.toString();
+  return suffix ? `${url}?${suffix}` : url;
+}
+function parseJson(value) {
+  if (!value)
+    return {};
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+// src/impls/posthog.ts
+import { PostHog } from "posthog-node";
+var DEFAULT_POSTHOG_HOST = "https://app.posthog.com";
+
+class PosthogAnalyticsProvider {
+  host;
+  projectId;
+  projectApiKey;
+  personalApiKey;
+  mcpUrl;
+  fetchFn;
+  client;
+  reader;
+  constructor(options) {
+    this.host = normalizeHost(options.host ?? DEFAULT_POSTHOG_HOST);
+    this.projectId = options.projectId;
+    this.projectApiKey = options.projectApiKey;
+    this.personalApiKey = options.personalApiKey;
+    this.mcpUrl = options.mcpUrl;
+    this.fetchFn = options.fetch ?? fetch;
+    this.client = options.client ?? (options.projectApiKey ? new PostHog(options.projectApiKey, {
+      host: this.host,
+      requestTimeout: options.requestTimeoutMs ?? 1e4
+    }) : undefined);
+    this.reader = new PosthogAnalyticsReader({
+      projectId: this.projectId,
+      client: { request: this.request.bind(this) }
+    });
+  }
+  async capture(event) {
+    if (!this.client) {
+      throw new Error("PostHog projectApiKey is required for capture.");
+    }
+    await this.client.capture({
+      distinctId: event.distinctId,
+      event: event.event,
+      properties: event.properties,
+      timestamp: event.timestamp,
+      groups: event.groups
+    });
+  }
+  async identify(input) {
+    if (!this.client) {
+      throw new Error("PostHog projectApiKey is required for identify.");
+    }
+    await this.client.identify({
+      distinctId: input.distinctId,
+      properties: {
+        ...input.properties ? { $set: input.properties } : {},
+        ...input.setOnce ? { $set_once: input.setOnce } : {}
+      }
+    });
+  }
+  async queryHogQL(input) {
+    return this.reader.queryHogQL(input);
+  }
+  async getEvents(input) {
+    return this.reader.getEvents(input);
+  }
+  async getPersons(input) {
+    return this.reader.getPersons(input);
+  }
+  async getInsights(input) {
+    return this.reader.getInsights(input);
+  }
+  async getInsightResult(input) {
+    return this.reader.getInsightResult(input);
+  }
+  async getCohorts(input) {
+    return this.reader.getCohorts(input);
+  }
+  async getFeatureFlags(input) {
+    return this.reader.getFeatureFlags(input);
+  }
+  async getAnnotations(input) {
+    return this.reader.getAnnotations(input);
+  }
+  async request(request) {
+    if (!this.personalApiKey) {
+      throw new Error("PostHog personalApiKey is required for API requests.");
+    }
+    const url = buildUrl(this.host, request.path, request.query);
+    const response = await this.fetchFn(url, {
+      method: request.method,
+      headers: {
+        Authorization: `Bearer ${this.personalApiKey}`,
+        "Content-Type": "application/json",
+        ...request.headers ?? {}
+      },
+      body: request.body ? JSON.stringify(request.body) : undefined
+    });
+    const text = await response.text();
+    const data = parseJson(text);
+    return {
+      status: response.status,
+      data,
+      headers: Object.fromEntries(response.headers.entries())
+    };
+  }
+  async callMcpTool(call) {
+    if (!this.mcpUrl) {
+      throw new Error("PostHog MCP URL is not configured.");
+    }
+    const response = await this.fetchFn(this.mcpUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: call.name,
+          arguments: call.arguments ?? {}
+        }
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`PostHog MCP error (${response.status}): ${body}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+      throw new Error(result.error.message ?? "PostHog MCP error");
+    }
+    return result.result ?? null;
+  }
+}
+export {
+  PosthogAnalyticsProvider
+};

package/dist/node/impls/postmark-email.js

@@ -0,0 +1,60 @@
+// src/impls/postmark-email.ts
+import { ServerClient } from "postmark";
+
+class PostmarkEmailProvider {
+  client;
+  defaultFromEmail;
+  messageStream;
+  constructor(options) {
+    this.client = options.client ?? new ServerClient(options.serverToken, {
+      useHttps: true
+    });
+    this.defaultFromEmail = options.defaultFromEmail;
+    this.messageStream = options.messageStream;
+  }
+  async sendEmail(message) {
+    const request = {
+      From: formatAddress(message.from) ?? this.defaultFromEmail,
+      To: message.to.map((addr) => formatAddress(addr)).join(", "),
+      Cc: message.cc?.map((addr) => formatAddress(addr)).join(", ") || undefined,
+      Bcc: message.bcc?.map((addr) => formatAddress(addr)).join(", ") || undefined,
+      ReplyTo: message.replyTo ? formatAddress(message.replyTo) : undefined,
+      Subject: message.subject,
+      TextBody: message.textBody,
+      HtmlBody: message.htmlBody,
+      Headers: message.headers ? Object.entries(message.headers).map(([name, value]) => ({
+        Name: name,
+        Value: value
+      })) : undefined,
+      MessageStream: this.messageStream,
+      Attachments: buildAttachments(message)
+    };
+    const response = await this.client.sendEmail(request);
+    return {
+      id: response.MessageID,
+      providerMessageId: response.MessageID,
+      queuedAt: new Date(response.SubmittedAt ?? new Date().toISOString())
+    };
+  }
+}
+function formatAddress(address) {
+  if (address.name) {
+    return `"${address.name}" <${address.email}>`;
+  }
+  return address.email;
+}
+function buildAttachments(message) {
+  if (!message.attachments?.length)
+    return;
+  return message.attachments.filter((attachment) => attachment.data).map((attachment) => ({
+    Name: attachment.filename,
+    Content: Buffer.from(attachment.data ?? new Uint8Array).toString("base64"),
+    ContentType: attachment.contentType,
+    ContentID: null,
+    ContentLength: attachment.sizeBytes,
+    Disposition: "attachment"
+  }));
+}
+export {
+  PostmarkEmailProvider
+};