@contractspec/example.integration-posthog 1.57.0 → 1.58.0

package/.turbo/turbo-build.log

@@ -1,34 +1,35 @@
-$ bun build:types && bun build:bundle
-$ tsc --noEmit
-$ tsdown
-ℹ tsdown v0.20.3 powered by rolldown v1.0.0-rc.3
-ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/integration-posthog/tsdown.config.js 
-ℹ entry: src/example.ts, src/index.ts, src/posthog.ts, src/run.ts, src/docs/index.ts, src/docs/integration-posthog.docblock.ts
-ℹ target: esnext
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ dist/posthog.js                                 7.59 kB │ gzip: 2.32 kB
-ℹ dist/docs/integration-posthog.docblock.js       1.97 kB │ gzip: 0.94 kB
-ℹ dist/example.js                                 0.99 kB │ gzip: 0.52 kB
-ℹ dist/run.js                                     0.29 kB │ gzip: 0.22 kB
-ℹ dist/index.js                                   0.20 kB │ gzip: 0.13 kB
-ℹ dist/docs/index.js                              0.04 kB │ gzip: 0.06 kB
-ℹ dist/posthog.js.map                            14.43 kB │ gzip: 4.14 kB
-ℹ dist/docs/integration-posthog.docblock.js.map   2.50 kB │ gzip: 1.13 kB
-ℹ dist/example.js.map                             1.46 kB │ gzip: 0.71 kB
-ℹ dist/run.js.map                                 0.49 kB │ gzip: 0.33 kB
-ℹ dist/posthog.d.ts.map                           0.33 kB │ gzip: 0.21 kB
-ℹ dist/example.d.ts.map                           0.13 kB │ gzip: 0.13 kB
-ℹ dist/posthog.d.ts                               0.74 kB │ gzip: 0.36 kB
-ℹ dist/index.d.ts                                 0.26 kB │ gzip: 0.12 kB
-ℹ dist/example.d.ts                               0.25 kB │ gzip: 0.17 kB
-ℹ dist/docs/index.d.ts                            0.01 kB │ gzip: 0.03 kB
-ℹ dist/docs/integration-posthog.docblock.d.ts     0.01 kB │ gzip: 0.03 kB
-ℹ dist/run.d.ts                                   0.01 kB │ gzip: 0.03 kB
-ℹ 18 files, total: 31.72 kB
-[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
-  - rolldown-plugin-dts:generate (55%)
-  - tsdown:external (41%)
-See https://rolldown.rs/options/checks#plugintimings for more details.
+$ contractspec-bun-build prebuild
+$ bun run prebuild && bun run build:bundle && bun run build:types
+$ contractspec-bun-build prebuild
+$ contractspec-bun-build transpile
+[contractspec-bun-build] transpile target=bun root=src entries=6
+Bundled 6 modules in 12ms
 
-✔ Build complete in 20615ms
+  docs/index.js                         1.98 KB   (entry point)
+  ./index.js                            11.20 KB  (entry point)
+  docs/integration-posthog.docblock.js  1.98 KB   (entry point)
+  ./example.js                          1.00 KB   (entry point)
+  ./run.js                              8.37 KB   (entry point)
+  ./posthog.js                          8.25 KB   (entry point)
+
+[contractspec-bun-build] transpile target=node root=src entries=6
+Bundled 6 modules in 26ms
+
+  docs/index.js                         1.96 KB   (entry point)
+  ./index.js                            11.18 KB  (entry point)
+  docs/integration-posthog.docblock.js  1.96 KB   (entry point)
+  ./example.js                          0.99 KB   (entry point)
+  ./run.js                              8.37 KB   (entry point)
+  ./posthog.js                          8.24 KB   (entry point)
+
+[contractspec-bun-build] transpile target=browser root=src entries=6
+Bundled 6 modules in 32ms
+
+  docs/index.js                         1.96 KB   (entry point)
+  ./index.js                            11.18 KB  (entry point)
+  docs/integration-posthog.docblock.js  1.96 KB   (entry point)
+  ./example.js                          0.99 KB   (entry point)
+  ./run.js                              8.37 KB   (entry point)
+  ./posthog.js                          8.24 KB   (entry point)
+
+$ contractspec-bun-build types

package/.turbo/turbo-prebuild.log

@@ -0,0 +1 @@
+$ contractspec-bun-build prebuild

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @contractspec/example.integration-posthog
 
+## 1.58.0
+
+### Minor Changes
+
+- d1f0fd0: chore: Migrate non-app package builds from tsdown to shared Bun tooling, add `@contractspec/tool.bun`, and standardize `prebuild`/`build`/`typecheck` with platform-aware exports and `tsc` declaration emission into `dist`.
+
+### Patch Changes
+
+- Updated dependencies [d1f0fd0]
+- Updated dependencies [4355a9e]
+  - @contractspec/integration.providers-impls@1.58.0
+  - @contractspec/lib.contracts@1.58.0
+
 ## 1.57.0
 
 ### Minor Changes

package/dist/browser/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/browser/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/browser/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
+};

package/dist/browser/index.js

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