@quonfig/cli 0.0.46 → 0.0.48

package/dist/migrate/quonfig-target/values.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared verb: provider variation value → typed Quonfig `{type, value}`.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Quonfig values
+ * are a discriminated union on `type`; this verb infers the type from the raw
+ * JSON a provider hands us and the flag's declared value type.
+ */
+/** A Quonfig value type — mirrors `ValueTypeSchema` in app-quonfig's config-schemas.ts. */
+export type QuonfigValueType = 'bool' | 'double' | 'int' | 'json' | 'string' | 'string_list';
+/** A typed Quonfig value object as it appears in stored config JSON. */
+export interface QuonfigValue {
+    type: QuonfigValueType;
+    value: unknown;
+}
+/**
+ * Infer the Quonfig value type for a single raw value.
+ *  - boolean → bool
+ *  - integer number → int; non-integer number → double
+ *  - string → string
+ *  - object / array → json
+ */
+export declare function inferValueType(raw: unknown): QuonfigValueType;
+/**
+ * Infer the value type for a whole flag from its variation values.
+ *
+ * LaunchDarkly boolean flags are unambiguously `bool`. For multivariate flags
+ * the variations are homogeneous in practice; we widen `int` → `double` if any
+ * variation is fractional so a flag with `[0, 1, 2.5]` lands on `double`
+ * rather than silently truncating.
+ */
+export declare function inferFlagValueType(kind: string, variationValues: unknown[]): QuonfigValueType;
+/**
+ * Coerce a raw provider value into a typed Quonfig value object under the
+ * flag's declared value type. The declared type wins — a `double` flag whose
+ * variation happens to be `2` still serializes as `{type: 'double', value: 2}`
+ * so the stored config is internally consistent.
+ */
+export declare function toQuonfigValue(raw: unknown, valueType: QuonfigValueType): QuonfigValue;

package/dist/migrate/quonfig-target/values.js

@@ -0,0 +1,77 @@
+/**
+ * Shared verb: provider variation value → typed Quonfig `{type, value}`.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Quonfig values
+ * are a discriminated union on `type`; this verb infers the type from the raw
+ * JSON a provider hands us and the flag's declared value type.
+ */
+/**
+ * Infer the Quonfig value type for a single raw value.
+ *  - boolean → bool
+ *  - integer number → int; non-integer number → double
+ *  - string → string
+ *  - object / array → json
+ */
+export function inferValueType(raw) {
+    if (typeof raw === 'boolean')
+        return 'bool';
+    if (typeof raw === 'number')
+        return Number.isInteger(raw) ? 'int' : 'double';
+    if (typeof raw === 'string')
+        return 'string';
+    // null, objects, and arrays all serialize as Quonfig `json`.
+    return 'json';
+}
+/**
+ * Infer the value type for a whole flag from its variation values.
+ *
+ * LaunchDarkly boolean flags are unambiguously `bool`. For multivariate flags
+ * the variations are homogeneous in practice; we widen `int` → `double` if any
+ * variation is fractional so a flag with `[0, 1, 2.5]` lands on `double`
+ * rather than silently truncating.
+ */
+export function inferFlagValueType(kind, variationValues) {
+    if (kind === 'boolean')
+        return 'bool';
+    if (variationValues.length === 0)
+        return 'string';
+    const types = variationValues.map((v) => inferValueType(v));
+    if (types.every((t) => t === 'bool'))
+        return 'bool';
+    if (types.every((t) => t === 'int' || t === 'double')) {
+        return types.includes('double') ? 'double' : 'int';
+    }
+    if (types.every((t) => t === 'string'))
+        return 'string';
+    // Mixed or object/array variations → json (json can hold any of them).
+    return 'json';
+}
+/**
+ * Coerce a raw provider value into a typed Quonfig value object under the
+ * flag's declared value type. The declared type wins — a `double` flag whose
+ * variation happens to be `2` still serializes as `{type: 'double', value: 2}`
+ * so the stored config is internally consistent.
+ */
+export function toQuonfigValue(raw, valueType) {
+    switch (valueType) {
+        case 'bool': {
+            return { type: 'bool', value: Boolean(raw) };
+        }
+        case 'double':
+        case 'int': {
+            return { type: valueType, value: typeof raw === 'number' ? raw : Number(raw) };
+        }
+        case 'json': {
+            return { type: 'json', value: raw };
+        }
+        case 'string_list': {
+            return { type: 'string_list', value: Array.isArray(raw) ? raw.map(String) : [] };
+        }
+        case 'string': {
+            return { type: 'string', value: typeof raw === 'string' ? raw : String(raw) };
+        }
+        default: {
+            return { type: 'string', value: String(raw) };
+        }
+    }
+}

package/dist/migrate/source-api-key.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Decision D8 (project/plans/migrator-launch-darkly.md §9.1): the `qfg migrate`
+ * command's API-key flag is generalized from the launch-specific `--api-key` /
+ * `LAUNCH_API_KEY` into a provider-agnostic `--source-api-key` /
+ * `QUONFIG_MIGRATE_API_KEY`, with a per-provider env fallback. `--api-key` /
+ * `LAUNCH_API_KEY` stay as deprecated aliases for the `launch` source.
+ *
+ * Precedence (highest first):
+ *   1. `--source-api-key` flag   (oclif also fills it from QUONFIG_MIGRATE_API_KEY)
+ *   2. `--api-key` flag          (oclif also fills it from LAUNCH_API_KEY; deprecated)
+ *   3. per-provider env var      (LAUNCHDARKLY_API_KEY, FLAGSMITH_API_KEY, ...)
+ */
+/**
+ * Per-provider env-var fallback, lowest precedence. Keyed by `--from` value so
+ * every supported source has an obvious, source-named env var. `launch`'s entry
+ * is redundant with the `--api-key` flag's own `env: LAUNCH_API_KEY` binding,
+ * but is kept so the map is a complete record of every provider's env var.
+ */
+export declare const PROVIDER_API_KEY_ENV: Record<string, string>;
+export interface SourceApiKeyInput {
+    /** `--api-key` flag value (oclif also fills this from LAUNCH_API_KEY). Deprecated alias. */
+    apiKeyFlag?: string;
+    /** Process env, injectable for tests. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** `--from` value — selects the per-provider env-var fallback. */
+    from: string;
+    /** `--source-api-key` flag value (oclif also fills this from QUONFIG_MIGRATE_API_KEY). */
+    sourceApiKeyFlag?: string;
+}
+/** Resolve the source API key from flags + env, or `undefined` if none is configured. */
+export declare function resolveSourceApiKey(input: SourceApiKeyInput): string | undefined;
+/** One-line guidance for the "no key configured" error, naming every accepted input. */
+export declare function missingSourceApiKeyMessage(from: string): string;

package/dist/migrate/source-api-key.js

@@ -0,0 +1,43 @@
+/**
+ * Decision D8 (project/plans/migrator-launch-darkly.md §9.1): the `qfg migrate`
+ * command's API-key flag is generalized from the launch-specific `--api-key` /
+ * `LAUNCH_API_KEY` into a provider-agnostic `--source-api-key` /
+ * `QUONFIG_MIGRATE_API_KEY`, with a per-provider env fallback. `--api-key` /
+ * `LAUNCH_API_KEY` stay as deprecated aliases for the `launch` source.
+ *
+ * Precedence (highest first):
+ *   1. `--source-api-key` flag   (oclif also fills it from QUONFIG_MIGRATE_API_KEY)
+ *   2. `--api-key` flag          (oclif also fills it from LAUNCH_API_KEY; deprecated)
+ *   3. per-provider env var      (LAUNCHDARKLY_API_KEY, FLAGSMITH_API_KEY, ...)
+ */
+/**
+ * Per-provider env-var fallback, lowest precedence. Keyed by `--from` value so
+ * every supported source has an obvious, source-named env var. `launch`'s entry
+ * is redundant with the `--api-key` flag's own `env: LAUNCH_API_KEY` binding,
+ * but is kept so the map is a complete record of every provider's env var.
+ */
+export const PROVIDER_API_KEY_ENV = {
+    flagsmith: 'FLAGSMITH_API_KEY',
+    launch: 'LAUNCH_API_KEY',
+    launchdarkly: 'LAUNCHDARKLY_API_KEY',
+};
+/** Resolve the source API key from flags + env, or `undefined` if none is configured. */
+export function resolveSourceApiKey(input) {
+    if (input.sourceApiKeyFlag)
+        return input.sourceApiKeyFlag;
+    if (input.apiKeyFlag)
+        return input.apiKeyFlag;
+    const env = input.env ?? process.env;
+    const providerEnv = PROVIDER_API_KEY_ENV[input.from];
+    if (providerEnv && env[providerEnv])
+        return env[providerEnv];
+    return undefined;
+}
+/** One-line guidance for the "no key configured" error, naming every accepted input. */
+export function missingSourceApiKeyMessage(from) {
+    const providerEnv = PROVIDER_API_KEY_ENV[from];
+    const providerHint = providerEnv ? ` For --from ${from} you can also set ${providerEnv}.` : '';
+    return ('--source-api-key is required (or set QUONFIG_MIGRATE_API_KEY).' +
+        providerHint +
+        ' The legacy --api-key / LAUNCH_API_KEY flag still works for --from launch.');
+}

package/dist/migrate/source.d.ts

@@ -1,3 +1,4 @@
+import type { ConversionNote } from './quonfig-target/report.js';
 export interface LegacyChange {
     changedAt?: number;
     key?: string;
@@ -88,6 +89,15 @@ export interface MigrationSource {
      * synthesized entries) and the caller should fall back to the migrator identity.
      */
     getCommitMeta?(change: LegacyChange): CommitMeta | null;
+    /**
+     * Optional post-translate accumulator. Returns the structured conversion notes
+     * collected during translate() — re-bucketed rollouts, dropped prerequisites,
+     * lossy individual-target conversions, etc. (the LaunchDarkly converter set).
+     * The write paths thread these into MIGRATION_REPORT.md's "Users will be
+     * re-bucketed" + "Conversion notes" sections. Null or empty when nothing
+     * notable happened during conversion.
+     */
+    getConversionNotes?(): ConversionNote[] | null;
     /**
      * Optional post-translate accumulator. Returns any override sections that were
      * dropped during translate() calls because the env.id was not present in the

package/dist/migrate/sources/launchdarkly/api.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LaunchDarkly REST API client — Phase-1 config snapshot.
+ *
+ * LaunchDarkly has no bulk "export everything" endpoint, so the fetcher
+ * stitches per-resource calls: environments, context-kinds, flags (full
+ * per-env targeting via `?summary=0&env=`), and segments (per environment).
+ *
+ * Auth is a raw API token in the `Authorization` header — no `Bearer` prefix.
+ * Rate limiting is a per-account rolling 10-second window with an unpublished
+ * limit, so we program against the headers: back off on 429 using
+ * `X-Ratelimit-Reset` (epoch-ms), pre-throttle on `X-Ratelimit-Global-Remaining`.
+ */
+import type { LDFlag, LDSegment, LDSnapshot } from './types.js';
+export declare function setLaunchDarklyBaseUrl(url: string): void;
+export declare function selectLaunchDarklyBaseUrl(): string;
+export declare function applyLaunchDarklyBaseUrl(): void;
+export declare function __setSleepForTests(fn: (ms: number) => Promise<void>): void;
+export declare function __resetSleepForTests(): void;
+export declare class LaunchDarklyApiError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, url: string, body: string);
+}
+/**
+ * Single GET with header auth, 429 backoff against `X-Ratelimit-Reset`, and a
+ * pre-throttle when `X-Ratelimit-Global-Remaining` runs low. Non-429 errors
+ * throw immediately — only rate limiting is retried.
+ *
+ * Exported so the Phase-2 audit-log walker (`audit.ts`) reuses the exact same
+ * rate-limit handling — `/auditlog` is account-wide and the slowest endpoint,
+ * so it must not bypass the shared 429 backoff.
+ */
+export declare function apiFetch(path: string, apiKey: string): Promise<unknown>;
+/** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
+export declare function fetchProjectEnvironments(apiKey: string, projectKey: string): Promise<string[]>;
+export declare function fetchContextKinds(apiKey: string, projectKey: string): Promise<string[]>;
+/**
+ * Full per-environment flag targeting. `?summary=0` plus repeated `?env=`
+ * returns rules, clauses, targets, fallthrough, offVariation, prerequisites
+ * and rollouts for every named environment in one response — there is no
+ * "all environments" wildcard, so env keys are templated in explicitly.
+ *
+ * `opts.archived` flips the list to *only* archived flags. LaunchDarkly's flag
+ * list endpoint hides archived flags by default and has no "both" mode, so a
+ * full picture is two calls. The migration runtime does not want archived flags
+ * (`fetchSnapshot` omits this), but the fixture-corpus exporter needs them so
+ * the `state-archived` edge case is in the canonical corpus.
+ */
+export declare function fetchFlags(apiKey: string, projectKey: string, envKeys: string[], opts?: {
+    archived?: boolean;
+}): Promise<LDFlag[]>;
+/** Segments are a per-environment resource — caller loops env keys and de-dupes. */
+export declare function fetchSegmentsForEnv(apiKey: string, projectKey: string, envKey: string): Promise<LDSegment[]>;
+/**
+ * Stitches the whole Phase-1 snapshot: environments → context-kinds → flags
+ * (one call, all envs) → segments (per env, de-duplicated by key). This is the
+ * ~60-call "fast, lossless for current state" path; it always re-fetches
+ * everything (decision D2 — we do not trust the LD audit cursor for deltas).
+ */
+export declare function fetchSnapshot(apiKey: string, projectKey: string): Promise<LDSnapshot>;

package/dist/migrate/sources/launchdarkly/api.js

@@ -0,0 +1,195 @@
+/**
+ * LaunchDarkly REST API client — Phase-1 config snapshot.
+ *
+ * LaunchDarkly has no bulk "export everything" endpoint, so the fetcher
+ * stitches per-resource calls: environments, context-kinds, flags (full
+ * per-env targeting via `?summary=0&env=`), and segments (per environment).
+ *
+ * Auth is a raw API token in the `Authorization` header — no `Bearer` prefix.
+ * Rate limiting is a per-account rolling 10-second window with an unpublished
+ * limit, so we program against the headers: back off on 429 using
+ * `X-Ratelimit-Reset` (epoch-ms), pre-throttle on `X-Ratelimit-Global-Remaining`.
+ */
+const PROD_BASE_URL = 'https://app.launchdarkly.com/api/v2';
+const PAGE_LIMIT = 20;
+/** Below this many remaining requests we pre-throttle to avoid a 429 storm. */
+const RATE_LIMIT_FLOOR = 5;
+/** Fallback wait when a 429 carries no usable reset header. */
+const DEFAULT_BACKOFF_MS = 2000;
+/** Hard cap on retries for a single request before we give up. */
+const MAX_RETRIES = 6;
+let baseUrl = PROD_BASE_URL;
+export function setLaunchDarklyBaseUrl(url) {
+    baseUrl = url;
+}
+export function selectLaunchDarklyBaseUrl() {
+    return process.env.LAUNCHDARKLY_API_URL ?? PROD_BASE_URL;
+}
+export function applyLaunchDarklyBaseUrl() {
+    baseUrl = selectLaunchDarklyBaseUrl();
+}
+/** Real timer-backed sleep — swapped out in tests so MSW runs don't actually wait. */
+function timerSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Test seam: a no-op sleep is swapped in so MSW tests don't actually wait. */
+let sleepImpl = timerSleep;
+export function __setSleepForTests(fn) {
+    sleepImpl = fn;
+}
+export function __resetSleepForTests() {
+    sleepImpl = timerSleep;
+}
+export class LaunchDarklyApiError extends Error {
+    status;
+    constructor(status, statusText, url, body) {
+        super(`LaunchDarkly API request failed: ${status} ${statusText} — ${url}\n${body}`);
+        this.name = 'LaunchDarklyApiError';
+        this.status = status;
+    }
+}
+/** Wait derived from a 429 response's rate-limit headers. */
+function backoffMsFromHeaders(headers) {
+    const reset = headers.get('X-Ratelimit-Reset');
+    if (reset) {
+        const resetMs = Number(reset);
+        if (Number.isFinite(resetMs)) {
+            // Header is an absolute epoch-ms timestamp; wait until then (clamped ≥ 0).
+            return Math.max(0, resetMs - Date.now());
+        }
+    }
+    return DEFAULT_BACKOFF_MS;
+}
+/**
+ * Single GET with header auth, 429 backoff against `X-Ratelimit-Reset`, and a
+ * pre-throttle when `X-Ratelimit-Global-Remaining` runs low. Non-429 errors
+ * throw immediately — only rate limiting is retried.
+ *
+ * Exported so the Phase-2 audit-log walker (`audit.ts`) reuses the exact same
+ * rate-limit handling — `/auditlog` is account-wide and the slowest endpoint,
+ * so it must not bypass the shared 429 backoff.
+ */
+export async function apiFetch(path, apiKey) {
+    const url = path.startsWith('http') ? path : `${baseUrl}${path}`;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await fetch(url, {
+            headers: {
+                Accept: 'application/json',
+                Authorization: apiKey,
+            },
+        });
+        if (res.status === 429) {
+            if (attempt === MAX_RETRIES) {
+                // eslint-disable-next-line no-await-in-loop
+                const body = await res.text().catch(() => '(no body)');
+                throw new LaunchDarklyApiError(429, res.statusText, url, body);
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await sleepImpl(backoffMsFromHeaders(res.headers));
+            continue;
+        }
+        if (!res.ok) {
+            // eslint-disable-next-line no-await-in-loop
+            const body = await res.text().catch(() => '(no body)');
+            throw new LaunchDarklyApiError(res.status, res.statusText, url, body);
+        }
+        // Pre-throttle: if the account-wide budget is nearly spent, pause briefly
+        // before the next call rather than walking straight into a 429.
+        const remaining = res.headers.get('X-Ratelimit-Global-Remaining');
+        if (remaining !== null && Number(remaining) <= RATE_LIMIT_FLOOR) {
+            // eslint-disable-next-line no-await-in-loop
+            await sleepImpl(backoffMsFromHeaders(res.headers));
+        }
+        return res.json();
+    }
+    // Unreachable — the loop either returns or throws.
+    throw new LaunchDarklyApiError(429, 'Too Many Requests', url, 'retries exhausted');
+}
+/**
+ * Walks an offset-paginated collection endpoint. LaunchDarkly returns a
+ * `_links.next.href` while more pages remain; we stop when it is absent or a
+ * short page is returned.
+ */
+async function paginate(firstPath, apiKey) {
+    const collected = [];
+    let path = firstPath;
+    const seen = new Set();
+    while (path && !seen.has(path)) {
+        seen.add(path);
+        // eslint-disable-next-line no-await-in-loop
+        const page = (await apiFetch(path, apiKey));
+        if (Array.isArray(page.items))
+            collected.push(...page.items);
+        const next = page._links?.next?.href;
+        // `next.href` is server-relative ("/api/v2/..."); strip the shared prefix
+        // so it composes with our configurable base URL.
+        path = next ? next.replace(/^\/api\/v2/, '') : undefined;
+        if (page.items.length < PAGE_LIMIT)
+            break;
+    }
+    return collected;
+}
+/** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
+export async function fetchProjectEnvironments(apiKey, projectKey) {
+    const items = await paginate(`/projects/${encodeURIComponent(projectKey)}/environments?limit=${PAGE_LIMIT}`, apiKey);
+    return items.map((e) => e.key);
+}
+export async function fetchContextKinds(apiKey, projectKey) {
+    const data = (await apiFetch(`/projects/${encodeURIComponent(projectKey)}/context-kinds`, apiKey));
+    return Array.isArray(data.items) ? data.items.map((k) => k.key) : [];
+}
+/**
+ * Full per-environment flag targeting. `?summary=0` plus repeated `?env=`
+ * returns rules, clauses, targets, fallthrough, offVariation, prerequisites
+ * and rollouts for every named environment in one response — there is no
+ * "all environments" wildcard, so env keys are templated in explicitly.
+ *
+ * `opts.archived` flips the list to *only* archived flags. LaunchDarkly's flag
+ * list endpoint hides archived flags by default and has no "both" mode, so a
+ * full picture is two calls. The migration runtime does not want archived flags
+ * (`fetchSnapshot` omits this), but the fixture-corpus exporter needs them so
+ * the `state-archived` edge case is in the canonical corpus.
+ */
+export async function fetchFlags(apiKey, projectKey, envKeys, opts = {}) {
+    const params = new URLSearchParams({ limit: String(PAGE_LIMIT), summary: '0' });
+    for (const env of envKeys)
+        params.append('env', env);
+    if (opts.archived)
+        params.set('archived', 'true');
+    return paginate(`/flags/${encodeURIComponent(projectKey)}?${params}`, apiKey);
+}
+/** Segments are a per-environment resource — caller loops env keys and de-dupes. */
+export async function fetchSegmentsForEnv(apiKey, projectKey, envKey) {
+    return paginate(`/segments/${encodeURIComponent(projectKey)}/${encodeURIComponent(envKey)}?limit=${PAGE_LIMIT}`, apiKey);
+}
+/**
+ * Stitches the whole Phase-1 snapshot: environments → context-kinds → flags
+ * (one call, all envs) → segments (per env, de-duplicated by key). This is the
+ * ~60-call "fast, lossless for current state" path; it always re-fetches
+ * everything (decision D2 — we do not trust the LD audit cursor for deltas).
+ */
+export async function fetchSnapshot(apiKey, projectKey) {
+    const environments = await fetchProjectEnvironments(apiKey, projectKey);
+    const contextKinds = await fetchContextKinds(apiKey, projectKey);
+    const flags = await fetchFlags(apiKey, projectKey, environments);
+    const segmentsByKey = new Map();
+    for (const envKey of environments) {
+        // eslint-disable-next-line no-await-in-loop
+        const segs = await fetchSegmentsForEnv(apiKey, projectKey, envKey);
+        for (const seg of segs) {
+            // First env to define a segment wins; LD segments are per-env but the
+            // key is stable, and v1 imports one shell per key (plan §5.4).
+            if (!segmentsByKey.has(seg.key))
+                segmentsByKey.set(seg.key, seg);
+        }
+    }
+    return {
+        contextKinds,
+        environments,
+        flags,
+        segments: [...segmentsByKey.values()],
+    };
+}

package/dist/migrate/sources/launchdarkly/audit.d.ts

@@ -0,0 +1,161 @@
+/**
+ * LaunchDarkly REST API client — Phase-2 history backfill (`--full-summary`).
+ *
+ * Phase 1 (`api.ts`) is a fast current-state snapshot. Phase 2 is the slow,
+ * resumable audit-log walk that reifies every historical flag change into its
+ * own git commit with the original author, date and message.
+ *
+ * Hard constraints, straight from `project/plans/migrator-launch-darkly.md`
+ * §4.1 / §4.1.1 — all surfaced to the user, none worked around silently:
+ *
+ * - The audit log is a *forward event stream*, not a versioned object store.
+ *   There is no point-in-time endpoint; each `/auditlog/{id}` entry carries the
+ *   full `currentVersion` of the resource as of that change, which is exactly
+ *   what we need to reify a commit.
+ * - `/auditlog` caps `limit` at 20 and is account-wide. A large account is tens
+ *   of thousands of events → 10k–50k+ calls → hours. The walk MUST be
+ *   checkpointed/resumable — `walkAuditLog` cursors on `before` and emits an
+ *   `onCheckpoint` after every page so a crashed run resumes where it stopped.
+ * - Retention is plan-gated: LD Developer plans retain only the last 30 days.
+ *   `probeRetentionHorizon` is the up-front pre-flight — it tells the user the
+ *   real horizon BEFORE the slow phase starts, so nobody waits hours expecting
+ *   two years and silently gets thirty days.
+ * - `delta` is null for semantic-patch updates, so we rely on `currentVersion`,
+ *   never `delta`.
+ */
+import type { CommitMeta, LegacyChange } from '../../source.js';
+import type { LDFlag } from './types.js';
+/** The human actor on an audit-log entry. Absent for token / integration actors. */
+export interface LDAuditActor {
+    _id?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+}
+/** A row from the `/auditlog` listing — enough to page and to hydrate. */
+export interface LDAuditLogListEntry {
+    _id: string;
+    /** Epoch ms — the change timestamp and the `before` pagination cursor. */
+    date: number;
+    name?: string;
+    titleVerb?: string;
+}
+/**
+ * A fully hydrated `/auditlog/{id}` entry. `currentVersion` is the full
+ * resource representation as of this change — for a flag entry it is an
+ * `LDFlag`, which `translate()` consumes directly.
+ */
+export interface LDAuditLogEntry extends LDAuditLogListEntry {
+    app?: {
+        name?: string;
+    };
+    comment?: string;
+    currentVersion?: LDFlag;
+    /** Null for semantic-patch updates — never relied on; see file header. */
+    delta?: unknown;
+    description?: string;
+    member?: LDAuditActor;
+    previousVersion?: unknown;
+    shortDescription?: string;
+    target?: {
+        name?: string;
+        resources?: string[];
+    };
+    token?: {
+        name?: string;
+    };
+}
+interface LDAuditLogPage {
+    _links?: {
+        next?: {
+            href: string;
+        };
+    };
+    items: LDAuditLogListEntry[];
+}
+/** Result of the up-front retention pre-flight (plan §4.1.1). */
+export interface RetentionHorizon {
+    /**
+     * True when no audit entry older than 30 days was found — the account is
+     * almost certainly on an LD Developer plan and pre-window history is gone.
+     */
+    developerPlanLikely: boolean;
+    /** Human-readable summary for the CLI to print before the slow phase. */
+    label: string;
+    /**
+     * Epoch ms of the oldest entry the bracket probe could reach, or null when
+     * nothing older than 30 days is retained.
+     */
+    oldestReachableMs: null | number;
+}
+export interface WalkAuditLogOptions {
+    /** Floor — stop once the stream reaches entries at or before this epoch ms. */
+    after?: number;
+    /**
+     * Resumable checkpoint hook — invoked after every listing page with the
+     * `before` cursor to restart from. Persist this so a crashed multi-hour walk
+     * resumes instead of restarting.
+     */
+    onCheckpoint?: (before: number) => Promise<void> | void;
+    /** LD resource spec, e.g. `proj/<key>:env/*:flag/*`. See `buildFlagAuditSpec`. */
+    spec?: string;
+    /** Resume cursor — start strictly older than this epoch ms instead of newest. */
+    startBefore?: number;
+}
+/** The LD audit-log resource spec that scopes the walk to every flag in a project. */
+export declare function buildFlagAuditSpec(projectKey: string): string;
+/** One page of the `/auditlog` listing. `limit` is pinned to the API's max of 20. */
+export declare function fetchAuditLogPage(apiKey: string, opts?: {
+    after?: number;
+    before?: number;
+    spec?: string;
+}): Promise<LDAuditLogPage>;
+/** Hydrate one listing row into a full entry — this is the call that carries `currentVersion`. */
+export declare function fetchAuditLogEntry(apiKey: string, id: string): Promise<LDAuditLogEntry>;
+/**
+ * Walk the audit log newest-to-oldest, hydrating every listing row. Pages on
+ * the `before` cursor (the oldest `date` seen so far) so the walk is resumable:
+ * pass `startBefore` to resume, and persist each `onCheckpoint(before)` value.
+ *
+ * Terminates on the first empty page; an `after` floor stops it early. A
+ * non-decreasing cursor (a misbehaving API or a same-ms tie at a page edge)
+ * also terminates the walk rather than looping forever.
+ */
+export declare function walkAuditLog(apiKey: string, opts?: WalkAuditLogOptions): AsyncIterable<LDAuditLogEntry>;
+/**
+ * Up-front retention pre-flight (plan §4.1.1). Brackets the account's retention
+ * window with one cheap `limit=1` probe per boundary instead of walking the
+ * whole log. An empty 30-day probe means the account retains ≤ 30 days — almost
+ * certainly an LD Developer plan, and pre-window history is permanently gone.
+ */
+export declare function probeRetentionHorizon(apiKey: string, opts?: {
+    now?: number;
+    spec?: string;
+}): Promise<RetentionHorizon>;
+/**
+ * The `LegacyChange.raw` payload for a Phase-2 audit change. Extends the
+ * Phase-1 `{kind: 'flag', data}` shape `translate()` already understands with
+ * the originating `auditEntry`, so the source's `getCommitMeta` can reify the
+ * original author / date / message without a second lookup.
+ */
+export interface LaunchDarklyFlagAuditRaw {
+    auditEntry: LDAuditLogEntry;
+    data: LDFlag;
+    kind: 'flag';
+}
+/**
+ * Map a hydrated audit entry to a `LegacyChange`. The `currentVersion` flag
+ * snapshot is carried as the `{kind: 'flag', data}` payload `translate()`
+ * already understands, so Phase-2 history reuses the Phase-1 converter
+ * unchanged. Returns null for entries that carry no flag `currentVersion`
+ * (deleted resources, non-flag audit rows) — those are skipped, not crashed.
+ */
+export declare function auditEntryToLegacyChange(entry: LDAuditLogEntry): LegacyChange | null;
+/**
+ * Reify an audit entry's original author, timestamp and description into commit
+ * metadata for `--full-summary` (plan §7). Returns null when the entry has no
+ * human member (token / integration actors) so the caller falls back to the
+ * migrator identity rather than inventing an author.
+ */
+export declare function getCommitMetaForAuditEntry(entry: LDAuditLogEntry): CommitMeta | null;
+export {};