posthog-flag-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backhandvolley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# posthog-flag-toolkit
+
+[![CI](https://github.com/backhandvolley/posthog-flag-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/backhandvolley/posthog-flag-toolkit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/posthog-flag-toolkit)](https://www.npmjs.com/package/posthog-flag-toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Type-safe feature flag registry, one-way sync, release tracking, and auto-rollback guardian for [PostHog](https://posthog.com). Framework-agnostic core with optional adapters for Inngest and Slack.
+
+## Install
+
+```bash
+npm install posthog-flag-toolkit
+```
+
+## Quick Start
+
+### 1. Define your registry
+
+```typescript
+import { createRegistry, type FlagDefinition } from "posthog-flag-toolkit";
+
+const { NAMING_REGEX, getLifecycle, getArea } = createRegistry({
+  areas: ["studio", "ai", "billing", "auth"] as const,
+});
+
+const registry = {
+  RELEASE_STUDIO_NEW_EDITOR: {
+    key: "release_studio_new_editor",
+    description: "Gates the new Tiptap-based editor in the studio.",
+    owner: "@yourname",
+    tags: ["studio"],
+    guardian: true,
+  },
+} as const satisfies Record<string, FlagDefinition>;
+```
+
+### 2. Sync flags to PostHog
+
+```typescript
+import { runFlagSync } from "posthog-flag-toolkit";
+
+const result = await runFlagSync({
+  posthog: { apiKey: "phx_...", projectId: "12345" },
+  registry,
+  namingRegex: NAMING_REGEX,
+  callbacks: {
+    onCreate: (def) => console.log(`Created ${def.key}`),
+    onOrphan: (flag) => console.log(`Orphan: ${flag.key}`),
+  },
+});
+```
+
+### 3. Track releases
+
+```typescript
+import { runReleaseTracker } from "posthog-flag-toolkit";
+
+const result = await runReleaseTracker({
+  posthog: { apiKey: "phx_...", projectId: "12345" },
+  registry,
+  namingRegex: NAMING_REGEX,
+  callbacks: {
+    onNewRelease: (flag, type) => console.log(`Released: ${flag.key} (${type})`),
+    onStale: (flag, days) => console.log(`Stale: ${flag.key} (${days} days)`),
+    onDigestReady: (digest) => sendEmail(digest),
+  },
+});
+```
+
+### 4. Auto-rollback with Guardian
+
+```typescript
+import { runFlagGuardian } from "posthog-flag-toolkit";
+
+const result = await runFlagGuardian({
+  posthog: { apiKey: "phx_...", projectId: "12345" },
+  thresholds: { errorRateRatioThreshold: 2.0 },
+  callbacks: {
+    onRegression: (evaluation) => alert(evaluation),
+    onEnforced: (flag) => console.log(`Auto-disabled: ${flag.key}`),
+  },
+});
+```
+
+## Inngest Adapter
+
+For durable execution with [Inngest](https://www.inngest.com/), pass `step` as the `StepRunner`:
+
+```typescript
+import { runFlagSync } from "posthog-flag-toolkit";
+
+export const syncFn = inngest.createFunction(
+  { id: "flag-sync" },
+  { cron: "*/10 * * * *" },
+  async ({ step }) => {
+    return runFlagSync({ posthog: config, registry, namingRegex, step });
+  },
+);
+```
+
+Or use the `withInngestCron` helper:
+
+```typescript
+import { withInngestCron } from "posthog-flag-toolkit/adapters/inngest";
+
+export const syncFn = withInngestCron(inngest, {
+  id: "flag-sync",
+  name: "Sync flags",
+  cron: "*/10 * * * *",
+  run: (step) => runFlagSync({ posthog: config, registry, namingRegex, step }),
+});
+```
+
+## Slack Adapter
+
+```typescript
+import { postGuardianAlert } from "posthog-flag-toolkit/adapters/slack";
+
+await postGuardianAlert(webhookUrl, {
+  severity: "critical",
+  flagKey: "release_studio_new_editor",
+  flagName: "New Editor",
+  decision: "auto_disabled",
+  enforced: true,
+  reason: "error rate ratio 3.2x",
+  metrics: { treatmentErrorRate: 0.15, controlErrorRate: 0.047 },
+  posthogFlagUrl: "https://us.posthog.com/project/12345/feature_flags/42",
+});
+```
+
+## API
+
+### Core Functions
+
+| Function | Description |
+|---|---|
+| `runFlagSync(options)` | One-way sync from registry to PostHog (create, reconcile, detect orphans) |
+| `runReleaseTracker(options)` | Detect 100% rollout releases, stale flags, experiments |
+| `runFlagGuardian(options)` | Compare treatment/control cohorts, auto-disable on regression |
+| `createRegistry(config)` | Factory for typed flag registry with naming regex |
+
+### PostHog API Helpers
+
+| Function | Description |
+|---|---|
+| `fetchAllFlags(config)` | Paginated fetch of all flags |
+| `fetchFlagsByTag(config, tag)` | Fetch flags by tag (substring filter) |
+| `createFlag(config, body)` | Create a new flag |
+| `patchFlag(config, flagId, patch)` | Update a flag |
+| `isFullyReleased(flag)` | Check if flag is active + 100% rollout |
+| `queryCohortMetrics(params)` | HogQL query for treatment/control metrics |
+
+### Guardian Decision Logic
+
+| Function | Description |
+|---|---|
+| `detectRegression(metrics, thresholds)` | Pure function: compare metrics against thresholds |
+| `meetsSampleFloor(metrics, thresholds)` | Check if both cohorts have enough data |
+| `mergeThresholds(overrides?)` | Merge custom thresholds with defaults |
+
+All `run*` functions accept an optional `step: StepRunner` parameter. Inngest's `step` object satisfies the interface natively. Without it, a `SimpleStepRunner` is used (direct execution, no durability).
+
+## Configuration
+
+### PostHogClientConfig
+
+```typescript
+{ apiKey: string; projectId: string; baseUrl?: string }
+```
+
+### GuardianThresholds
+
+| Option | Default | Description |
+|---|---|---|
+| `windowMinutes` | 20 | HogQL lookback window |
+| `minSampleSize` | 100 | Min events per cohort |
+| `minUniqueUsers` | 50 | Min distinct users per cohort |
+| `errorRateRatioThreshold` | 2.0 | Treatment/control error rate ratio |
+| `publishSuccessDropThreshold` | 0.15 | Max acceptable success rate drop (pp) |
+| `cooldownMinutes` | 30 | Skip recently-updated flags |
+
+## License
+
+MIT

package/dist/adapters/inngest.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+// src/adapters/inngest.ts
+function withInngestCron(inngest, config) {
+  return inngest.createFunction(
+    {
+      id: config.id,
+      name: config.name,
+      retries: config.retries ?? 1
+    },
+    { cron: config.cron },
+    async ({ step }) => {
+      return config.run(step);
+    }
+  );
+}
+
+exports.withInngestCron = withInngestCron;
+//# sourceMappingURL=inngest.cjs.map
+//# sourceMappingURL=inngest.cjs.map

package/dist/adapters/inngest.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/inngest.ts"],"names":[],"mappings":";;;AA4BO,SAAS,eAAA,CACd,SACA,MAAA,EACA;AACA,EAAA,OAAO,OAAA,CAAQ,cAAA;AAAA,IACb;AAAA,MACE,IAAI,MAAA,CAAO,EAAA;AAAA,MACX,MAAM,MAAA,CAAO,IAAA;AAAA,MACb,OAAA,EAAS,OAAO,OAAA,IAAW;AAAA,KAC7B;AAAA,IACA,EAAE,IAAA,EAAM,MAAA,CAAO,IAAA,EAAK;AAAA,IACpB,OAAO,EAAE,IAAA,EAAK,KAA8E;AAC1F,MAAA,OAAO,MAAA,CAAO,IAAI,IAAI,CAAA;AAAA,IACxB;AAAA,GACF;AACF","file":"inngest.cjs","sourcesContent":["/**\n * Inngest adapter — wraps `run*` functions into `inngest.createFunction` calls,\n * passing `step` through as the StepRunner.\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: Inngest client type varies by consumer's event map\ntype InngestClient = any;\n\nexport interface InngestCronConfig<TResult> {\n  id: string;\n  name: string;\n  cron: string;\n  retries?: number;\n  run: (step: { run: <T>(id: string, fn: () => Promise<T>) => Promise<T> }) => Promise<TResult>;\n}\n\n/**\n * Wrap a pure `run*` function as an Inngest cron function.\n *\n * ```ts\n * const fn = withInngestCron(inngest, {\n *   id: \"flag-sync\",\n *   name: \"Sync flags\",\n *   cron: \"* /10 * * * *\",\n *   run: (step) => runFlagSync({ posthog: config, registry, namingRegex, step }),\n * });\n * ```\n */\nexport function withInngestCron<TResult>(\n  inngest: InngestClient,\n  config: InngestCronConfig<TResult>,\n) {\n  return inngest.createFunction(\n    {\n      id: config.id,\n      name: config.name,\n      retries: config.retries ?? 1,\n    },\n    { cron: config.cron },\n    async ({ step }: { step: { run: <T>(id: string, fn: () => Promise<T>) => Promise<T> } }) => {\n      return config.run(step);\n    },\n  );\n}\n"]}

package/dist/adapters/inngest.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Inngest adapter — wraps `run*` functions into `inngest.createFunction` calls,
+ * passing `step` through as the StepRunner.
+ */
+type InngestClient = any;
+interface InngestCronConfig<TResult> {
+    id: string;
+    name: string;
+    cron: string;
+    retries?: number;
+    run: (step: {
+        run: <T>(id: string, fn: () => Promise<T>) => Promise<T>;
+    }) => Promise<TResult>;
+}
+/**
+ * Wrap a pure `run*` function as an Inngest cron function.
+ *
+ * ```ts
+ * const fn = withInngestCron(inngest, {
+ *   id: "flag-sync",
+ *   name: "Sync flags",
+ *   cron: "* /10 * * * *",
+ *   run: (step) => runFlagSync({ posthog: config, registry, namingRegex, step }),
+ * });
+ * ```
+ */
+declare function withInngestCron<TResult>(inngest: InngestClient, config: InngestCronConfig<TResult>): any;
+
+export { type InngestCronConfig, withInngestCron };

package/dist/adapters/inngest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Inngest adapter — wraps `run*` functions into `inngest.createFunction` calls,
+ * passing `step` through as the StepRunner.
+ */
+type InngestClient = any;
+interface InngestCronConfig<TResult> {
+    id: string;
+    name: string;
+    cron: string;
+    retries?: number;
+    run: (step: {
+        run: <T>(id: string, fn: () => Promise<T>) => Promise<T>;
+    }) => Promise<TResult>;
+}
+/**
+ * Wrap a pure `run*` function as an Inngest cron function.
+ *
+ * ```ts
+ * const fn = withInngestCron(inngest, {
+ *   id: "flag-sync",
+ *   name: "Sync flags",
+ *   cron: "* /10 * * * *",
+ *   run: (step) => runFlagSync({ posthog: config, registry, namingRegex, step }),
+ * });
+ * ```
+ */
+declare function withInngestCron<TResult>(inngest: InngestClient, config: InngestCronConfig<TResult>): any;
+
+export { type InngestCronConfig, withInngestCron };

package/dist/adapters/inngest.js

@@ -0,0 +1,18 @@
+// src/adapters/inngest.ts
+function withInngestCron(inngest, config) {
+  return inngest.createFunction(
+    {
+      id: config.id,
+      name: config.name,
+      retries: config.retries ?? 1
+    },
+    { cron: config.cron },
+    async ({ step }) => {
+      return config.run(step);
+    }
+  );
+}
+
+export { withInngestCron };
+//# sourceMappingURL=inngest.js.map
+//# sourceMappingURL=inngest.js.map

package/dist/adapters/inngest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/inngest.ts"],"names":[],"mappings":";AA4BO,SAAS,eAAA,CACd,SACA,MAAA,EACA;AACA,EAAA,OAAO,OAAA,CAAQ,cAAA;AAAA,IACb;AAAA,MACE,IAAI,MAAA,CAAO,EAAA;AAAA,MACX,MAAM,MAAA,CAAO,IAAA;AAAA,MACb,OAAA,EAAS,OAAO,OAAA,IAAW;AAAA,KAC7B;AAAA,IACA,EAAE,IAAA,EAAM,MAAA,CAAO,IAAA,EAAK;AAAA,IACpB,OAAO,EAAE,IAAA,EAAK,KAA8E;AAC1F,MAAA,OAAO,MAAA,CAAO,IAAI,IAAI,CAAA;AAAA,IACxB;AAAA,GACF;AACF","file":"inngest.js","sourcesContent":["/**\n * Inngest adapter — wraps `run*` functions into `inngest.createFunction` calls,\n * passing `step` through as the StepRunner.\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: Inngest client type varies by consumer's event map\ntype InngestClient = any;\n\nexport interface InngestCronConfig<TResult> {\n  id: string;\n  name: string;\n  cron: string;\n  retries?: number;\n  run: (step: { run: <T>(id: string, fn: () => Promise<T>) => Promise<T> }) => Promise<TResult>;\n}\n\n/**\n * Wrap a pure `run*` function as an Inngest cron function.\n *\n * ```ts\n * const fn = withInngestCron(inngest, {\n *   id: \"flag-sync\",\n *   name: \"Sync flags\",\n *   cron: \"* /10 * * * *\",\n *   run: (step) => runFlagSync({ posthog: config, registry, namingRegex, step }),\n * });\n * ```\n */\nexport function withInngestCron<TResult>(\n  inngest: InngestClient,\n  config: InngestCronConfig<TResult>,\n) {\n  return inngest.createFunction(\n    {\n      id: config.id,\n      name: config.name,\n      retries: config.retries ?? 1,\n    },\n    { cron: config.cron },\n    async ({ step }: { step: { run: <T>(id: string, fn: () => Promise<T>) => Promise<T> } }) => {\n      return config.run(step);\n    },\n  );\n}\n"]}

package/dist/adapters/slack.cjs

@@ -0,0 +1,75 @@
+'use strict';
+
+// src/adapters/slack.ts
+function fmtPct(n) {
+  if (n == null) return "\u2014";
+  return `${(n * 100).toFixed(2)}%`;
+}
+async function postGuardianAlert(webhookUrl, opts) {
+  try {
+    if (!webhookUrl) return;
+    const color = opts.severity === "critical" ? "#DC2626" : "#EAB308";
+    const prefix = opts.enforced ? ":rotating_light: *FLAG AUTO-DISABLED*" : ":warning: *Regression detected (dry-run)*";
+    const mention = opts.enforced ? "<!channel> " : "";
+    const blocks = [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: `${mention}${prefix}
+*Flag*: \`${opts.flagKey}\` \u2014 ${opts.flagName}`
+        }
+      },
+      {
+        type: "section",
+        fields: [
+          { type: "mrkdwn", text: `*Reason*
+${opts.reason}` },
+          { type: "mrkdwn", text: `*Decision*
+${opts.decision}` },
+          {
+            type: "mrkdwn",
+            text: `*Error rate*
+Treatment: ${fmtPct(opts.metrics.treatmentErrorRate)}
+Control: ${fmtPct(opts.metrics.controlErrorRate)}`
+          },
+          {
+            type: "mrkdwn",
+            text: `*Publish success*
+Treatment: ${fmtPct(opts.metrics.treatmentPublishSuccessRate)}
+Control: ${fmtPct(opts.metrics.controlPublishSuccessRate)}`
+          }
+        ]
+      }
+    ];
+    const actionElements = [
+      {
+        type: "button",
+        text: { type: "plain_text", text: "Open in PostHog" },
+        url: opts.posthogFlagUrl
+      }
+    ];
+    if (opts.inngestRunUrl) {
+      actionElements.push({
+        type: "button",
+        text: { type: "plain_text", text: "Inngest run" },
+        url: opts.inngestRunUrl
+      });
+    }
+    blocks.push({ type: "actions", elements: actionElements });
+    const res = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ attachments: [{ color, blocks }] })
+    });
+    if (!res.ok) {
+      console.warn(`Slack webhook failed: ${res.status} ${await res.text().catch(() => "")}`);
+    }
+  } catch (err) {
+    console.warn("Slack alert dispatch failed:", err instanceof Error ? err.message : String(err));
+  }
+}
+
+exports.postGuardianAlert = postGuardianAlert;
+//# sourceMappingURL=slack.cjs.map
+//# sourceMappingURL=slack.cjs.map

package/dist/adapters/slack.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/slack.ts"],"names":[],"mappings":"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","file":"slack.cjs","sourcesContent":["/**\n * Slack Block Kit formatter for Guardian alerts.\n * Webhook URL is passed as a parameter — no secret resolution.\n */\n\nexport interface GuardianAlertOptions {\n  severity: \"warning\" | \"critical\";\n  flagKey: string;\n  flagName: string;\n  decision: \"regression_detected\" | \"auto_disabled\";\n  enforced: boolean;\n  reason: string;\n  metrics: {\n    treatmentErrorRate?: number | null;\n    controlErrorRate?: number | null;\n    treatmentPublishSuccessRate?: number | null;\n    controlPublishSuccessRate?: number | null;\n  };\n  posthogFlagUrl: string;\n  inngestRunUrl?: string;\n}\n\nfunction fmtPct(n: number | null | undefined): string {\n  if (n == null) return \"—\";\n  return `${(n * 100).toFixed(2)}%`;\n}\n\n/**\n * Post a Guardian alert to Slack via Incoming Webhook.\n * No-op if `webhookUrl` is falsy. Swallows errors.\n */\nexport async function postGuardianAlert(\n  webhookUrl: string | null | undefined,\n  opts: GuardianAlertOptions,\n): Promise<void> {\n  try {\n    if (!webhookUrl) return;\n\n    const color = opts.severity === \"critical\" ? \"#DC2626\" : \"#EAB308\";\n    const prefix = opts.enforced\n      ? \":rotating_light: *FLAG AUTO-DISABLED*\"\n      : \":warning: *Regression detected (dry-run)*\";\n    const mention = opts.enforced ? \"<!channel> \" : \"\";\n\n    const blocks: unknown[] = [\n      {\n        type: \"section\",\n        text: {\n          type: \"mrkdwn\",\n          text: `${mention}${prefix}\\n*Flag*: \\`${opts.flagKey}\\` — ${opts.flagName}`,\n        },\n      },\n      {\n        type: \"section\",\n        fields: [\n          { type: \"mrkdwn\", text: `*Reason*\\n${opts.reason}` },\n          { type: \"mrkdwn\", text: `*Decision*\\n${opts.decision}` },\n          {\n            type: \"mrkdwn\",\n            text: `*Error rate*\\nTreatment: ${fmtPct(opts.metrics.treatmentErrorRate)}\\nControl: ${fmtPct(opts.metrics.controlErrorRate)}`,\n          },\n          {\n            type: \"mrkdwn\",\n            text: `*Publish success*\\nTreatment: ${fmtPct(opts.metrics.treatmentPublishSuccessRate)}\\nControl: ${fmtPct(opts.metrics.controlPublishSuccessRate)}`,\n          },\n        ],\n      },\n    ];\n\n    const actionElements: unknown[] = [\n      {\n        type: \"button\",\n        text: { type: \"plain_text\", text: \"Open in PostHog\" },\n        url: opts.posthogFlagUrl,\n      },\n    ];\n    if (opts.inngestRunUrl) {\n      actionElements.push({\n        type: \"button\",\n        text: { type: \"plain_text\", text: \"Inngest run\" },\n        url: opts.inngestRunUrl,\n      });\n    }\n    blocks.push({ type: \"actions\", elements: actionElements });\n\n    const res = await fetch(webhookUrl, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ attachments: [{ color, blocks }] }),\n    });\n\n    if (!res.ok) {\n      console.warn(`Slack webhook failed: ${res.status} ${await res.text().catch(() => \"\")}`);\n    }\n  } catch (err) {\n    console.warn(\"Slack alert dispatch failed:\", err instanceof Error ? err.message : String(err));\n  }\n}\n"]}

package/dist/adapters/slack.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Slack Block Kit formatter for Guardian alerts.
+ * Webhook URL is passed as a parameter — no secret resolution.
+ */
+interface GuardianAlertOptions {
+    severity: "warning" | "critical";
+    flagKey: string;
+    flagName: string;
+    decision: "regression_detected" | "auto_disabled";
+    enforced: boolean;
+    reason: string;
+    metrics: {
+        treatmentErrorRate?: number | null;
+        controlErrorRate?: number | null;
+        treatmentPublishSuccessRate?: number | null;
+        controlPublishSuccessRate?: number | null;
+    };
+    posthogFlagUrl: string;
+    inngestRunUrl?: string;
+}
+/**
+ * Post a Guardian alert to Slack via Incoming Webhook.
+ * No-op if `webhookUrl` is falsy. Swallows errors.
+ */
+declare function postGuardianAlert(webhookUrl: string | null | undefined, opts: GuardianAlertOptions): Promise<void>;
+
+export { type GuardianAlertOptions, postGuardianAlert };

package/dist/adapters/slack.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Slack Block Kit formatter for Guardian alerts.
+ * Webhook URL is passed as a parameter — no secret resolution.
+ */
+interface GuardianAlertOptions {
+    severity: "warning" | "critical";
+    flagKey: string;
+    flagName: string;
+    decision: "regression_detected" | "auto_disabled";
+    enforced: boolean;
+    reason: string;
+    metrics: {
+        treatmentErrorRate?: number | null;
+        controlErrorRate?: number | null;
+        treatmentPublishSuccessRate?: number | null;
+        controlPublishSuccessRate?: number | null;
+    };
+    posthogFlagUrl: string;
+    inngestRunUrl?: string;
+}
+/**
+ * Post a Guardian alert to Slack via Incoming Webhook.
+ * No-op if `webhookUrl` is falsy. Swallows errors.
+ */
+declare function postGuardianAlert(webhookUrl: string | null | undefined, opts: GuardianAlertOptions): Promise<void>;
+
+export { type GuardianAlertOptions, postGuardianAlert };

package/dist/adapters/slack.js

@@ -0,0 +1,73 @@
+// src/adapters/slack.ts
+function fmtPct(n) {
+  if (n == null) return "\u2014";
+  return `${(n * 100).toFixed(2)}%`;
+}
+async function postGuardianAlert(webhookUrl, opts) {
+  try {
+    if (!webhookUrl) return;
+    const color = opts.severity === "critical" ? "#DC2626" : "#EAB308";
+    const prefix = opts.enforced ? ":rotating_light: *FLAG AUTO-DISABLED*" : ":warning: *Regression detected (dry-run)*";
+    const mention = opts.enforced ? "<!channel> " : "";
+    const blocks = [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: `${mention}${prefix}
+*Flag*: \`${opts.flagKey}\` \u2014 ${opts.flagName}`
+        }
+      },
+      {
+        type: "section",
+        fields: [
+          { type: "mrkdwn", text: `*Reason*
+${opts.reason}` },
+          { type: "mrkdwn", text: `*Decision*
+${opts.decision}` },
+          {
+            type: "mrkdwn",
+            text: `*Error rate*
+Treatment: ${fmtPct(opts.metrics.treatmentErrorRate)}
+Control: ${fmtPct(opts.metrics.controlErrorRate)}`
+          },
+          {
+            type: "mrkdwn",
+            text: `*Publish success*
+Treatment: ${fmtPct(opts.metrics.treatmentPublishSuccessRate)}
+Control: ${fmtPct(opts.metrics.controlPublishSuccessRate)}`
+          }
+        ]
+      }
+    ];
+    const actionElements = [
+      {
+        type: "button",
+        text: { type: "plain_text", text: "Open in PostHog" },
+        url: opts.posthogFlagUrl
+      }
+    ];
+    if (opts.inngestRunUrl) {
+      actionElements.push({
+        type: "button",
+        text: { type: "plain_text", text: "Inngest run" },
+        url: opts.inngestRunUrl
+      });
+    }
+    blocks.push({ type: "actions", elements: actionElements });
+    const res = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ attachments: [{ color, blocks }] })
+    });
+    if (!res.ok) {
+      console.warn(`Slack webhook failed: ${res.status} ${await res.text().catch(() => "")}`);
+    }
+  } catch (err) {
+    console.warn("Slack alert dispatch failed:", err instanceof Error ? err.message : String(err));
+  }
+}
+
+export { postGuardianAlert };
+//# sourceMappingURL=slack.js.map
+//# sourceMappingURL=slack.js.map

package/dist/adapters/slack.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/slack.ts"],"names":[],"mappings":"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","file":"slack.js","sourcesContent":["/**\n * Slack Block Kit formatter for Guardian alerts.\n * Webhook URL is passed as a parameter — no secret resolution.\n */\n\nexport interface GuardianAlertOptions {\n  severity: \"warning\" | \"critical\";\n  flagKey: string;\n  flagName: string;\n  decision: \"regression_detected\" | \"auto_disabled\";\n  enforced: boolean;\n  reason: string;\n  metrics: {\n    treatmentErrorRate?: number | null;\n    controlErrorRate?: number | null;\n    treatmentPublishSuccessRate?: number | null;\n    controlPublishSuccessRate?: number | null;\n  };\n  posthogFlagUrl: string;\n  inngestRunUrl?: string;\n}\n\nfunction fmtPct(n: number | null | undefined): string {\n  if (n == null) return \"—\";\n  return `${(n * 100).toFixed(2)}%`;\n}\n\n/**\n * Post a Guardian alert to Slack via Incoming Webhook.\n * No-op if `webhookUrl` is falsy. Swallows errors.\n */\nexport async function postGuardianAlert(\n  webhookUrl: string | null | undefined,\n  opts: GuardianAlertOptions,\n): Promise<void> {\n  try {\n    if (!webhookUrl) return;\n\n    const color = opts.severity === \"critical\" ? \"#DC2626\" : \"#EAB308\";\n    const prefix = opts.enforced\n      ? \":rotating_light: *FLAG AUTO-DISABLED*\"\n      : \":warning: *Regression detected (dry-run)*\";\n    const mention = opts.enforced ? \"<!channel> \" : \"\";\n\n    const blocks: unknown[] = [\n      {\n        type: \"section\",\n        text: {\n          type: \"mrkdwn\",\n          text: `${mention}${prefix}\\n*Flag*: \\`${opts.flagKey}\\` — ${opts.flagName}`,\n        },\n      },\n      {\n        type: \"section\",\n        fields: [\n          { type: \"mrkdwn\", text: `*Reason*\\n${opts.reason}` },\n          { type: \"mrkdwn\", text: `*Decision*\\n${opts.decision}` },\n          {\n            type: \"mrkdwn\",\n            text: `*Error rate*\\nTreatment: ${fmtPct(opts.metrics.treatmentErrorRate)}\\nControl: ${fmtPct(opts.metrics.controlErrorRate)}`,\n          },\n          {\n            type: \"mrkdwn\",\n            text: `*Publish success*\\nTreatment: ${fmtPct(opts.metrics.treatmentPublishSuccessRate)}\\nControl: ${fmtPct(opts.metrics.controlPublishSuccessRate)}`,\n          },\n        ],\n      },\n    ];\n\n    const actionElements: unknown[] = [\n      {\n        type: \"button\",\n        text: { type: \"plain_text\", text: \"Open in PostHog\" },\n        url: opts.posthogFlagUrl,\n      },\n    ];\n    if (opts.inngestRunUrl) {\n      actionElements.push({\n        type: \"button\",\n        text: { type: \"plain_text\", text: \"Inngest run\" },\n        url: opts.inngestRunUrl,\n      });\n    }\n    blocks.push({ type: \"actions\", elements: actionElements });\n\n    const res = await fetch(webhookUrl, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ attachments: [{ color, blocks }] }),\n    });\n\n    if (!res.ok) {\n      console.warn(`Slack webhook failed: ${res.status} ${await res.text().catch(() => \"\")}`);\n    }\n  } catch (err) {\n    console.warn(\"Slack alert dispatch failed:\", err instanceof Error ? err.message : String(err));\n  }\n}\n"]}