dbkeeper 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,240 @@
+<div align="center">
+
+<img src="./assets/DB-Keeper.png" alt="DBKeeper - Automatic Database Backup" width="100%">
+
+</div>
+
+<div align="center">
+
+<pre>
+██████╗ ██████╗ ██╗  ██╗███████╗███████╗██████╗ ███████╗██████╗ 
+██╔══██╗██╔══██╗██║ ██╔╝██╔════╝██╔════╝██╔══██╗██╔════╝██╔══██╗
+██║  ██║██████╔╝█████╔╝ █████╗  █████╗  ██████╔╝█████╗  ██████╔╝
+██║  ██║██╔══██╗██╔═██╗ ██╔══╝  ██╔══╝  ██╔═══╝ ██╔══╝  ██╔══██╗
+██████╔╝██████╔╝██║  ██╗███████╗███████╗██║     ███████╗██║  ██║
+╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝
+</pre>
+
+</div>
+
+**Reliable, self-hosted database backups for MongoDB and beyond.**
+
+[![npm version](https://img.shields.io/npm/v/dbkeeper)](https://www.npmjs.com/package/dbkeeper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/node/v/dbkeeper)](https://nodejs.org)
+
+---
+
+
+
+
+## Why this exists
+
+Most backup solutions are either cloud-locked SaaS products with recurring fees, or bare shell scripts with no retry logic, no rotation safety, and no notifications. dbkeeper is a self-hosted CLI tool that handles rolling backup retention, safe rotation (never deletes an old backup before a new one is verified uploaded), and email notifications — all in one composable package. No subscription. No vendor lock-in. You own your data pipeline.
+
+---
+
+## Features
+
+- **MongoDB backup** via `mongodump` — produces a compressed `.tar.gz` archive
+- **Google Drive storage** — uploads via service account credentials, no OAuth flow required
+- **Rolling retention** — keep the N most recent backups; older ones are deleted automatically
+- **Safe rotation** — old backups are only deleted *after* the new upload is confirmed with a remote ID
+- **Email notifications** — configurable success and/or failure alerts via any SMTP server
+- **TypeScript-first** — full type declarations included; works equally well from plain JavaScript
+
+---
+
+## Installation
+
+```bash
+# Global (recommended for CLI use)
+npm install -g dbkeeper
+
+# Local dev dependency (for programmatic use or CI)
+npm install --save-dev dbkeeper
+```
+
+---
+
+## Quick Start
+
+**1. Create a `backup.config.js` in your project root:**
+
+```js
+// backup.config.js
+require('dotenv').config();
+
+module.exports = {
+  database: {
+    type: 'mongo',
+    uri: process.env.MONGO_URI,
+  },
+  storage: {
+    type: 'gdrive',
+    credentialsPath: process.env.GDRIVE_CREDENTIALS_PATH ?? './gdrive-credentials.json',
+    folderId: process.env.GDRIVE_FOLDER_ID,
+  },
+  retention: {
+    keep: 24, // keep the 24 most recent backups
+  },
+  notifications: {
+    success: false,
+    failure: true,
+    to: process.env.NOTIFY_EMAIL,
+    smtp: {
+      host: process.env.SMTP_HOST,
+      port: 587,
+      auth: {
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS,
+      },
+    },
+  },
+};
+```
+
+**2. Run a backup:**
+
+```bash
+dbkeeper run
+# or with a custom config path:
+dbkeeper run --config ./config/backup.config.js
+```
+
+**3. Check the last result:**
+
+```bash
+dbkeeper status
+```
+
+---
+
+## Configuration Reference
+
+All configuration is provided via a `backup.config.js` (or any `.js` file) that exports a plain object.
+
+### `database`
+
+| Field  | Type     | Required | Description                                      |
+|--------|----------|----------|--------------------------------------------------|
+| `type` | `string` | ✅        | Database type. Currently only `"mongo"`.         |
+| `uri`  | `string` | ✅        | MongoDB connection URI (supports Atlas SRV URIs). |
+
+### `storage`
+
+| Field               | Type     | Required | Description                                                       |
+|---------------------|----------|----------|-------------------------------------------------------------------|
+| `type`              | `string` | ✅        | Storage backend. Currently only `"gdrive"`.                       |
+| `credentialsPath`   | `string` | ✅        | Path to the Google Drive service account JSON key file.           |
+| `folderId`          | `string` | ✅        | ID of the Drive folder where backups will be stored.              |
+
+### `retention`
+
+| Field  | Type               | Required | Description                                                                   |
+|--------|--------------------|----------|-------------------------------------------------------------------------------|
+| `keep` | `number \| "unlimited"` | ✅  | Number of recent backups to keep. Use `"unlimited"` to disable deletion.      |
+
+### `notifications`
+
+| Field     | Type      | Required | Description                                                     |
+|-----------|-----------|----------|-----------------------------------------------------------------|
+| `success` | `boolean` | ✅        | Send an email when a backup succeeds.                           |
+| `failure` | `boolean` | ✅        | Send an email when a backup fails.                              |
+| `to`      | `string`  | ✅        | Recipient email address.                                        |
+| `smtp`    | `object`  | ✴️ *     | SMTP connection config (required if `success` or `failure` is `true`). |
+
+**`smtp` sub-fields:**
+
+| Field    | Type      | Default | Description                           |
+|----------|-----------|---------|---------------------------------------|
+| `host`   | `string`  | —       | SMTP server hostname.                 |
+| `port`   | `number`  | `587`   | SMTP port.                            |
+| `secure` | `boolean` | `false` | Use TLS (`true` for port 465).        |
+| `auth`   | `object`  | —       | `{ user: string, pass: string }`      |
+
+---
+
+## Google Drive Setup
+
+dbkeeper authenticates with Google Drive via a **service account** — there's no OAuth browser flow.
+
+1. **Enable the Drive API** — Go to [Google Cloud Console](https://console.cloud.google.com) → APIs & Services → Enable APIs → search for "Google Drive API" and enable it.
+
+2. **Create a service account** — Go to IAM & Admin → Service Accounts → Create Service Account. Give it a name (e.g. `dbkeeper-backup`), skip the optional role assignment.
+
+3. **Download the JSON key** — Inside your new service account, go to Keys → Add Key → Create new key → JSON. Save the file somewhere secure (e.g. `./gdrive-credentials.json`). **Do not commit this file to version control.**
+
+4. **Share the target folder** — In Google Drive, right-click your backup folder → Share → paste in the service account's email address (e.g. `dbkeeper-backup@your-project.iam.gserviceaccount.com`) and give it **Editor** access.
+
+5. **Get the folder ID** — Open the folder in Drive. The URL will look like `https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz`. The folder ID is the last path segment.
+
+---
+
+## How Retention Works
+
+After each successful upload, dbkeeper lists all backup files in your Drive folder and applies retention. Given `keep: N`:
+
+- It sorts all backups by creation date (oldest first).
+- It keeps the N most recent files.
+- It deletes everything older.
+- **Deletion only happens after the new upload has been verified** — dbkeeper confirms the remote file ID is non-empty before touching any existing backups.
+
+**Example** with `keep: 3`, running daily:
+
+```
+Before run:  backup-day1.tar.gz  backup-day2.tar.gz  backup-day3.tar.gz
+After run:   backup-day2.tar.gz  backup-day3.tar.gz  backup-day4.tar.gz
+             (day1 deleted, day4 uploaded — always 3 in storage)
+```
+
+Set `keep: "unlimited"` to accumulate all backups indefinitely.
+
+---
+
+## Programmatic API
+
+dbkeeper also exports its internals for use in custom scripts or other tooling:
+
+```ts
+import { runBackup, mongoAdapter, gdriveAdapter, loadConfig } from 'dbkeeper';
+
+const config = loadConfig('./backup.config.js');
+const result = await runBackup(config, mongoAdapter, gdriveAdapter);
+
+if (result.ok) {
+  console.log(`Backed up to Drive: ${result.remoteId}`);
+}
+```
+
+You can also bring your own adapters by implementing the `DatabaseAdapter` or `StorageAdapter` interfaces:
+
+```ts
+import { DatabaseAdapter, StorageAdapter } from 'dbkeeper';
+```
+
+---
+
+## Roadmap
+
+The following are **not yet implemented**. This list is here so you know exactly what dbkeeper does and doesn't do today:
+
+- [ ] PostgreSQL support
+- [ ] MySQL / MariaDB support
+- [ ] Amazon S3 storage backend
+- [ ] Encryption at rest (GPG or AES)
+- [ ] Restore verification (test-restore and checksum validation)
+- [ ] Web dashboard / status UI
+- [ ] Cron scheduling built into the CLI (currently relies on system cron or a process manager)
+
+---
+
+## Contributing
+
+dbkeeper is open source and welcomes contributions. If you hit a bug, have a feature request, or want to add a new database or storage adapter, open an issue or a pull request on [GitHub](https://github.com/<your-github-username>/dbkeeper). The codebase is intentionally small and straightforward — adapters are just two-method interfaces, so adding support for a new backend is a well-defined, self-contained task.
+
+---
+
+## License
+
+MIT © Faysal Sarker — see [LICENSE](./LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * dbkeeper CLI entry point.
+ *
+ * Thin wrapper — all real logic lives in src/core/runBackup.ts.
+ * Supported commands (v1):
+ *   dbkeeper run      Execute one backup immediately
+ *   dbkeeper status   Show the last backup result from the status file
+ */
+import 'dotenv/config';

package/dist/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * dbkeeper CLI entry point.
+ *
+ * Thin wrapper — all real logic lives in src/core/runBackup.ts.
+ * Supported commands (v1):
+ *   dbkeeper run      Execute one backup immediately
+ *   dbkeeper status   Show the last backup result from the status file
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+require("dotenv/config");
+const loadConfig_1 = require("./config/loadConfig");
+const runBackup_1 = require("./core/runBackup");
+const mongo_1 = require("./database/mongo");
+const gdrive_1 = require("./storage/gdrive");
+const logger_1 = require("./core/logger");
+// ---------------------------------------------------------------------------
+// Status file — persisted to cwd so it survives process restarts
+// ---------------------------------------------------------------------------
+const STATUS_FILE = path.resolve(process.cwd(), '.dbkeeper-status.json');
+function saveStatus(result) {
+    try {
+        fs.writeFileSync(STATUS_FILE, JSON.stringify(result, null, 2), 'utf8');
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function readStatus() {
+    try {
+        if (!fs.existsSync(STATUS_FILE))
+            return null;
+        return JSON.parse(fs.readFileSync(STATUS_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Command: run
+// ---------------------------------------------------------------------------
+async function cmdRun(configPath) {
+    const config = (0, loadConfig_1.loadConfig)(configPath);
+    // Select adapters based on config types
+    // (v1 only supports mongo + gdrive — add more cases here for future adapters)
+    if (config.database.type !== 'mongo') {
+        logger_1.logger.error(`Unsupported database type: "${config.database.type}". Only "mongo" is supported in v1.`);
+        process.exit(1);
+    }
+    if (config.storage.type !== 'gdrive') {
+        logger_1.logger.error(`Unsupported storage type: "${config.storage.type}". Only "gdrive" is supported in v1.`);
+        process.exit(1);
+    }
+    const result = await (0, runBackup_1.runBackup)(config, mongo_1.mongoAdapter, gdrive_1.gdriveAdapter);
+    saveStatus(result);
+    if (!result.ok) {
+        process.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command: status
+// ---------------------------------------------------------------------------
+function cmdStatus() {
+    const status = readStatus();
+    if (!status) {
+        console.log('No backup has been run yet. Execute `dbkeeper run` first.');
+        return;
+    }
+    if (status.ok) {
+        console.log(`Last backup: SUCCESS`);
+        console.log(`  Timestamp:  ${new Date(status.timestamp).toISOString()}`);
+        console.log(`  File:       ${path.basename(status.filePath)}`);
+        console.log(`  Size:       ${formatBytes(status.sizeBytes)}`);
+        console.log(`  Remote ID:  ${status.remoteId}`);
+        console.log(`  Retained:   ${status.remainingCount} backup(s) in storage`);
+        console.log(`  Deleted:    ${status.deletedCount} old backup(s)`);
+    }
+    else {
+        console.log(`Last backup: FAILED`);
+        console.log(`  Timestamp:  ${new Date(status.timestamp).toISOString()}`);
+        console.log(`  Error:      ${status.error?.message ?? 'unknown'}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI routing
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.log(`
+dbkeeper — MongoDB backup tool
+
+Usage:
+  dbkeeper run [--config <path>]   Run a backup immediately
+  dbkeeper status                  Show the last backup result
+
+Options:
+  --config <path>   Path to backup.config.js (default: ./backup.config.js)
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === '--help' || command === '-h') {
+        printHelp();
+        return;
+    }
+    const configFlagIndex = args.indexOf('--config');
+    const configPath = configFlagIndex !== -1 ? args[configFlagIndex + 1] : undefined;
+    switch (command) {
+        case 'run':
+            await cmdRun(configPath);
+            break;
+        case 'status':
+            cmdStatus();
+            break;
+        default:
+            console.error(`Unknown command: "${command}". Run \`dbkeeper --help\` for usage.`);
+            process.exit(1);
+    }
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+main().catch((err) => {
+    logger_1.logger.error(`Unhandled error: ${err.message}`);
+    process.exit(1);
+});

package/dist/config/loadConfig.d.ts

@@ -0,0 +1,6 @@
+import { BackupConfig } from '../types';
+/**
+ * Loads `backup.config.js` from the consuming project's root (cwd).
+ * Throws a clear error if the file is missing or invalid.
+ */
+export declare function loadConfig(configPath?: string): BackupConfig;

package/dist/config/loadConfig.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * Loads `backup.config.js` from the consuming project's root (cwd).
+ * Throws a clear error if the file is missing or invalid.
+ */
+function loadConfig(configPath) {
+    const resolvedPath = configPath
+        ? path.resolve(configPath)
+        : path.resolve(process.cwd(), 'backup.config.js');
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`dbkeeper: config file not found at "${resolvedPath}".\n` +
+            `Create a backup.config.js in your project root, or pass --config <path>.`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const raw = require(resolvedPath);
+    if (!raw || typeof raw !== 'object') {
+        throw new Error(`dbkeeper: "${resolvedPath}" must export a plain object. Got: ${typeof raw}`);
+    }
+    const config = raw;
+    // Basic structural validation — keeps error messages actionable
+    if (!config.database?.type) {
+        throw new Error('dbkeeper: config.database.type is required (e.g. "mongo")');
+    }
+    if (!config.database?.uri) {
+        throw new Error('dbkeeper: config.database.uri is required');
+    }
+    if (!config.storage?.type) {
+        throw new Error('dbkeeper: config.storage.type is required (e.g. "gdrive")');
+    }
+    if (config.retention?.keep === undefined) {
+        throw new Error('dbkeeper: config.retention.keep is required (use a number or "unlimited")');
+    }
+    if (!config.notifications?.to) {
+        throw new Error('dbkeeper: config.notifications.to (recipient email) is required');
+    }
+    return config;
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lightweight structured logger.
+ *
+ * Prefixes every line with a timestamp and log level.
+ * Replace this with a structured logger (pino, winston, etc.) if needed
+ * without touching any other module — all internal code imports from here.
+ */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+export declare const logger: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+};

package/dist/core/logger.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Lightweight structured logger.
+ *
+ * Prefixes every line with a timestamp and log level.
+ * Replace this with a structured logger (pino, winston, etc.) if needed
+ * without touching any other module — all internal code imports from here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+function stamp() {
+    return new Date().toISOString();
+}
+function write(level, message) {
+    const line = `[${stamp()}] [${level.toUpperCase()}] ${message}`;
+    if (level === 'error') {
+        process.stderr.write(line + '\n');
+    }
+    else {
+        process.stdout.write(line + '\n');
+    }
+}
+exports.logger = {
+    info: (msg) => write('info', msg),
+    warn: (msg) => write('warn', msg),
+    error: (msg) => write('error', msg),
+    debug: (msg) => write('debug', msg),
+};

package/dist/core/retention.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure rolling-retention logic.
+ *
+ * No I/O, no network calls — fully unit-testable.
+ * The caller is responsible for actually deleting the returned IDs.
+ */
+export interface RemoteFile {
+    remoteId: string;
+    createdAt: Date;
+}
+export interface RetentionResult {
+    /** Files that should be deleted to satisfy the keep limit. */
+    toDelete: RemoteFile[];
+    /** How many files will remain after deletion. */
+    remainingCount: number;
+}
+/**
+ * Given the current list of remote backup files (oldest-first) and the keep
+ * limit, return which files need to be deleted and how many will remain.
+ *
+ * @param existing  All existing backups, **including** the one just uploaded.
+ * @param keep      Maximum number of backups to retain, or "unlimited".
+ */
+export declare function applyRetention(existing: RemoteFile[], keep: number | 'unlimited'): RetentionResult;

package/dist/core/retention.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Pure rolling-retention logic.
+ *
+ * No I/O, no network calls — fully unit-testable.
+ * The caller is responsible for actually deleting the returned IDs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRetention = applyRetention;
+/**
+ * Given the current list of remote backup files (oldest-first) and the keep
+ * limit, return which files need to be deleted and how many will remain.
+ *
+ * @param existing  All existing backups, **including** the one just uploaded.
+ * @param keep      Maximum number of backups to retain, or "unlimited".
+ */
+function applyRetention(existing, keep) {
+    if (keep === 'unlimited') {
+        return { toDelete: [], remainingCount: existing.length };
+    }
+    if (typeof keep !== 'number' || keep < 1) {
+        throw new Error(`retention.keep must be a positive integer or "unlimited". Got: ${keep}`);
+    }
+    if (existing.length <= keep) {
+        return { toDelete: [], remainingCount: existing.length };
+    }
+    // Sort by date ascending so the oldest entries are at the front
+    const sorted = [...existing].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    const deleteCount = sorted.length - keep;
+    const toDelete = sorted.slice(0, deleteCount);
+    const remainingCount = sorted.length - deleteCount;
+    return { toDelete, remainingCount };
+}

package/dist/core/runBackup.d.ts

@@ -0,0 +1,20 @@
+import { BackupConfig, DatabaseAdapter, StorageAdapter, BackupResult } from '../types';
+/**
+ * Core backup orchestrator.
+ *
+ * Accepts adapters by interface — never imports mongo.ts or gdrive.ts directly.
+ * This is the key extension point: swap in any DatabaseAdapter / StorageAdapter
+ * to support new databases or storage backends without changing this file.
+ *
+ * Safe rotation order (hard requirement):
+ *   1. dump   → create local backup file
+ *   2. upload → push to remote storage
+ *   3. verify → confirm the remote file ID exists
+ *   4. retain → delete old backups (ONLY after upload is confirmed)
+ *   5. notify → send success / failure email
+ *
+ * If any step before retention fails, we stop immediately:
+ *   - Nothing is deleted from remote storage
+ *   - A failure email is sent (if configured)
+ */
+export declare function runBackup(config: BackupConfig, dbAdapter: DatabaseAdapter, storageAdapter: StorageAdapter): Promise<BackupResult>;