posthog-flag-toolkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Minimal subset of PostHog's FeatureFlag schema — only the fields we use.
+ *
+ * IMPORTANT: PostHog's FeatureFlag schema has NO separate `description` field.
+ * The `name` field IS the description, kept under that name for backwards
+ * compatibility. From the OpenAPI spec:
+ *
+ *   name: { type: string, description: "contains the description for the flag
+ *     (field name `name` is kept for backwards-compatibility)" }
+ */
+interface PostHogClientConfig {
+    apiKey: string;
+    projectId: string;
+    baseUrl?: string;
+}
+interface PostHogFlagGroup {
+    variant?: string | null;
+    properties?: unknown[];
+    rollout_percentage?: number | null;
+}
+interface PostHogFlagFilters {
+    groups?: PostHogFlagGroup[];
+}
+interface PostHogFlag {
+    id: number;
+    key: string;
+    /** Description of the flag — PostHog calls this `name` for legacy reasons. */
+    name: string | null;
+    active: boolean;
+    deleted: boolean;
+    tags: string[] | null;
+    filters: PostHogFlagFilters | null;
+    created_at: string;
+    updated_at?: string;
+}
+interface PostHogFlagList {
+    results: PostHogFlag[];
+    next: string | null;
+}
+interface PostHogExperiment {
+    id: number;
+    name: string;
+    feature_flag_key: string;
+    start_date: string | null;
+    end_date: string | null;
+    archived: boolean;
+}
+interface PostHogExperimentList {
+    results: PostHogExperiment[];
+}
+interface ActivityEntry {
+    created_at: string;
+    activity: string;
+    detail: {
+        changes?: Array<{
+            field: string;
+            after: unknown;
+            before: unknown;
+        }>;
+    } | null;
+}
+interface ActivityList {
+    results: ActivityEntry[];
+}
+
+interface CohortMetrics {
+    eventCount: number;
+    uniqueUsers: number;
+    errorRate: number | null;
+    publishSuccessRate: number | null;
+}
+interface EvaluationMetrics {
+    treatment: CohortMetrics;
+    control: CohortMetrics;
+}
+/**
+ * Single HogQL round-trip for per-cohort metrics. Partitions by the
+ * `$feature/<flag_key>` property the PostHog SDKs attach to every event.
+ *
+ * Flag key is validated against a strict regex before interpolation.
+ */
+declare function queryCohortMetrics(params: {
+    config: PostHogClientConfig;
+    flagKey: string;
+    windowStart: Date;
+    windowEnd: Date;
+    /** Custom publish event name. Defaults to `post/publish.completed`. */
+    publishEventName?: string;
+    /** Custom publish success property. Defaults to `properties.success`. */
+    publishSuccessProp?: string;
+}): Promise<EvaluationMetrics>;
+
+interface GuardianThresholds {
+    windowMinutes: number;
+    minSampleSize: number;
+    minUniqueUsers: number;
+    errorRateRatioThreshold: number;
+    publishSuccessDropThreshold: number;
+    cooldownMinutes: number;
+}
+declare const DEFAULT_THRESHOLDS: GuardianThresholds;
+declare function mergeThresholds(overrides?: Partial<GuardianThresholds>): GuardianThresholds;
+
+type DecisionKind = "insufficient_data" | "no_regression" | "regression_detected" | "auto_disabled";
+interface Decision {
+    kind: DecisionKind;
+    reason: string;
+}
+declare function fmtPct(n: number | null | undefined): string;
+declare function detectRegression(metrics: EvaluationMetrics, thresholds: GuardianThresholds): Decision;
+declare function meetsSampleFloor(metrics: EvaluationMetrics, thresholds: GuardianThresholds): boolean;
+
+interface Logger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+declare const consoleLogger: Logger;
+
+/**
+ * Abstraction that decouples orchestration functions from Inngest.
+ * Inngest's `step.run()` returns `Promise<Jsonify<T>>` which isn't assignable
+ * to `Promise<T>` — so we use `unknown` as the return type to stay compatible.
+ */
+interface StepRunner {
+    run<T>(id: string, fn: () => Promise<T>): Promise<any>;
+}
+/**
+ * Simple implementation that just calls `fn()` directly — no durability,
+ * suitable for BullMQ, Vercel cron, plain Node, or testing.
+ */
+declare class SimpleStepRunner implements StepRunner {
+    run<T>(_id: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Auto-rollback cron logic. Scans flags tagged `guardian` and compares
+ * treatment vs control cohorts. Pure function with StepRunner + callbacks.
+ */
+
+interface GuardianEvaluation {
+    flag: PostHogFlag;
+    metrics: EvaluationMetrics;
+    decision: DecisionKind;
+    reason: string;
+    enforced: boolean;
+}
+interface GuardianCallbacks {
+    onRegression?: (result: GuardianEvaluation) => void | Promise<void>;
+    onEvaluated?: (result: GuardianEvaluation) => void | Promise<void>;
+    onEnforced?: (flag: PostHogFlag, result: GuardianEvaluation) => void | Promise<void>;
+}
+interface FlagOutcome {
+    flag_key: string;
+    decision: DecisionKind;
+    reason: string;
+}
+interface GuardianResult {
+    flags_evaluated: number;
+    regressions_detected: number;
+    auto_disabled: number;
+    outcomes: FlagOutcome[];
+}
+interface GuardianOptions {
+    posthog: PostHogClientConfig;
+    thresholds?: Partial<GuardianThresholds>;
+    /** Custom HogQL config for publish event detection */
+    publishEventName?: string;
+    publishSuccessProp?: string;
+    step?: StepRunner;
+    dryRun?: boolean;
+    callbacks?: GuardianCallbacks;
+    logger?: Logger;
+}
+declare function posthogFlagUrl(projectId: string, flagId: number, baseUrl?: string): string;
+declare function runFlagGuardian(options: GuardianOptions): Promise<GuardianResult>;
+
+/** Fetch every flag in the project, paginating through PostHog's cursor pagination. */
+declare function fetchAllFlags(config: PostHogClientConfig): Promise<PostHogFlag[]>;
+/**
+ * Note: PostHog's `?tags=` filter is substring-based — callers should re-filter
+ * for exact tag matches via `hasTag()` to be safe.
+ */
+declare function fetchFlagsByTag(config: PostHogClientConfig, tag: string): Promise<PostHogFlag[]>;
+declare function fetchAllExperiments(config: PostHogClientConfig): Promise<PostHogExperiment[]>;
+/**
+ * Find when a specific tag was added to a flag by scanning PostHog's activity log.
+ */
+declare function findTagAddedAt(config: PostHogClientConfig, flagId: number, tag: string): Promise<Date | null>;
+interface FlagPatch {
+    name?: string;
+    tags?: string[];
+    active?: boolean;
+    filters?: PostHogFlagFilters;
+}
+/** Pass only the fields you want to change. */
+declare function patchFlag(config: PostHogClientConfig, flagId: number, patch: FlagPatch, options?: {
+    dryRun?: boolean;
+}): Promise<void>;
+declare function patchFlagTags(config: PostHogClientConfig, flagId: number, tags: string[], options?: {
+    dryRun?: boolean;
+}): Promise<void>;
+interface CreateFlagBody {
+    key: string;
+    /** Goes into PostHog's `name` field (which is actually the description). */
+    name: string;
+    tags: string[];
+    active?: boolean;
+    filters?: PostHogFlagFilters;
+}
+/**
+ * Defaults to `active: false, rollout: 0%` if filters is omitted.
+ */
+declare function createFlag(config: PostHogClientConfig, body: CreateFlagBody, options?: {
+    dryRun?: boolean;
+}): Promise<PostHogFlag | null>;
+/**
+ * Active, not deleted, and every release condition at 100% rollout. Flags with
+ * zero groups are considered NOT released.
+ */
+declare function isFullyReleased(flag: PostHogFlag): boolean;
+declare function hasTag(flag: PostHogFlag, tag: string): boolean;
+declare function withTagAdded(flag: PostHogFlag, tag: string): string[];
+
+type Lifecycle = "release" | "experiment" | "ops" | "tier";
+interface FlagDefinition<K extends string = string> {
+    key: K;
+    description: string;
+    /** @Slack handle or email — shown in admin digests + orphan reports. */
+    owner: string;
+    /** Navigation tags applied additively to PostHog (e.g. "studio", "instagram"). */
+    tags?: readonly string[];
+    /** Opt into guardian monitoring on creation (adds the `guardian` tag). */
+    guardian?: boolean;
+    sunsetTarget?: string;
+}
+
+interface RegistryConfig<A extends string> {
+    areas: readonly A[];
+    extraTags?: readonly string[];
+}
+type FeatureFlagKey<A extends string> = `${Lifecycle}_${A}_${string}`;
+interface Registry<A extends string> {
+    /**
+     * Define the full registry object. The `satisfies` constraint is applied
+     * by the consumer at the call site for compile-time validation.
+     */
+    NAMING_REGEX: RegExp;
+    /** Typed accessor for consumer code. */
+    flag<K extends string>(name: K, registry: Record<K, FlagDefinition>): string;
+    /** Get the lifecycle prefix from a flag key. */
+    getLifecycle: (key: string) => Lifecycle;
+    /** Get the area segment from a flag key. */
+    getArea: (key: string) => A;
+}
+/**
+ * Factory that produces a registry bound to an app's specific areas.
+ *
+ * Consumer usage:
+ * ```ts
+ * const { NAMING_REGEX, flag, getLifecycle, getArea } = createRegistry({
+ *   areas: ["studio", "ai", "publish"] as const,
+ * });
+ * ```
+ */
+declare function createRegistry<A extends string>(config: RegistryConfig<A>): Registry<A>;
+
+declare function buildNamingRegex(areas: readonly string[]): RegExp;
+declare function getLifecycle(key: string): Lifecycle;
+declare function getArea<A extends string>(key: string): A;
+
+/**
+ * Detects feature flags / experiments hitting 100% rollout and treats that
+ * as a "feature release." Pure function with StepRunner + callbacks.
+ *
+ * Idempotency, timestamps, and stale-flag dedupe all live in PostHog tags
+ * (no DB tables): `released-detected-v1` marks first detection,
+ * `stale-notified-YYYY-MM` is month-scoped so flags re-nag once per month.
+ */
+
+interface NewRelease {
+    key: string;
+    name: string;
+    type: "flag" | "experiment";
+}
+interface StaleFlagInfo {
+    key: string;
+    name: string;
+    daysSinceRelease: number;
+}
+interface OrphanFlag {
+    key: string;
+}
+interface NamingViolation {
+    key: string;
+}
+interface DigestPayload {
+    newFlagReleases: NewRelease[];
+    newExperimentReleases: NewRelease[];
+    staleFlags: StaleFlagInfo[];
+    orphans: OrphanFlag[];
+    namingViolations: NamingViolation[];
+}
+interface ReleaseTrackerCallbacks {
+    onNewRelease?: (flag: PostHogFlag, type: "flag" | "experiment") => void | Promise<void>;
+    onStale?: (flag: PostHogFlag, daysSinceRelease: number) => void | Promise<void>;
+    onOrphan?: (flag: PostHogFlag) => void | Promise<void>;
+    onNamingViolation?: (flag: PostHogFlag) => void | Promise<void>;
+    onDigestReady?: (digest: DigestPayload) => void | Promise<void>;
+}
+interface ReleaseTrackerResult {
+    flags_checked: number;
+    experiments_checked: number;
+    new_flag_releases: number;
+    new_experiment_releases: number;
+    stale_flags_notified: number;
+    orphans: number;
+    naming_violations: number;
+}
+interface ReleaseTrackerOptions {
+    posthog: PostHogClientConfig;
+    registry: Record<string, FlagDefinition>;
+    namingRegex: RegExp;
+    namingExemptTag?: string;
+    staleThresholdDays?: number;
+    step?: StepRunner;
+    dryRun?: boolean;
+    callbacks?: ReleaseTrackerCallbacks;
+    logger?: Logger;
+}
+declare function runReleaseTracker(options: ReleaseTrackerOptions): Promise<ReleaseTrackerResult>;
+
+/**
+ * One-way sync from a local registry to PostHog. Pure function with
+ * StepRunner + callbacks — no framework dependency.
+ *
+ * Safety principles:
+ *   - Never deletes flags from PostHog (orphans = human review only)
+ *   - Never touches active / rollout / conditions (PostHog owns state)
+ *   - Tag reconciliation is additive only (union, never subtract)
+ *   - New flags created in safe state (active: false, 0% rollout)
+ *   - Idempotent — second run is a no-op if registry == PostHog
+ */
+
+interface FlagSyncCallbacks {
+    onCreate?: (def: FlagDefinition) => void | Promise<void>;
+    onOrphan?: (flag: PostHogFlag) => void | Promise<void>;
+    onNamingViolation?: (flag: PostHogFlag) => void | Promise<void>;
+    onReconcile?: (flag: PostHogFlag, patch: Record<string, unknown>) => void | Promise<void>;
+}
+interface FlagSyncResult {
+    registry_size: number;
+    posthog_size: number;
+    created: number;
+    reconciled: number;
+    orphans: number;
+    naming_violations: number;
+}
+interface FlagSyncOptions {
+    posthog: PostHogClientConfig;
+    registry: Record<string, FlagDefinition>;
+    namingRegex: RegExp;
+    namingExemptTag?: string;
+    step?: StepRunner;
+    dryRun?: boolean;
+    callbacks?: FlagSyncCallbacks;
+    logger?: Logger;
+}
+declare function runFlagSync(options: FlagSyncOptions): Promise<FlagSyncResult>;
+
+export { type ActivityEntry, type ActivityList, type CohortMetrics, type CreateFlagBody, DEFAULT_THRESHOLDS, type Decision, type DecisionKind, type DigestPayload, type EvaluationMetrics, type FeatureFlagKey, type FlagDefinition, type FlagOutcome, type FlagPatch, type FlagSyncCallbacks, type FlagSyncOptions, type FlagSyncResult, type GuardianCallbacks, type GuardianEvaluation, type GuardianOptions, type GuardianResult, type GuardianThresholds, type Lifecycle, type Logger, type NamingViolation, type NewRelease, type OrphanFlag, type PostHogClientConfig, type PostHogExperiment, type PostHogExperimentList, type PostHogFlag, type PostHogFlagFilters, type PostHogFlagGroup, type PostHogFlagList, type Registry, type RegistryConfig, type ReleaseTrackerCallbacks, type ReleaseTrackerOptions, type ReleaseTrackerResult, SimpleStepRunner, type StaleFlagInfo, type StepRunner, buildNamingRegex, consoleLogger, createFlag, createRegistry, detectRegression, fetchAllExperiments, fetchAllFlags, fetchFlagsByTag, findTagAddedAt, fmtPct, getArea, getLifecycle, hasTag, isFullyReleased, meetsSampleFloor, mergeThresholds, patchFlag, patchFlagTags, posthogFlagUrl, queryCohortMetrics, runFlagGuardian, runFlagSync, runReleaseTracker, withTagAdded };