@contractspec/example.integration-posthog 1.57.0 → 1.58.0

package/dist/example.d.ts

@@ -1,7 +1,3 @@
-import * as _contractspec_lib_contracts0 from "@contractspec/lib.contracts";
-
-//#region src/example.d.ts
-declare const example: _contractspec_lib_contracts0.ExampleSpec;
-//#endregion
-export { example as default };
+declare const example: import("@contractspec/lib.contracts").ExampleSpec;
+export default example;
 //# sourceMappingURL=example.d.ts.map

package/dist/example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"example.d.ts","names":[],"sources":["../src/example.ts"],"mappings":";;;cAEM,OAAA,EA2BJ,4BAAA,CA3BW,WAAA"}
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../src/example.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,OAAO,mDA2BX,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/dist/example.js

@@ -1,45 +1,34 @@
+// @bun
+// src/example.ts
 import { defineExample } from "@contractspec/lib.contracts";
-
-//#region src/example.ts
-const example = defineExample({
-	meta: {
-		key: "integration-posthog",
-		version: "1.0.0",
-		title: "Integration — PostHog Analytics",
-		description: "Capture events, run HogQL, and manage PostHog assets via AnalyticsProvider.",
-		kind: "integration",
-		visibility: "public",
-		stability: "experimental",
-		owners: ["@platform.integrations"],
-		tags: [
-			"posthog",
-			"analytics",
-			"hogql",
-			"integration"
-		]
-	},
-	docs: {
-		rootDocId: "docs.examples.integration-posthog",
-		usageDocId: "docs.examples.integration-posthog.usage"
-	},
-	entrypoints: {
-		packageName: "@contractspec/example.integration-posthog",
-		docs: "./docs"
-	},
-	surfaces: {
-		templates: true,
-		sandbox: {
-			enabled: true,
-			modes: ["markdown", "specs"]
-		},
-		studio: {
-			enabled: true,
-			installable: true
-		},
-		mcp: { enabled: true }
-	}
+var example = defineExample({
+  meta: {
+    key: "integration-posthog",
+    version: "1.0.0",
+    title: "Integration \u2014 PostHog Analytics",
+    description: "Capture events, run HogQL, and manage PostHog assets via AnalyticsProvider.",
+    kind: "integration",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.integrations"],
+    tags: ["posthog", "analytics", "hogql", "integration"]
+  },
+  docs: {
+    rootDocId: "docs.examples.integration-posthog",
+    usageDocId: "docs.examples.integration-posthog.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.integration-posthog",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown", "specs"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
 });
-
-//#endregion
-export { example as default };
-//# sourceMappingURL=example.js.map
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-import example from "./example.js";
-import { PosthogExampleMode, PosthogExampleOutput, resolvePosthogMode, runPosthogExampleFromEnv } from "./posthog.js";
-export { PosthogExampleMode, PosthogExampleOutput, example, resolvePosthogMode, runPosthogExampleFromEnv };
+export * from './posthog';
+export { default as example } from './example';
+import './docs';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,CAAC"}

package/dist/index.js

@@ -1,5 +1,359 @@
-import example from "./example.js";
-import { resolvePosthogMode, runPosthogExampleFromEnv } from "./posthog.js";
-import "./docs/index.js";
+// @bun
+// src/docs/integration-posthog.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    id: "docs.examples.integration-posthog",
+    title: "Integration Example \u2014 PostHog Analytics",
+    summary: "Capture events, run HogQL, and manage feature flags using the PostHog analytics provider.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog",
+    tags: ["posthog", "analytics", "hogql", "example"],
+    body: `## What this example shows
+- Capture product events and identify users.
+- Run HogQL queries through the analytics provider.
+- Perform generic REST API requests (feature flag list/create/delete).
+- Read events, persons, insights, and feature flags using typed reader methods.
+- Optionally call a PostHog MCP tool via JSON-RPC.
 
-export { example, resolvePosthogMode, runPosthogExampleFromEnv };
+## Guardrails
+- Use dry-run while validating credentials.
+- Writes are gated behind CONTRACTSPEC_POSTHOG_ALLOW_WRITES.
+- Keep API keys in secret storage.`
+  },
+  {
+    id: "docs.examples.integration-posthog.usage",
+    title: "PostHog Integration Example \u2014 Usage",
+    summary: "How to run the PostHog example with env-driven settings.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog/usage",
+    tags: ["posthog", "usage"],
+    body: `## Usage
+- Set CONTRACTSPEC_POSTHOG_MODE to capture | query | request | read | all.
+- Set CONTRACTSPEC_POSTHOG_DRY_RUN=true for a safe preview.
+- Set CONTRACTSPEC_POSTHOG_ALLOW_WRITES=true to enable capture and create/delete.
+
+## Required env vars
+- POSTHOG_PROJECT_ID for queries and REST requests.
+- POSTHOG_PROJECT_API_KEY for capture/identify.
+- POSTHOG_PERSONAL_API_KEY for HogQL queries and REST requests.
+
+## MCP
+- Set POSTHOG_MCP_URL to call tools/call.
+- Optionally set POSTHOG_MCP_TOOL_NAME and POSTHOG_MCP_TOOL_ARGS (JSON).
+
+## Example
+- Call runPosthogExampleFromEnv() from run.ts to execute the flow.`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "integration-posthog",
+    version: "1.0.0",
+    title: "Integration \u2014 PostHog Analytics",
+    description: "Capture events, run HogQL, and manage PostHog assets via AnalyticsProvider.",
+    kind: "integration",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.integrations"],
+    tags: ["posthog", "analytics", "hogql", "integration"]
+  },
+  docs: {
+    rootDocId: "docs.examples.integration-posthog",
+    usageDocId: "docs.examples.integration-posthog.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.integration-posthog",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown", "specs"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+
+// src/posthog.ts
+import { PosthogAnalyticsProvider } from "@contractspec/integration.providers-impls/impls/posthog";
+async function runPosthogExampleFromEnv() {
+  const mode = resolvePosthogMode();
+  const dryRun = resolveBooleanEnv("CONTRACTSPEC_POSTHOG_DRY_RUN", true);
+  const allowWrites = resolveBooleanEnv("CONTRACTSPEC_POSTHOG_ALLOW_WRITES", false);
+  const output = { mode, dryRun, allowWrites };
+  if (dryRun) {
+    if (mode === "capture" || mode === "all") {
+      output.capture = buildCapturePreview();
+    }
+    if (mode === "query" || mode === "all") {
+      output.query = { query: buildHogQLQuery() };
+    }
+    if (mode === "request" || mode === "all") {
+      output.request = buildRequestPreview();
+    }
+    if (mode === "read" || mode === "all") {
+      output.read = buildReadPreview();
+    }
+    if (process.env.POSTHOG_MCP_URL) {
+      output.mcp = buildMcpPreview();
+    }
+    return output;
+  }
+  const provider = createProviderFromEnv();
+  if (mode === "capture" || mode === "all") {
+    output.capture = await runCapture(provider, allowWrites);
+  }
+  if (mode === "query" || mode === "all") {
+    output.query = await runHogQLQuery(provider);
+  }
+  if (mode === "request" || mode === "all") {
+    output.request = await runApiRequests(provider, allowWrites);
+  }
+  if (mode === "read" || mode === "all") {
+    output.read = await runReadOperations(provider);
+  }
+  if (process.env.POSTHOG_MCP_URL) {
+    output.mcp = await runMcpToolCall(provider);
+  }
+  return output;
+}
+function resolvePosthogMode() {
+  const raw = (process.env.CONTRACTSPEC_POSTHOG_MODE ?? "all").toLowerCase();
+  if (raw === "capture" || raw === "query" || raw === "request" || raw === "read" || raw === "all") {
+    return raw;
+  }
+  throw new Error(`Unsupported CONTRACTSPEC_POSTHOG_MODE: ${raw}. Use capture, query, request, read, or all.`);
+}
+function createProviderFromEnv() {
+  return new PosthogAnalyticsProvider({
+    host: process.env.POSTHOG_HOST,
+    projectId: process.env.POSTHOG_PROJECT_ID,
+    projectApiKey: process.env.POSTHOG_PROJECT_API_KEY,
+    personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
+    mcpUrl: process.env.POSTHOG_MCP_URL,
+    requestTimeoutMs: 1e4
+  });
+}
+async function runCapture(provider, allowWrites) {
+  if (!allowWrites) {
+    return {
+      skipped: true,
+      reason: "Set CONTRACTSPEC_POSTHOG_ALLOW_WRITES=true to enable capture."
+    };
+  }
+  const event = buildCaptureEvent();
+  if (provider.identify) {
+    await provider.identify({
+      distinctId: event.distinctId,
+      properties: { plan: "pro", source: "contractspec-example" }
+    });
+  }
+  await provider.capture(event);
+  return { captured: true, event };
+}
+async function runHogQLQuery(provider) {
+  if (!provider.queryHogQL) {
+    throw new Error("Analytics provider does not support HogQL queries.");
+  }
+  const query = buildHogQLQuery();
+  return provider.queryHogQL({ query });
+}
+async function runApiRequests(provider, allowWrites) {
+  const projectId = requireEnv("POSTHOG_PROJECT_ID");
+  const listRequest = {
+    method: "GET",
+    path: `/api/projects/${projectId}/feature_flags/`,
+    query: { limit: 5 }
+  };
+  const listResponse = await provider.request(listRequest);
+  const output = {
+    list: listResponse.data
+  };
+  if (!allowWrites) {
+    output.writeGuard = "Set CONTRACTSPEC_POSTHOG_ALLOW_WRITES=true to create/delete feature flags.";
+    return output;
+  }
+  const flagKey = `contractspec-example-${Date.now()}`;
+  const createResponse = await provider.request({
+    method: "POST",
+    path: `/api/projects/${projectId}/feature_flags/`,
+    body: {
+      name: "ContractSpec Example Flag",
+      key: flagKey,
+      active: true,
+      filters: {
+        groups: [
+          {
+            properties: [],
+            rollout_percentage: 100
+          }
+        ]
+      }
+    }
+  });
+  output.created = createResponse.data;
+  const createdId = extractId(createResponse);
+  if (createdId) {
+    const deleteResponse = await provider.request({
+      method: "DELETE",
+      path: `/api/projects/${projectId}/feature_flags/${createdId}`
+    });
+    output.deleted = deleteResponse.status;
+  } else {
+    output.deleted = "Skipped delete: response did not include an id.";
+  }
+  return output;
+}
+async function runReadOperations(provider) {
+  const now = new Date;
+  const from = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+  const dateRange = { from, to: now };
+  const output = {
+    window: { from: from.toISOString(), to: now.toISOString() }
+  };
+  if (provider.getEvents) {
+    output.events = await provider.getEvents({ dateRange, limit: 5 });
+  } else {
+    output.events = "Provider does not support getEvents.";
+  }
+  if (provider.getPersons) {
+    output.persons = await provider.getPersons({ limit: 5 });
+  } else {
+    output.persons = "Provider does not support getPersons.";
+  }
+  if (provider.getInsights) {
+    output.insights = await provider.getInsights({ limit: 5 });
+  } else {
+    output.insights = "Provider does not support getInsights.";
+  }
+  if (provider.getFeatureFlags) {
+    output.featureFlags = await provider.getFeatureFlags({ limit: 5 });
+  } else {
+    output.featureFlags = "Provider does not support getFeatureFlags.";
+  }
+  return output;
+}
+async function runMcpToolCall(provider) {
+  if (!provider.callMcpTool) {
+    throw new Error("Analytics provider does not support MCP tool calls.");
+  }
+  const name = process.env.POSTHOG_MCP_TOOL_NAME ?? "posthog.query";
+  const argumentsValue = parseOptionalJsonEnv("POSTHOG_MCP_TOOL_ARGS", {
+    query: buildHogQLQuery()
+  });
+  return provider.callMcpTool({ name, arguments: argumentsValue });
+}
+function buildCaptureEvent() {
+  const distinctId = process.env.POSTHOG_DISTINCT_ID ?? "contractspec-demo";
+  const event = process.env.POSTHOG_EVENT_NAME ?? "contractspec.example.event";
+  return {
+    distinctId,
+    event,
+    properties: {
+      source: "contractspec-example",
+      environment: "development"
+    },
+    timestamp: new Date
+  };
+}
+function buildHogQLQuery() {
+  return "select event, count() as count " + "from events " + "where timestamp >= now() - interval 1 day " + "group by event " + "order by count desc " + "limit 5";
+}
+function buildCapturePreview() {
+  return {
+    event: buildCaptureEvent(),
+    hint: "Dry run enabled. Set CONTRACTSPEC_POSTHOG_DRY_RUN=false."
+  };
+}
+function buildRequestPreview() {
+  const projectId = process.env.POSTHOG_PROJECT_ID ?? "PROJECT_ID";
+  return {
+    listRequest: {
+      method: "GET",
+      path: `/api/projects/${projectId}/feature_flags/`,
+      query: { limit: 5 }
+    },
+    writeRequests: {
+      create: {
+        method: "POST",
+        path: `/api/projects/${projectId}/feature_flags/`
+      },
+      delete: {
+        method: "DELETE",
+        path: `/api/projects/${projectId}/feature_flags/{id}`
+      }
+    }
+  };
+}
+function buildReadPreview() {
+  return {
+    events: {
+      dateRange: "last_24_hours",
+      limit: 5
+    },
+    persons: {
+      limit: 5
+    },
+    insights: {
+      limit: 5
+    },
+    featureFlags: {
+      limit: 5
+    }
+  };
+}
+function buildMcpPreview() {
+  return {
+    url: process.env.POSTHOG_MCP_URL,
+    toolName: process.env.POSTHOG_MCP_TOOL_NAME ?? "posthog.query",
+    arguments: parseOptionalJsonEnv("POSTHOG_MCP_TOOL_ARGS", {
+      query: buildHogQLQuery()
+    })
+  };
+}
+function extractId(response) {
+  if (!response || typeof response !== "object")
+    return null;
+  const data = response.data;
+  if (data && (typeof data.id === "string" || typeof data.id === "number")) {
+    return data.id;
+  }
+  return null;
+}
+function resolveBooleanEnv(key, defaultValue) {
+  const value = process.env[key];
+  if (value === undefined)
+    return defaultValue;
+  return value.toLowerCase() === "true";
+}
+function requireEnv(key) {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Missing required env var: ${key}`);
+  }
+  return value;
+}
+function parseOptionalJsonEnv(key, fallback) {
+  const raw = process.env[key];
+  if (!raw)
+    return fallback;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object")
+      return parsed;
+  } catch {
+    throw new Error(`Invalid JSON in ${key}`);
+  }
+  return fallback;
+}
+export {
+  runPosthogExampleFromEnv,
+  resolvePosthogMode,
+  example_default as example
+};

package/dist/node/docs/index.js

@@ -0,0 +1,50 @@
+// src/docs/integration-posthog.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    id: "docs.examples.integration-posthog",
+    title: "Integration Example — PostHog Analytics",
+    summary: "Capture events, run HogQL, and manage feature flags using the PostHog analytics provider.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog",
+    tags: ["posthog", "analytics", "hogql", "example"],
+    body: `## What this example shows
+- Capture product events and identify users.
+- Run HogQL queries through the analytics provider.
+- Perform generic REST API requests (feature flag list/create/delete).
+- Read events, persons, insights, and feature flags using typed reader methods.
+- Optionally call a PostHog MCP tool via JSON-RPC.
+
+## Guardrails
+- Use dry-run while validating credentials.
+- Writes are gated behind CONTRACTSPEC_POSTHOG_ALLOW_WRITES.
+- Keep API keys in secret storage.`
+  },
+  {
+    id: "docs.examples.integration-posthog.usage",
+    title: "PostHog Integration Example — Usage",
+    summary: "How to run the PostHog example with env-driven settings.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog/usage",
+    tags: ["posthog", "usage"],
+    body: `## Usage
+- Set CONTRACTSPEC_POSTHOG_MODE to capture | query | request | read | all.
+- Set CONTRACTSPEC_POSTHOG_DRY_RUN=true for a safe preview.
+- Set CONTRACTSPEC_POSTHOG_ALLOW_WRITES=true to enable capture and create/delete.
+
+## Required env vars
+- POSTHOG_PROJECT_ID for queries and REST requests.
+- POSTHOG_PROJECT_API_KEY for capture/identify.
+- POSTHOG_PERSONAL_API_KEY for HogQL queries and REST requests.
+
+## MCP
+- Set POSTHOG_MCP_URL to call tools/call.
+- Optionally set POSTHOG_MCP_TOOL_NAME and POSTHOG_MCP_TOOL_ARGS (JSON).
+
+## Example
+- Call runPosthogExampleFromEnv() from run.ts to execute the flow.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/docs/integration-posthog.docblock.js

@@ -0,0 +1,50 @@
+// src/docs/integration-posthog.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    id: "docs.examples.integration-posthog",
+    title: "Integration Example — PostHog Analytics",
+    summary: "Capture events, run HogQL, and manage feature flags using the PostHog analytics provider.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog",
+    tags: ["posthog", "analytics", "hogql", "example"],
+    body: `## What this example shows
+- Capture product events and identify users.
+- Run HogQL queries through the analytics provider.
+- Perform generic REST API requests (feature flag list/create/delete).
+- Read events, persons, insights, and feature flags using typed reader methods.
+- Optionally call a PostHog MCP tool via JSON-RPC.
+
+## Guardrails
+- Use dry-run while validating credentials.
+- Writes are gated behind CONTRACTSPEC_POSTHOG_ALLOW_WRITES.
+- Keep API keys in secret storage.`
+  },
+  {
+    id: "docs.examples.integration-posthog.usage",
+    title: "PostHog Integration Example — Usage",
+    summary: "How to run the PostHog example with env-driven settings.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/integration-posthog/usage",
+    tags: ["posthog", "usage"],
+    body: `## Usage
+- Set CONTRACTSPEC_POSTHOG_MODE to capture | query | request | read | all.
+- Set CONTRACTSPEC_POSTHOG_DRY_RUN=true for a safe preview.
+- Set CONTRACTSPEC_POSTHOG_ALLOW_WRITES=true to enable capture and create/delete.
+
+## Required env vars
+- POSTHOG_PROJECT_ID for queries and REST requests.
+- POSTHOG_PROJECT_API_KEY for capture/identify.
+- POSTHOG_PERSONAL_API_KEY for HogQL queries and REST requests.
+
+## MCP
+- Set POSTHOG_MCP_URL to call tools/call.
+- Optionally set POSTHOG_MCP_TOOL_NAME and POSTHOG_MCP_TOOL_ARGS (JSON).
+
+## Example
+- Call runPosthogExampleFromEnv() from run.ts to execute the flow.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "integration-posthog",
+    version: "1.0.0",
+    title: "Integration — PostHog Analytics",
+    description: "Capture events, run HogQL, and manage PostHog assets via AnalyticsProvider.",
+    kind: "integration",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.integrations"],
+    tags: ["posthog", "analytics", "hogql", "integration"]
+  },
+  docs: {
+    rootDocId: "docs.examples.integration-posthog",
+    usageDocId: "docs.examples.integration-posthog.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.integration-posthog",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["markdown", "specs"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};