@contractspec/example.integration-posthog 1.57.0

package/dist/run.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/run.js

@@ -0,0 +1,12 @@
+import { runPosthogExampleFromEnv } from "./posthog.js";
+
+//#region src/run.ts
+runPosthogExampleFromEnv().then((result) => {
+	console.log(JSON.stringify(result, null, 2));
+}).catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});
+
+//#endregion
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","names":[],"sources":["../src/run.ts"],"sourcesContent":["import { runPosthogExampleFromEnv } from './posthog';\n\nrunPosthogExampleFromEnv()\n  .then((result) => {\n    console.log(JSON.stringify(result, null, 2));\n  })\n  .catch((error) => {\n    console.error(error);\n    process.exitCode = 1;\n  });\n"],"mappings":";;;AAEA,0BAA0B,CACvB,MAAM,WAAW;AAChB,SAAQ,IAAI,KAAK,UAAU,QAAQ,MAAM,EAAE,CAAC;EAC5C,CACD,OAAO,UAAU;AAChB,SAAQ,MAAM,MAAM;AACpB,SAAQ,WAAW;EACnB"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@contractspec/example.integration-posthog",
+  "version": "1.57.0",
+  "description": "PostHog analytics integration example: capture events, run HogQL, and manage feature flags.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/integration-posthog.docblock": "./dist/docs/integration-posthog.docblock.js",
+    "./example": "./dist/example.js",
+    "./posthog": "./dist/posthog.js",
+    "./run": "./dist/run.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/integration.providers-impls": "1.57.0",
+    "@contractspec/lib.contracts": "1.57.0"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.57.0",
+    "@contractspec/tool.typescript": "1.57.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/integration-posthog.docblock": "./dist/docs/integration-posthog.docblock.js",
+      "./example": "./dist/example.js",
+      "./posthog": "./dist/posthog.js",
+      "./run": "./dist/run.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/integration-posthog"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './integration-posthog.docblock';

package/src/docs/integration-posthog.docblock.ts

@@ -0,0 +1,53 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    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/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+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 },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './posthog';
+export { default as example } from './example';
+import './docs';

package/src/posthog.ts

@@ -0,0 +1,362 @@
+import { PosthogAnalyticsProvider } from '@contractspec/integration.providers-impls/impls/posthog';
+import type {
+  AnalyticsEventInput,
+  AnalyticsProvider,
+  AnalyticsQueryResult,
+  AnalyticsRequest,
+  AnalyticsResponse,
+} from '@contractspec/integration.providers-impls/analytics';
+
+export type PosthogExampleMode =
+  | 'capture'
+  | 'query'
+  | 'request'
+  | 'read'
+  | 'all';
+
+export interface PosthogExampleOutput {
+  mode: PosthogExampleMode;
+  dryRun: boolean;
+  allowWrites: boolean;
+  capture?: unknown;
+  query?: AnalyticsQueryResult | unknown;
+  request?: Record<string, unknown>;
+  read?: Record<string, unknown>;
+  mcp?: unknown;
+}
+
+export async function runPosthogExampleFromEnv(): Promise<PosthogExampleOutput> {
+  const mode = resolvePosthogMode();
+  const dryRun = resolveBooleanEnv('CONTRACTSPEC_POSTHOG_DRY_RUN', true);
+  const allowWrites = resolveBooleanEnv(
+    'CONTRACTSPEC_POSTHOG_ALLOW_WRITES',
+    false
+  );
+  const output: PosthogExampleOutput = { 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;
+}
+
+export function resolvePosthogMode(): PosthogExampleMode {
+  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(): AnalyticsProvider {
+  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: 10000,
+  });
+}
+
+async function runCapture(
+  provider: AnalyticsProvider,
+  allowWrites: boolean
+): Promise<Record<string, unknown>> {
+  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: AnalyticsProvider
+): Promise<AnalyticsQueryResult> {
+  if (!provider.queryHogQL) {
+    throw new Error('Analytics provider does not support HogQL queries.');
+  }
+  const query = buildHogQLQuery();
+  return provider.queryHogQL({ query });
+}
+
+async function runApiRequests(
+  provider: AnalyticsProvider,
+  allowWrites: boolean
+): Promise<Record<string, unknown>> {
+  const projectId = requireEnv('POSTHOG_PROJECT_ID');
+  const listRequest: AnalyticsRequest = {
+    method: 'GET',
+    path: `/api/projects/${projectId}/feature_flags/`,
+    query: { limit: 5 },
+  };
+  const listResponse = await provider.request(listRequest);
+  const output: Record<string, unknown> = {
+    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: AnalyticsProvider
+): Promise<Record<string, unknown>> {
+  const now = new Date();
+  const from = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+  const dateRange = { from, to: now };
+  const output: Record<string, unknown> = {
+    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: AnalyticsProvider): Promise<unknown> {
+  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(): AnalyticsEventInput {
+  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: process.env.NODE_ENV ?? 'development',
+    },
+    timestamp: new Date(),
+  };
+}
+
+function buildHogQLQuery(): string {
+  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(): Record<string, unknown> {
+  return {
+    event: buildCaptureEvent(),
+    hint: 'Dry run enabled. Set CONTRACTSPEC_POSTHOG_DRY_RUN=false.',
+  };
+}
+
+function buildRequestPreview(): Record<string, unknown> {
+  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(): Record<string, unknown> {
+  return {
+    events: {
+      dateRange: 'last_24_hours',
+      limit: 5,
+    },
+    persons: {
+      limit: 5,
+    },
+    insights: {
+      limit: 5,
+    },
+    featureFlags: {
+      limit: 5,
+    },
+  };
+}
+
+function buildMcpPreview(): Record<string, unknown> {
+  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: AnalyticsResponse<unknown>
+): string | number | null {
+  if (!response || typeof response !== 'object') return null;
+  const data = response.data as { id?: string | number } | null | undefined;
+  if (data && (typeof data.id === 'string' || typeof data.id === 'number')) {
+    return data.id;
+  }
+  return null;
+}
+
+function resolveBooleanEnv(key: string, defaultValue: boolean): boolean {
+  const value = process.env[key];
+  if (value === undefined) return defaultValue;
+  return value.toLowerCase() === 'true';
+}
+
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Missing required env var: ${key}`);
+  }
+  return value;
+}
+
+function parseOptionalJsonEnv(
+  key: string,
+  fallback: Record<string, unknown>
+): Record<string, unknown> {
+  const raw = process.env[key];
+  if (!raw) return fallback;
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch {
+    throw new Error(`Invalid JSON in ${key}`);
+  }
+  return fallback;
+}

package/src/run.ts

@@ -0,0 +1,10 @@
+import { runPosthogExampleFromEnv } from './posthog';
+
+runPosthogExampleFromEnv()
+  .then((result) => {
+    console.log(JSON.stringify(result, null, 2));
+  })
+  .catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}