@hyperdrive.bot/cli 1.0.13 → 1.0.16

package/dist/utils/hook-flow.js

@@ -1,4 +1,55 @@
 import inquirer from 'inquirer';
+const SMART_ACTION_TYPES = ['git-create-branch', 'git-create-mr', 'git-delete-branch'];
+export const VALID_TRIGGER_EVENTS = [
+    'status_transition', 'issue_created', 'issue_assigned',
+    'field_changed', 'comment_added', 'label_changed',
+];
+export const ALL_ACTION_TYPES = [
+    'git-create-branch', 'git-create-mr', 'git-delete-branch',
+    'adhb-enrich', 'ci-trigger', 'slack-notify', 'webhook',
+    'stage-create', 'stage-delete', 'deploy',
+];
+export const VALID_LIFECYCLE_EVENTS = [
+    'stage.created', 'stage.provisioned', 'stage.domain.ready', 'stage.domain.failed',
+    'stage.destroying', 'stage.destroyed',
+    'deploy.created', 'deploy.ready', 'deploy.launched', 'deploy.completed', 'deploy.failed',
+    'launch.created', 'launch.deployed', 'launch.failed', 'launch.terminated',
+    'mission.started', 'mission.wave.completed', 'mission.completed', 'mission.failed',
+];
+export const LIFECYCLE_EVENT_GROUPS = [
+    new inquirer.Separator('── Stage Events ──'),
+    { name: 'stage.created — Stage record created', value: 'stage.created' },
+    { name: 'stage.provisioned — Stage infrastructure ready', value: 'stage.provisioned' },
+    { name: 'stage.domain.ready — Custom domain live', value: 'stage.domain.ready' },
+    { name: 'stage.domain.failed — Domain provisioning failed', value: 'stage.domain.failed' },
+    { name: 'stage.destroying — Stage teardown started', value: 'stage.destroying' },
+    { name: 'stage.destroyed — Stage fully deleted', value: 'stage.destroyed' },
+    new inquirer.Separator('── Deploy Events ──'),
+    { name: 'deploy.created — Deployment queued for build', value: 'deploy.created' },
+    { name: 'deploy.ready — Build artifacts available', value: 'deploy.ready' },
+    { name: 'deploy.launched — Live and serving traffic', value: 'deploy.launched' },
+    { name: 'deploy.completed — Full deploy cycle done', value: 'deploy.completed' },
+    { name: 'deploy.failed — Build or launch failed', value: 'deploy.failed' },
+    new inquirer.Separator('── Launch Events ──'),
+    { name: 'launch.created — Launch record created', value: 'launch.created' },
+    { name: 'launch.deployed — Launch live', value: 'launch.deployed' },
+    { name: 'launch.failed — Launch failed', value: 'launch.failed' },
+    { name: 'launch.terminated — Replaced by newer launch', value: 'launch.terminated' },
+    new inquirer.Separator('── Mission Events ──'),
+    { name: 'mission.started — Wave-based deploy started', value: 'mission.started' },
+    { name: 'mission.wave.completed — One dependency wave finished', value: 'mission.wave.completed' },
+    { name: 'mission.completed — All waves done', value: 'mission.completed' },
+    { name: 'mission.failed — Mission aborted', value: 'mission.failed' },
+];
+export const LIFECYCLE_CONDITION_FIELDS = {
+    deploy: ['stageName', 'projectSlug', 'isFirstDeploy', 'deploymentName'],
+    launch: ['stageName', 'projectSlug', 'region'],
+    mission: ['stageName', 'waveIndex', 'totalWaves'],
+    stage: ['stageName', 'accountId', 'isProduction', 'hasAutoLaunch'],
+};
+export function getActionCategory(type) {
+    return SMART_ACTION_TYPES.includes(type) ? 'smart' : 'flex';
+}
 /**
  * Prompt user to select a trigger status from available Jira statuses
  */
@@ -121,17 +172,295 @@ export async function promptActionConfig(actionType) {
                 config.ref = answers.ref;
             return config;
         }
+        case 'git-create-branch': {
+            const { branchPattern } = await inquirer.prompt([{
+                    default: '{issueKey}/{summary-slug}',
+                    message: 'Branch pattern (tokens: {issueKey}, {summary-slug}):',
+                    name: 'branchPattern',
+                    type: 'input',
+                }]);
+            return { branchPattern };
+        }
+        case 'git-create-mr': {
+            const answers = await inquirer.prompt([
+                {
+                    default: '',
+                    message: 'Target branch (leave empty for repo default):',
+                    name: 'targetBranch',
+                    type: 'input',
+                },
+                {
+                    default: true,
+                    message: 'Create as draft?',
+                    name: 'draft',
+                    type: 'confirm',
+                },
+                {
+                    default: '{issueKey}: {summary}',
+                    message: 'Title pattern (tokens: {issueKey}, {summary}):',
+                    name: 'titlePattern',
+                    type: 'input',
+                },
+            ]);
+            const config = { draft: answers.draft, titlePattern: answers.titlePattern };
+            if (answers.targetBranch)
+                config.targetBranch = answers.targetBranch;
+            return config;
+        }
+        case 'git-delete-branch':
+            return {};
+        case 'stage-create': {
+            const answers = await inquirer.prompt([
+                {
+                    default: '{{issueKey}}',
+                    message: 'Stage name template (tokens: {{issueKey}}, {{summary}}):',
+                    name: 'nameTemplate',
+                    type: 'input',
+                    validate: (input) => input.includes('{{issueKey}}') || input.includes('{issueKey}')
+                        ? true : 'Must contain {{issueKey}} or {issueKey}',
+                },
+                {
+                    message: 'AWS account ID (12-digit):',
+                    name: 'accountId',
+                    type: 'input',
+                    validate: (input) => /^\d{12}$/.test(input.trim()) ? true : 'Must be a 12-digit AWS account ID',
+                },
+                {
+                    default: 'sa-east-1',
+                    message: 'Regions (comma-separated):',
+                    name: 'regions',
+                    type: 'input',
+                    validate: (input) => input.trim() ? true : 'At least one region is required',
+                },
+            ]);
+            const config = {
+                accountId: answers.accountId.trim(),
+                nameTemplate: answers.nameTemplate,
+                regions: answers.regions.split(',').map((r) => r.trim()).filter(Boolean),
+            };
+            return config;
+        }
+        case 'stage-delete':
+            return { stageResolver: 'issueKey' };
+        case 'deploy': {
+            const answers = await inquirer.prompt([
+                {
+                    default: '',
+                    message: 'Project slug (leave empty for all modules on stage):',
+                    name: 'projectSlug',
+                    type: 'input',
+                },
+                {
+                    default: true,
+                    message: 'Launch deployment immediately?',
+                    name: 'launch',
+                    type: 'confirm',
+                },
+            ]);
+            const config = { stageResolver: 'issueKey' };
+            if (answers.projectSlug.trim())
+                config.projectSlug = answers.projectSlug.trim();
+            if (!answers.launch)
+                config.launch = false;
+            return config;
+        }
         default:
             throw new Error(`Unknown action type: ${actionType}`);
     }
 }
+/**
+ * Prompt user to select a trigger event type
+ */
+export async function promptTriggerEvent() {
+    const { triggerEvent } = await inquirer.prompt([{
+            choices: [
+                { name: 'Status transition', value: 'status_transition' },
+                { name: 'Issue created', value: 'issue_created' },
+                { name: 'Issue assigned', value: 'issue_assigned' },
+                { name: 'Field changed', value: 'field_changed' },
+                { name: 'Comment added', value: 'comment_added' },
+                { name: 'Label changed', value: 'label_changed' },
+            ],
+            message: 'Trigger event:',
+            name: 'triggerEvent',
+            type: 'list',
+        }]);
+    return triggerEvent;
+}
+/**
+ * Prompt for event-specific trigger conditions
+ */
+export async function promptTriggerConditions(event) {
+    const conditions = {};
+    switch (event) {
+        case 'status_transition': {
+            const { statusFrom } = await inquirer.prompt([{
+                    default: '',
+                    message: 'Status from (optional, leave blank for any):',
+                    name: 'statusFrom',
+                    type: 'input',
+                }]);
+            if (statusFrom && statusFrom.trim() !== '')
+                conditions.statusFrom = statusFrom.trim();
+            const { statusTo } = await inquirer.prompt([{
+                    default: '*',
+                    message: 'Status to (* for any):',
+                    name: 'statusTo',
+                    type: 'input',
+                }]);
+            if (statusTo && statusTo.trim() !== '*')
+                conditions.statusTo = statusTo.trim();
+            break;
+        }
+        case 'issue_created': {
+            const { issueType } = await inquirer.prompt([{
+                    default: '',
+                    message: 'Issue type filter (optional, e.g. Bug, Story):',
+                    name: 'issueType',
+                    type: 'input',
+                }]);
+            if (issueType)
+                conditions.issueType = issueType;
+            break;
+        }
+        case 'issue_assigned': {
+            const { assignee } = await inquirer.prompt([{
+                    default: '',
+                    message: 'Assignee filter (optional):',
+                    name: 'assignee',
+                    type: 'input',
+                }]);
+            if (assignee)
+                conditions.assignee = assignee;
+            break;
+        }
+        case 'field_changed': {
+            const { fieldName } = await inquirer.prompt([{
+                    message: 'Field name:',
+                    name: 'fieldName',
+                    type: 'input',
+                    validate: (input) => input.trim() ? true : 'Field name is required',
+                }]);
+            conditions.fieldName = fieldName;
+            const { fieldValue } = await inquirer.prompt([{
+                    default: '',
+                    message: 'Field value filter (optional):',
+                    name: 'fieldValue',
+                    type: 'input',
+                }]);
+            if (fieldValue)
+                conditions.fieldValue = fieldValue;
+            break;
+        }
+        case 'comment_added': {
+            const { pattern } = await inquirer.prompt([{
+                    default: '',
+                    message: 'Comment pattern (optional regex, e.g. @hyperdrive deploy):',
+                    name: 'pattern',
+                    type: 'input',
+                }]);
+            if (pattern)
+                conditions.pattern = pattern;
+            break;
+        }
+        case 'label_changed': {
+            const { label } = await inquirer.prompt([{
+                    message: 'Label:',
+                    name: 'label',
+                    type: 'input',
+                    validate: (input) => input.trim() ? true : 'Label is required',
+                }]);
+            conditions.label = label;
+            const { action } = await inquirer.prompt([{
+                    choices: [
+                        { name: 'added', value: 'added' },
+                        { name: 'removed', value: 'removed' },
+                    ],
+                    message: 'Label action:',
+                    name: 'action',
+                    type: 'list',
+                }]);
+            conditions.action = action;
+            break;
+        }
+    }
+    return conditions;
+}
+/**
+ * Prompt user to select an action type with category grouping
+ */
+export async function promptActionTypeV2() {
+    const { Separator } = inquirer;
+    const { actionType } = await inquirer.prompt([{
+            choices: [
+                new Separator('── Smart Actions ──'),
+                { name: 'Create branches (git-create-branch)', value: 'git-create-branch' },
+                { name: 'Create merge/pull requests (git-create-mr)', value: 'git-create-mr' },
+                { name: 'Delete branches (git-delete-branch)', value: 'git-delete-branch' },
+                new Separator('── Native Actions ──'),
+                { name: 'Create stage (stage-create)', value: 'stage-create' },
+                { name: 'Delete stage (stage-delete)', value: 'stage-delete' },
+                { name: 'Deploy (deploy)', value: 'deploy' },
+                new Separator('── Flex Hooks ──'),
+                { name: 'Slack notification (slack-notify)', value: 'slack-notify' },
+                { name: 'ADHB enrichment (adhb-enrich)', value: 'adhb-enrich' },
+                { name: 'Webhook (webhook)', value: 'webhook' },
+                { name: 'CI trigger (ci-trigger)', value: 'ci-trigger' },
+            ],
+            message: 'Action type:',
+            name: 'actionType',
+            type: 'list',
+        }]);
+    return {
+        category: getActionCategory(actionType),
+        type: actionType,
+    };
+}
+/**
+ * Prompt for execution order
+ */
+export async function promptOrder() {
+    const { order } = await inquirer.prompt([{
+            default: '',
+            message: 'Execution order (lower runs first, leave empty for default):',
+            name: 'order',
+            type: 'input',
+            validate: (input) => {
+                if (!input.trim())
+                    return true;
+                const num = Number(input);
+                if (Number.isInteger(num) && num > 0)
+                    return true;
+                return 'Must be a positive integer or empty';
+            },
+        }]);
+    return order ? Number(order) : undefined;
+}
+/**
+ * Format a hook label for display in selection prompts
+ */
+function formatHookLabel(h) {
+    // V2 shape: has trigger/action objects
+    if ('trigger' in h && h.trigger) {
+        const event = h.trigger.event ?? '';
+        const conditions = h.trigger.conditions;
+        const condStr = conditions && Object.keys(conditions).length > 0
+            ? Object.entries(conditions).map(([k, v]) => `${k}: ${v}`).join(', ')
+            : '*';
+        const actionType = h.action?.type ?? '';
+        return `[${event}] ${condStr} → ${actionType} (${h.enabled ? 'enabled' : 'disabled'})`;
+    }
+    // V1 shape: has triggerStatus/actionType
+    const v1 = h;
+    return `[${v1.triggerStatus}] ${v1.actionType} (${v1.enabled ? 'enabled' : 'disabled'})`;
+}
 /**
  * Prompt user to select a hook from a list
  */
 export async function promptSelectHook(hooks) {
     const { selectedHook } = await inquirer.prompt([{
             choices: hooks.map(h => ({
-                name: `[${h.triggerStatus}] ${h.actionType} (${h.enabled ? 'enabled' : 'disabled'})`,
+                name: formatHookLabel(h),
                 value: h,
             })),
             message: 'Select a hook:',
@@ -146,9 +475,115 @@ export async function promptSelectHook(hooks) {
 export async function promptConfirmDelete(hook) {
     const { confirmed } = await inquirer.prompt([{
             default: false,
-            message: `Delete hook [${hook.triggerStatus}] ${hook.actionType}?`,
+            message: `Delete hook ${formatHookLabel(hook)}?`,
             name: 'confirmed',
             type: 'confirm',
         }]);
     return confirmed;
 }
+/**
+ * Prompt user to choose between lifecycle event trigger and cron trigger
+ */
+export async function promptTriggerType() {
+    const { triggerType } = await inquirer.prompt([{
+            choices: [
+                { name: 'Lifecycle event — fire on deploy, stage, launch, or mission events', value: 'lifecycle' },
+                { name: 'Cron schedule — fire on a recurring time-based schedule', value: 'cron' },
+            ],
+            message: 'Select trigger type:',
+            name: 'triggerType',
+            type: 'list',
+        }]);
+    return triggerType;
+}
+/**
+ * Prompt user for a cron expression or rate expression
+ */
+export async function promptCronExpression() {
+    const { expression } = await inquirer.prompt([{
+            message: 'Cron expression or rate (e.g. "0 3 * * ? *", "rate(1 hour)"):',
+            name: 'expression',
+            type: 'input',
+            validate: (input) => {
+                if (!input.trim())
+                    return 'Expression is required';
+                return true;
+            },
+        }]);
+    return expression.trim();
+}
+/**
+ * Prompt user for an IANA timezone
+ */
+export async function promptCronTimezone() {
+    const { timezone } = await inquirer.prompt([{
+            default: 'UTC',
+            message: 'Timezone (IANA, e.g. "America/Sao_Paulo", "UTC"):',
+            name: 'timezone',
+            type: 'input',
+            validate: (input) => {
+                if (!input.trim())
+                    return 'Timezone is required';
+                return true;
+            },
+        }]);
+    return timezone.trim();
+}
+/**
+ * Prompt user for the flexible time window (optional)
+ */
+export async function promptFlexibleWindow() {
+    const { flexWindow } = await inquirer.prompt([{
+            default: '',
+            message: 'Flexible time window in minutes (default: 15, leave empty to use default):',
+            name: 'flexWindow',
+            type: 'input',
+            validate: (input) => {
+                if (!input.trim())
+                    return true;
+                const num = Number(input);
+                if (Number.isInteger(num) && num >= 0 && num <= 1440)
+                    return true;
+                return 'Must be an integer between 0 and 1440, or empty for default';
+            },
+        }]);
+    return flexWindow ? Number(flexWindow) : undefined;
+}
+/**
+ * Prompt user to select a lifecycle event for tenant hooks
+ */
+export async function promptLifecycleEvent() {
+    const { event } = await inquirer.prompt([{
+            choices: LIFECYCLE_EVENT_GROUPS,
+            message: 'Select lifecycle event:',
+            name: 'event',
+            type: 'list',
+        }]);
+    return event;
+}
+/**
+ * Prompt for lifecycle event-specific conditions
+ *
+ * Extracts group prefix from the event (e.g., deploy.completed → deploy)
+ * and prompts for each field in LIFECYCLE_CONDITION_FIELDS[group].
+ * Returns only non-empty values.
+ */
+export async function promptLifecycleConditions(event) {
+    const group = event.split('.')[0];
+    const fields = LIFECYCLE_CONDITION_FIELDS[group];
+    if (!fields || fields.length === 0)
+        return {};
+    const conditions = {};
+    for (const field of fields) {
+        const answer = await inquirer.prompt([{
+                default: '',
+                message: `${field} (leave empty to skip):`,
+                name: field,
+                type: 'input',
+            }]);
+        if (answer[field]?.trim()) {
+            conditions[field] = answer[field].trim();
+        }
+    }
+    return conditions;
+}

package/dist/utils/hook-normalize.d.ts

@@ -0,0 +1,6 @@
+import type { TrackerHookResponseV2 } from '../services/hyperdrive-sigv4.js';
+/**
+ * Normalize a hook response to V2 shape.
+ * Handles both V1 (triggerStatus/actionType/actionConfig) and V2 (trigger/action) formats.
+ */
+export declare function normalizeHookToV2(hook: Record<string, any>): TrackerHookResponseV2;

package/dist/utils/hook-normalize.js

@@ -0,0 +1,33 @@
+import { getActionCategory } from './hook-flow.js';
+/**
+ * Normalize a hook response to V2 shape.
+ * Handles both V1 (triggerStatus/actionType/actionConfig) and V2 (trigger/action) formats.
+ */
+export function normalizeHookToV2(hook) {
+    // Already V2 — has trigger and action objects
+    if (hook.trigger && hook.action) {
+        return hook;
+    }
+    // V1 → V2 conversion
+    const triggerStatus = hook.triggerStatus ?? '*';
+    const actionType = hook.actionType ?? '';
+    const actionConfig = hook.actionConfig ?? {};
+    return {
+        action: {
+            category: getActionCategory(actionType) ?? 'flex',
+            config: actionConfig,
+            type: actionType,
+        },
+        createdAt: hook.createdAt,
+        enabled: hook.enabled,
+        hookId: hook.hookId,
+        order: hook.order,
+        trackerProjectId: hook.trackerProjectId,
+        trigger: {
+            conditions: triggerStatus === '*' ? {} : { statusTo: triggerStatus },
+            event: 'status_transition',
+            source: 'jira',
+        },
+        updatedAt: hook.updatedAt ?? hook.createdAt,
+    };
+}

package/dist/utils/lifecycle-poller.d.ts

@@ -0,0 +1,32 @@
+export interface PollerOptions<T> {
+    /** Function to call on each poll cycle */
+    pollFn: () => Promise<T>;
+    /** Extract the status string from the polled entity */
+    getStatus: (entity: T) => string;
+    /** Set of status values that mean the operation finished (success or failure) */
+    terminalStates: Set<string>;
+    /** Set of status values that indicate success */
+    successStates: Set<string>;
+    /** Optional: extract a phase string (for clone multi-phase display) */
+    getPhase?: (entity: T) => string | undefined;
+    /** Optional: extract an error message on failure */
+    getErrorMessage?: (entity: T) => string | undefined;
+    /** Label shown in spinner (e.g. "Backing up", "Restoring") */
+    operationLabel: string;
+    /** Poll interval in ms (default 10_000) */
+    intervalMs?: number;
+    /** Max timeout in ms (default 30 minutes) */
+    timeoutMs?: number;
+}
+export interface PollerResult<T> {
+    entity: T;
+    success: boolean;
+    timedOut: boolean;
+}
+/**
+ * Generic lifecycle polling utility for async Hyperdrive operations.
+ *
+ * Polls a status endpoint at a fixed interval, displaying an ora spinner
+ * with phase and elapsed time until a terminal state is reached or timeout.
+ */
+export declare function pollLifecycle<T>(options: PollerOptions<T>, isJson: boolean): Promise<PollerResult<T>>;

package/dist/utils/lifecycle-poller.js

@@ -0,0 +1,72 @@
+import chalk from 'chalk';
+import ora from 'ora';
+const CLONE_PHASE_LABELS = {
+    'completed': 'Completed',
+    'credential-rotation': 'Rotating credentials',
+    'failed': 'Failed',
+    'registering': 'Registering new service',
+    'restoring': 'Restoring from snapshot',
+    'snapshot-creating': 'Creating snapshot',
+    'snapshot-sharing': 'Sharing snapshot cross-account',
+};
+function formatElapsed(startTime) {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+}
+/**
+ * Generic lifecycle polling utility for async Hyperdrive operations.
+ *
+ * Polls a status endpoint at a fixed interval, displaying an ora spinner
+ * with phase and elapsed time until a terminal state is reached or timeout.
+ */
+export async function pollLifecycle(options, isJson) {
+    const { pollFn, getStatus, terminalStates, successStates, getPhase, getErrorMessage, operationLabel, intervalMs = 10_000, timeoutMs = 30 * 60 * 1000, } = options;
+    const spinner = isJson ? null : ora(`${operationLabel}...`).start();
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        await new Promise(resolve => setTimeout(resolve, intervalMs));
+        try {
+            const entity = await pollFn();
+            const status = getStatus(entity);
+            const elapsed = formatElapsed(startTime);
+            if (terminalStates.has(status)) {
+                const isSuccess = successStates.has(status);
+                if (isSuccess) {
+                    spinner?.succeed(chalk.green(`${operationLabel} completed (${elapsed})`));
+                }
+                else {
+                    spinner?.fail(chalk.red(`${operationLabel} failed (${elapsed})`));
+                    const errorMsg = getErrorMessage?.(entity);
+                    if (errorMsg && !isJson) {
+                        // Print error on a new line under the spinner
+                        process.stderr.write(chalk.red(`  Reason: ${errorMsg}\n`));
+                    }
+                }
+                return { entity, success: isSuccess, timedOut: false };
+            }
+            // Still in progress — update spinner with phase + elapsed
+            const phase = getPhase?.(entity);
+            const phaseLabel = phase ? (CLONE_PHASE_LABELS[phase] || phase) : status;
+            spinner?.start(`${operationLabel}... ${chalk.gray(`(${phaseLabel} — ${elapsed})`)}`);
+        }
+        catch {
+            // Transient error — keep polling
+            const elapsed = formatElapsed(startTime);
+            spinner?.start(`${operationLabel}... ${chalk.gray(`(checking — ${elapsed})`)}`);
+        }
+    }
+    // Timeout
+    const elapsed = formatElapsed(startTime);
+    spinner?.warn(chalk.yellow(`${operationLabel} timed out (${elapsed})`));
+    // Return a best-effort result — poll one last time
+    try {
+        const entity = await pollFn();
+        return { entity, success: false, timedOut: true };
+    }
+    catch {
+        // Can't even fetch final state — return a synthetic timeout result
+        return { entity: undefined, success: false, timedOut: true };
+    }
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Retry utility with exponential backoff for transient upload failures.
+ *
+ * Classifies errors as retryable (network errors, 429, 5xx) vs permanent
+ * (4xx except 429) and only retries transient failures.
+ */
+export interface RetryConfig {
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+}
+export interface RetryResult<T> {
+    /** Number of attempts made (1 = no retries needed) */
+    attempts: number;
+    /** The result if successful */
+    result: T;
+}
+/**
+ * Check whether an error is transient and should be retried.
+ *
+ * Retryable:
+ * - Network errors: ECONNRESET, ETIMEDOUT, EPIPE, ENOTFOUND, etc.
+ * - HTTP 429 (rate limited)
+ * - HTTP 5xx (server errors)
+ *
+ * Non-retryable:
+ * - HTTP 4xx except 429 (client errors — bad URL, expired signature, etc.)
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Execute an async function with exponential backoff retry.
+ *
+ * @param fn - Async function to execute. Should throw or return a failed Response on failure.
+ * @param config - Retry configuration
+ * @returns The successful result and attempt count
+ * @throws The last error after all retries are exhausted
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<RetryResult<T>>;
+/** Awaitable sleep helper (exported for testing) */
+export declare function sleep(ms: number): Promise<void>;