@wopr-network/platform-core 1.17.0 → 1.19.0

package/dist/api/routes/admin-audit-helper.d.ts

@@ -1,7 +1,7 @@
 import type { AuditEntry } from "../../admin/audit-log.js";
 /** Minimal interface for admin audit logging in route factories. */
 export interface AdminAuditLogger {
-    log(entry: AuditEntry): void | Promise<unknown>;
+    log(entry: AuditEntry): undefined | Promise<unknown>;
 }
 /** Safely log an admin audit entry — never throws. */
 export declare function safeAuditLog(logger: (() => AdminAuditLogger) | undefined, entry: AuditEntry): void;

package/dist/billing/crypto/evm/__tests__/config.test.js

@@ -19,6 +19,16 @@ describe("getTokenConfig", () => {
         expect(cfg.contractAddress).toMatch(/^0x/);
         expect(cfg.contractAddress).toBe("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
     });
+    it("returns USDT on Base", () => {
+        const cfg = getTokenConfig("USDT", "base");
+        expect(cfg.decimals).toBe(6);
+        expect(cfg.contractAddress).toBe("0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2");
+    });
+    it("returns DAI on Base", () => {
+        const cfg = getTokenConfig("DAI", "base");
+        expect(cfg.decimals).toBe(18);
+        expect(cfg.contractAddress).toBe("0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb");
+    });
     it("throws on unsupported token/chain combo", () => {
         // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
         expect(() => getTokenConfig("USDC", "ethereum")).toThrow("Unsupported token");

package/dist/billing/crypto/evm/config.js

@@ -14,6 +14,18 @@ const TOKENS = {
         contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         decimals: 6,
     },
+    "USDT:base": {
+        token: "USDT",
+        chain: "base",
+        contractAddress: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
+        decimals: 6,
+    },
+    "DAI:base": {
+        token: "DAI",
+        chain: "base",
+        contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+        decimals: 18,
+    },
 };
 export function getChainConfig(chain) {
     const cfg = CHAINS[chain];

package/dist/billing/crypto/evm/types.d.ts

@@ -1,7 +1,7 @@
 /** Supported EVM chains. */
 export type EvmChain = "base";
 /** Supported stablecoin tokens. */
-export type StablecoinToken = "USDC";
+export type StablecoinToken = "USDC" | "USDT" | "DAI";
 /** Chain configuration. */
 export interface ChainConfig {
     readonly chain: EvmChain;

package/dist/fleet/__tests__/rollout-strategy.test.d.ts

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

package/dist/fleet/__tests__/rollout-strategy.test.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { createRolloutStrategy, ImmediateStrategy, RollingWaveStrategy, SingleBotStrategy, } from "../rollout-strategy.js";
+function makeBots(count) {
+    return Array.from({ length: count }, (_, i) => ({
+        id: randomUUID(),
+        tenantId: "tenant-1",
+        name: `bot-${i}`,
+        description: "",
+        image: "ghcr.io/wopr-network/test:latest",
+        env: {},
+        restartPolicy: "unless-stopped",
+        releaseChannel: "stable",
+        updatePolicy: "manual",
+    }));
+}
+describe("RollingWaveStrategy", () => {
+    it("returns batchPercent of remaining bots", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 25 });
+        const bots = makeBots(10);
+        const batch = s.nextBatch(bots);
+        // 25% of 10 = 2.5, ceil = 3
+        expect(batch).toHaveLength(3);
+        expect(batch).toEqual(bots.slice(0, 3));
+    });
+    it("returns minimum 1 bot even with low percentage", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 1 });
+        const bots = makeBots(2);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+    });
+    it("returns empty array for empty remaining", () => {
+        const s = new RollingWaveStrategy();
+        expect(s.nextBatch([])).toHaveLength(0);
+    });
+    it("handles 1 bot remaining", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 50 });
+        const bots = makeBots(1);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+    });
+    it("handles batchPercent > 100", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 200 });
+        const bots = makeBots(5);
+        // 200% of 5 = 10, ceil = 10, but slice(0,10) on 5 items = 5
+        expect(s.nextBatch(bots)).toHaveLength(5);
+    });
+    it("returns correct pause duration", () => {
+        expect(new RollingWaveStrategy().pauseDuration()).toBe(60_000);
+        expect(new RollingWaveStrategy({ pauseMs: 30_000 }).pauseDuration()).toBe(30_000);
+    });
+    it("retries on failure until maxRetries", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 2 });
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 1)).toBe("retry");
+    });
+    it("skips after maxRetries when under maxFailures", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 3 });
+        const err = new Error("fail");
+        // attempt >= maxRetries (2), first total failure
+        expect(s.onBotFailure("b1", err, 2)).toBe("skip");
+    });
+    it("aborts when total failures reach maxFailures", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 2 });
+        const err = new Error("fail");
+        // exhaust retries for bot1 → skip (totalFailures=1)
+        expect(s.onBotFailure("b1", err, 2)).toBe("skip");
+        // exhaust retries for bot2 → abort (totalFailures=2 >= maxFailures=2)
+        expect(s.onBotFailure("b2", err, 2)).toBe("abort");
+    });
+    it("has maxRetries of 2", () => {
+        expect(new RollingWaveStrategy().maxRetries()).toBe(2);
+    });
+    it("has healthCheckTimeout of 120_000", () => {
+        expect(new RollingWaveStrategy().healthCheckTimeout()).toBe(120_000);
+    });
+});
+describe("SingleBotStrategy", () => {
+    it("returns exactly 1 bot", () => {
+        const s = new SingleBotStrategy();
+        const bots = makeBots(10);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+        expect(s.nextBatch(bots)[0]).toBe(bots[0]);
+    });
+    it("returns empty for empty remaining", () => {
+        expect(new SingleBotStrategy().nextBatch([])).toHaveLength(0);
+    });
+    it("has pauseDuration of 0", () => {
+        expect(new SingleBotStrategy().pauseDuration()).toBe(0);
+    });
+    it("always retries on failure", () => {
+        const s = new SingleBotStrategy();
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 1)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 2)).toBe("retry");
+        // After maxRetries (3), aborts instead of retrying forever
+        expect(s.onBotFailure("b1", err, 99)).toBe("abort");
+    });
+    it("has maxRetries of 3", () => {
+        expect(new SingleBotStrategy().maxRetries()).toBe(3);
+    });
+    it("has healthCheckTimeout of 120_000", () => {
+        expect(new SingleBotStrategy().healthCheckTimeout()).toBe(120_000);
+    });
+});
+describe("ImmediateStrategy", () => {
+    it("returns all remaining bots", () => {
+        const s = new ImmediateStrategy();
+        const bots = makeBots(10);
+        expect(s.nextBatch(bots)).toHaveLength(10);
+        expect(s.nextBatch(bots)).toEqual(bots);
+    });
+    it("returns empty for empty remaining", () => {
+        expect(new ImmediateStrategy().nextBatch([])).toHaveLength(0);
+    });
+    it("does not mutate the input array", () => {
+        const s = new ImmediateStrategy();
+        const bots = makeBots(3);
+        const result = s.nextBatch(bots);
+        expect(result).not.toBe(bots);
+        expect(result).toEqual(bots);
+    });
+    it("has pauseDuration of 0", () => {
+        expect(new ImmediateStrategy().pauseDuration()).toBe(0);
+    });
+    it("always skips on failure", () => {
+        const s = new ImmediateStrategy();
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("skip");
+        expect(s.onBotFailure("b1", err, 5)).toBe("skip");
+    });
+    it("has maxRetries of 1", () => {
+        expect(new ImmediateStrategy().maxRetries()).toBe(1);
+    });
+    it("has healthCheckTimeout of 60_000", () => {
+        expect(new ImmediateStrategy().healthCheckTimeout()).toBe(60_000);
+    });
+});
+describe("createRolloutStrategy", () => {
+    it("creates RollingWaveStrategy", () => {
+        const s = createRolloutStrategy("rolling-wave");
+        expect(s).toBeInstanceOf(RollingWaveStrategy);
+    });
+    it("creates RollingWaveStrategy with options", () => {
+        const s = createRolloutStrategy("rolling-wave", { batchPercent: 50, pauseMs: 10_000 });
+        expect(s).toBeInstanceOf(RollingWaveStrategy);
+        expect(s.pauseDuration()).toBe(10_000);
+    });
+    it("creates SingleBotStrategy", () => {
+        const s = createRolloutStrategy("single-bot");
+        expect(s).toBeInstanceOf(SingleBotStrategy);
+    });
+    it("creates ImmediateStrategy", () => {
+        const s = createRolloutStrategy("immediate");
+        expect(s).toBeInstanceOf(ImmediateStrategy);
+    });
+});

package/dist/fleet/__tests__/volume-snapshot-manager.test.d.ts

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

package/dist/fleet/__tests__/volume-snapshot-manager.test.js

@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { VolumeSnapshotManager } from "../volume-snapshot-manager.js";
+// Mock fs/promises
+vi.mock("node:fs/promises", () => ({
+    mkdir: vi.fn().mockResolvedValue(undefined),
+    stat: vi.fn().mockResolvedValue({ size: 1024, mtime: new Date("2026-03-14T10:00:00Z") }),
+    readdir: vi.fn().mockResolvedValue([]),
+    rm: vi.fn().mockResolvedValue(undefined),
+}));
+// Mock logger
+vi.mock("../../config/logger.js", () => ({
+    logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+    },
+}));
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
+function mockContainer() {
+    return {
+        start: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue({ StatusCode: 0 }),
+        remove: vi.fn().mockResolvedValue(undefined),
+    };
+}
+function mockDocker() {
+    return {
+        createContainer: vi.fn().mockResolvedValue(mockContainer()),
+    };
+}
+describe("VolumeSnapshotManager", () => {
+    let docker;
+    let manager;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        docker = mockDocker();
+        manager = new VolumeSnapshotManager(docker, "/data/fleet/snapshots");
+    });
+    describe("snapshot()", () => {
+        it("creates container with correct binds and runs tar", async () => {
+            await manager.snapshot("my-volume");
+            expect(docker.createContainer).toHaveBeenCalledWith(expect.objectContaining({
+                Image: "alpine:latest",
+                Cmd: expect.arrayContaining(["tar", "cf"]),
+                HostConfig: expect.objectContaining({
+                    Binds: expect.arrayContaining(["my-volume:/source:ro", "/data/fleet/snapshots:/backup"]),
+                    AutoRemove: true,
+                }),
+            }));
+            const container = await docker.createContainer.mock.results[0].value;
+            expect(container.start).toHaveBeenCalled();
+            expect(container.wait).toHaveBeenCalled();
+        });
+        it("returns a VolumeSnapshot with correct fields", async () => {
+            const result = await manager.snapshot("my-volume");
+            expect(result.volumeName).toBe("my-volume");
+            expect(result.id).toMatch(/^my-volume-\d{4}-\d{2}-\d{2}T/);
+            expect(result.archivePath).toMatch(/^\/data\/fleet\/snapshots\/my-volume-.*\.tar$/);
+            expect(result.sizeBytes).toBe(1024);
+            expect(result.createdAt).toBeInstanceOf(Date);
+        });
+        it("ensures backup directory exists", async () => {
+            await manager.snapshot("my-volume");
+            expect(mkdir).toHaveBeenCalledWith("/data/fleet/snapshots", { recursive: true });
+        });
+        it("cleans up container on start failure", async () => {
+            const container = mockContainer();
+            container.start.mockRejectedValue(new Error("start failed"));
+            docker.createContainer.mockResolvedValue(container);
+            await expect(manager.snapshot("my-volume")).rejects.toThrow("start failed");
+            expect(container.remove).toHaveBeenCalledWith({ force: true });
+        });
+    });
+    describe("restore()", () => {
+        it("creates container with correct binds and runs tar xf", async () => {
+            const snapshotId = "my-volume-2026-03-14T10-00-00-000Z";
+            await manager.restore(snapshotId);
+            expect(docker.createContainer).toHaveBeenCalledWith(expect.objectContaining({
+                Image: "alpine:latest",
+                Cmd: ["sh", "-c", `cd /target && rm -rf ./* ./.??* && tar xf /backup/${snapshotId}.tar -C /target`],
+                HostConfig: expect.objectContaining({
+                    Binds: expect.arrayContaining(["my-volume:/target", "/data/fleet/snapshots:/backup:ro"]),
+                    AutoRemove: true,
+                }),
+            }));
+        });
+        it("starts and waits for container", async () => {
+            const container = mockContainer();
+            docker.createContainer.mockResolvedValue(container);
+            await manager.restore("my-volume-2026-03-14T10-00-00-000Z");
+            expect(container.start).toHaveBeenCalled();
+            expect(container.wait).toHaveBeenCalled();
+        });
+        it("throws if archive does not exist", async () => {
+            stat.mockRejectedValueOnce(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            await expect(manager.restore("nonexistent-2026-03-14T10-00-00-000Z")).rejects.toThrow("ENOENT");
+        });
+    });
+    describe("list()", () => {
+        it("returns snapshots sorted by date, newest first", async () => {
+            readdir.mockResolvedValue([
+                "my-volume-2026-03-12T08-00-00-000Z.tar",
+                "my-volume-2026-03-14T10-00-00-000Z.tar",
+                "my-volume-2026-03-13T09-00-00-000Z.tar",
+            ]);
+            const oldDate = new Date("2026-03-12T08:00:00Z");
+            const midDate = new Date("2026-03-13T09:00:00Z");
+            const newDate = new Date("2026-03-14T10:00:00Z");
+            stat
+                .mockResolvedValueOnce({ size: 100, mtime: oldDate })
+                .mockResolvedValueOnce({ size: 300, mtime: newDate })
+                .mockResolvedValueOnce({ size: 200, mtime: midDate });
+            const result = await manager.list("my-volume");
+            expect(result).toHaveLength(3);
+            expect(result[0].createdAt).toEqual(newDate);
+            expect(result[1].createdAt).toEqual(midDate);
+            expect(result[2].createdAt).toEqual(oldDate);
+        });
+        it("filters to only matching volume name", async () => {
+            readdir.mockResolvedValue([
+                "my-volume-2026-03-14T10-00-00-000Z.tar",
+                "other-volume-2026-03-14T10-00-00-000Z.tar",
+            ]);
+            const result = await manager.list("my-volume");
+            expect(result).toHaveLength(1);
+            expect(result[0].volumeName).toBe("my-volume");
+        });
+        it("returns empty array when backup dir does not exist", async () => {
+            readdir.mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            const result = await manager.list("my-volume");
+            expect(result).toEqual([]);
+        });
+    });
+    describe("delete()", () => {
+        it("removes the archive file", async () => {
+            await manager.delete("my-volume-2026-03-14T10-00-00-000Z");
+            expect(rm).toHaveBeenCalledWith("/data/fleet/snapshots/my-volume-2026-03-14T10-00-00-000Z.tar", { force: true });
+        });
+    });
+    describe("cleanup()", () => {
+        it("removes old snapshots and keeps recent ones", async () => {
+            const now = Date.now();
+            const oldTime = new Date(now - 2 * 60 * 60 * 1000); // 2 hours ago
+            const recentTime = new Date(now - 10 * 60 * 1000); // 10 minutes ago
+            readdir.mockResolvedValue([
+                "vol-2026-03-14T08-00-00-000Z.tar",
+                "vol-2026-03-14T09-50-00-000Z.tar",
+            ]);
+            stat
+                .mockResolvedValueOnce({ size: 100, mtime: oldTime })
+                .mockResolvedValueOnce({ size: 200, mtime: recentTime });
+            const maxAge = 60 * 60 * 1000; // 1 hour
+            const deleted = await manager.cleanup(maxAge);
+            expect(deleted).toBe(1);
+            expect(rm).toHaveBeenCalledTimes(1);
+            expect(rm).toHaveBeenCalledWith("/data/fleet/snapshots/vol-2026-03-14T08-00-00-000Z.tar", { force: true });
+        });
+        it("returns 0 when backup dir does not exist", async () => {
+            readdir.mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            const result = await manager.cleanup(60_000);
+            expect(result).toBe(0);
+        });
+        it("skips non-tar files", async () => {
+            readdir.mockResolvedValue(["readme.txt", ".gitkeep"]);
+            const result = await manager.cleanup(60_000);
+            expect(result).toBe(0);
+            expect(stat).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/fleet/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./repository-types.js";
+export * from "./rollout-strategy.js";
 export * from "./services.js";
 export * from "./types.js";
+export * from "./volume-snapshot-manager.js";

package/dist/fleet/index.js

@@ -1,3 +1,5 @@
 export * from "./repository-types.js";
+export * from "./rollout-strategy.js";
 export * from "./services.js";
 export * from "./types.js";
+export * from "./volume-snapshot-manager.js";

package/dist/fleet/rollout-strategy.d.ts

@@ -0,0 +1,52 @@
+import type { BotProfile } from "./types.js";
+export interface IRolloutStrategy {
+    /** Select next batch from remaining bots */
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    /** Milliseconds to wait between waves */
+    pauseDuration(): number;
+    /** What to do when a single bot update fails */
+    onBotFailure(botId: string, error: Error, attempt: number): "abort" | "skip" | "retry";
+    /** Max retries per bot before skip/abort */
+    maxRetries(): number;
+    /** Health check timeout per bot (ms) */
+    healthCheckTimeout(): number;
+}
+export interface RollingWaveOptions {
+    batchPercent?: number;
+    pauseMs?: number;
+    maxFailures?: number;
+}
+/**
+ * Rolling wave strategy — processes bots in configurable percentage batches.
+ * Create a new instance per rollout; totalFailures accumulates across waves
+ * within a single rollout. Call reset() if reusing across rollouts.
+ */
+export declare class RollingWaveStrategy implements IRolloutStrategy {
+    private readonly batchPercent;
+    private readonly pauseMs;
+    private readonly maxFailures;
+    private totalFailures;
+    constructor(opts?: RollingWaveOptions);
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+    /** Reset failure counters for reuse across rollouts. */
+    reset(): void;
+}
+export declare class SingleBotStrategy implements IRolloutStrategy {
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+}
+export declare class ImmediateStrategy implements IRolloutStrategy {
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, _attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+}
+export declare function createRolloutStrategy(type: "rolling-wave" | "single-bot" | "immediate", options?: RollingWaveOptions): IRolloutStrategy;

package/dist/fleet/rollout-strategy.js

@@ -0,0 +1,91 @@
+/**
+ * Rolling wave strategy — processes bots in configurable percentage batches.
+ * Create a new instance per rollout; totalFailures accumulates across waves
+ * within a single rollout. Call reset() if reusing across rollouts.
+ */
+export class RollingWaveStrategy {
+    batchPercent;
+    pauseMs;
+    maxFailures;
+    totalFailures = 0;
+    constructor(opts = {}) {
+        this.batchPercent = opts.batchPercent ?? 25;
+        this.pauseMs = opts.pauseMs ?? 60_000;
+        this.maxFailures = opts.maxFailures ?? 3;
+    }
+    nextBatch(remaining) {
+        if (remaining.length === 0)
+            return [];
+        const count = Math.max(1, Math.ceil((remaining.length * this.batchPercent) / 100));
+        return remaining.slice(0, count);
+    }
+    pauseDuration() {
+        return this.pauseMs;
+    }
+    onBotFailure(_botId, _error, attempt) {
+        if (attempt < this.maxRetries())
+            return "retry";
+        this.totalFailures++;
+        if (this.totalFailures >= this.maxFailures)
+            return "abort";
+        return "skip";
+    }
+    maxRetries() {
+        return 2;
+    }
+    healthCheckTimeout() {
+        return 120_000;
+    }
+    /** Reset failure counters for reuse across rollouts. */
+    reset() {
+        this.totalFailures = 0;
+    }
+}
+export class SingleBotStrategy {
+    nextBatch(remaining) {
+        if (remaining.length === 0)
+            return [];
+        return remaining.slice(0, 1);
+    }
+    pauseDuration() {
+        return 0;
+    }
+    onBotFailure(_botId, _error, attempt) {
+        if (attempt < this.maxRetries())
+            return "retry";
+        return "abort";
+    }
+    maxRetries() {
+        return 3;
+    }
+    healthCheckTimeout() {
+        return 120_000;
+    }
+}
+export class ImmediateStrategy {
+    nextBatch(remaining) {
+        return [...remaining];
+    }
+    pauseDuration() {
+        return 0;
+    }
+    onBotFailure(_botId, _error, _attempt) {
+        return "skip";
+    }
+    maxRetries() {
+        return 1;
+    }
+    healthCheckTimeout() {
+        return 60_000;
+    }
+}
+export function createRolloutStrategy(type, options) {
+    switch (type) {
+        case "rolling-wave":
+            return new RollingWaveStrategy(options);
+        case "single-bot":
+            return new SingleBotStrategy();
+        case "immediate":
+            return new ImmediateStrategy();
+    }
+}

package/dist/fleet/volume-snapshot-manager.d.ts

@@ -0,0 +1,35 @@
+import type Docker from "dockerode";
+export interface VolumeSnapshot {
+    id: string;
+    volumeName: string;
+    archivePath: string;
+    createdAt: Date;
+    sizeBytes: number;
+}
+/**
+ * Snapshots and restores Docker named volumes using temporary alpine containers.
+ * Used for nuclear rollback during fleet updates — if a container update fails,
+ * we roll back both the image AND the data volumes.
+ */
+export declare class VolumeSnapshotManager {
+    private readonly docker;
+    private readonly backupDir;
+    constructor(docker: Docker, backupDir?: string);
+    /** Create a snapshot of a Docker named volume */
+    snapshot(volumeName: string): Promise<VolumeSnapshot>;
+    /** Restore a volume from a snapshot */
+    restore(snapshotId: string): Promise<void>;
+    /** List all snapshots for a volume */
+    list(volumeName: string): Promise<VolumeSnapshot[]>;
+    /** Delete a snapshot archive */
+    delete(snapshotId: string): Promise<void>;
+    /** Delete all snapshots older than maxAge ms */
+    cleanup(maxAgeMs: number): Promise<number>;
+    /**
+     * Extract volume name from snapshot ID.
+     * Snapshot IDs are `${volumeName}-${ISO timestamp with colons/dots replaced}`.
+     * ISO timestamps start with 4 digits (year), so we find the last occurrence
+     * of `-YYYY` pattern to split.
+     */
+    private extractVolumeName;
+}