react-native-ensys-camera-x 1.0.7

package/src/db/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Encrypted media database — public API.
+ *
+ * A modular SQLCipher persistence layer for the camera plugin:
+ *   - `DatabaseManager`     centralized encrypted connection + primitives
+ *   - `migrations`          schema versioning (PRAGMA user_version)
+ *   - `MediaRepository`     typed CRUD/service layer
+ *   - `MediaMapper`         CameraAsset ⇆ MediaRecord translation
+ *   - `useMediaDatabase`    React hook bridging UI and the store
+ *   - `secureKey`           Keystore-backed encryption-key provisioning
+ *
+ * Consumers should generally use `useMediaDatabase` (UI) or `getMediaRepository`
+ * (imperative), and call `initializeMediaDatabase()` once at startup.
+ */
+
+// Models & types
+export type {
+  MediaRecord,
+  MediaRecordInput,
+  MediaType,
+  MediaSource,
+  MediaFilter,
+  MediaCounts,
+  MediaQueryOptions,
+} from './types';
+export { MEDIA_TABLE, MediaColumns } from './types';
+
+// Centralized manager
+export {
+  DatabaseManager,
+  getDatabaseManager,
+  initializeMediaDatabase,
+  type BatchStatement,
+} from './DatabaseManager';
+
+// Schema versioning & migrations
+export {
+  MIGRATIONS,
+  LATEST_SCHEMA_VERSION,
+  runMigrations,
+  type Migration,
+  type MigrationExecutor,
+} from './migrations';
+
+// Repository / service layer
+export { MediaRepository, getMediaRepository } from './MediaRepository';
+
+// Mapping helpers
+export {
+  assetToRecordInput,
+  recordToAsset,
+  rowToRecord,
+  assetTypeToMediaType,
+  mediaTypeToAssetType,
+  normalizeSource,
+  extensionForMimeType,
+  // Documents-path & source resolution (persistence contract)
+  resolveDocumentsPath,
+  isPublishedToDocuments,
+  detectSource,
+} from './MediaMapper';
+
+// Encryption key provisioning
+export {
+  getDatabaseKey,
+  isHardwareBackedKeyAvailable,
+} from './secureKey';
+
+// React hook
+export {
+  useMediaDatabase,
+  type UseMediaDatabaseResult,
+} from './useMediaDatabase';

package/src/db/migrations.ts

@@ -0,0 +1,222 @@
+/**
+ * Schema versioning & migrations for the encrypted media database.
+ *
+ * Versioning uses SQLite's built-in `PRAGMA user_version`. On every open,
+ * `runMigrations` reads the current version and applies — inside a single
+ * transaction — every migration whose target version is greater than it, in
+ * ascending order. Adding a new schema change is a matter of appending one more
+ * entry to `MIGRATIONS`; never edit or reorder existing entries.
+ */
+import { MEDIA_TABLE, MediaColumns } from './types';
+
+/** A single forward migration step. */
+export interface Migration {
+  /** Target `user_version` this migration upgrades the database to. */
+  version: number;
+  /** Human-readable description (documentation only). */
+  description: string;
+  /** Ordered SQL statements executed to reach `version`. */
+  statements: string[];
+}
+
+/**
+ * Ordered list of migrations. `LATEST_SCHEMA_VERSION` is derived from the last
+ * entry, so bumping the schema only requires appending a new `Migration`.
+ */
+export const MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    description: 'Initial media table with type/source indexes',
+    statements: [
+      `CREATE TABLE IF NOT EXISTS ${MEDIA_TABLE} (
+        ${MediaColumns.id}         TEXT PRIMARY KEY NOT NULL,
+        ${MediaColumns.mediaType}  TEXT NOT NULL CHECK (${MediaColumns.mediaType} IN ('image','video')),
+        ${MediaColumns.source}     TEXT NOT NULL CHECK (${MediaColumns.source} IN ('camera','gallery')),
+        ${MediaColumns.filePath}   TEXT NOT NULL,
+        ${MediaColumns.fileName}   TEXT NOT NULL,
+        ${MediaColumns.fileSize}   INTEGER,
+        ${MediaColumns.width}      INTEGER,
+        ${MediaColumns.height}     INTEGER,
+        ${MediaColumns.duration}   INTEGER,
+        ${MediaColumns.mimeType}   TEXT,
+        ${MediaColumns.createdAt}  INTEGER NOT NULL,
+        ${MediaColumns.updatedAt}  INTEGER NOT NULL
+      );`,
+      `CREATE INDEX IF NOT EXISTS idx_media_type
+        ON ${MEDIA_TABLE} (${MediaColumns.mediaType});`,
+      `CREATE INDEX IF NOT EXISTS idx_media_created_at
+        ON ${MEDIA_TABLE} (${MediaColumns.createdAt} DESC);`,
+      // Non-unique: speeds up delete-by-path without rejecting a re-selected
+      // file that arrives under a new id (dedup is keyed on the primary id).
+      `CREATE INDEX IF NOT EXISTS idx_media_file_path
+        ON ${MEDIA_TABLE} (${MediaColumns.filePath});`,
+    ],
+  },
+  {
+    version: 2,
+    description:
+      'Composite (media_type, created_at DESC) index for the filtered+ordered list query',
+    statements: [
+      // The Photos/Videos filters run `WHERE media_type = ? ORDER BY created_at DESC`
+      // (see MediaRepository.getAll). The single-column idx_media_type filters but then
+      // forces a sort of the matching rows on every query; the single-column
+      // idx_media_created_at orders but can't also filter. A composite index lets SQLite
+      // satisfy BOTH the equality filter and the ordering from one index — no separate
+      // sort step — which keeps the filtered list fast as the library grows into the
+      // thousands. Purely additive (CREATE INDEX IF NOT EXISTS): no data change, and the
+      // unfiltered "All" query keeps using idx_media_created_at.
+      `CREATE INDEX IF NOT EXISTS idx_media_type_created_at
+        ON ${MEDIA_TABLE} (${MediaColumns.mediaType}, ${MediaColumns.createdAt} DESC);`,
+    ],
+  },
+  {
+    version: 3,
+    description:
+      'Widen media_type to include document + audio, and reclassify legacy rows by MIME/extension',
+    // SQLite cannot ALTER a CHECK constraint in place, so the table is rebuilt.
+    // The copy step reclassifies rows the old two-kind schema was forced to store
+    // as `image`: a picked PDF/track kept its real MIME (e.g. application/pdf,
+    // audio/mpeg) even though media_type was clamped to 'image', so we recover the
+    // correct kind here from mime_type (then the file extension as a fallback).
+    statements: [
+      // 1. Park the current table out of the way (its indexes move with it).
+      `ALTER TABLE ${MEDIA_TABLE} RENAME TO ${MEDIA_TABLE}_legacy_v2;`,
+      // 2. Recreate the table with the widened media_type CHECK constraint.
+      `CREATE TABLE ${MEDIA_TABLE} (
+        ${MediaColumns.id}         TEXT PRIMARY KEY NOT NULL,
+        ${MediaColumns.mediaType}  TEXT NOT NULL CHECK (${MediaColumns.mediaType} IN ('image','video','document','audio')),
+        ${MediaColumns.source}     TEXT NOT NULL CHECK (${MediaColumns.source} IN ('camera','gallery')),
+        ${MediaColumns.filePath}   TEXT NOT NULL,
+        ${MediaColumns.fileName}   TEXT NOT NULL,
+        ${MediaColumns.fileSize}   INTEGER,
+        ${MediaColumns.width}      INTEGER,
+        ${MediaColumns.height}     INTEGER,
+        ${MediaColumns.duration}   INTEGER,
+        ${MediaColumns.mimeType}   TEXT,
+        ${MediaColumns.createdAt}  INTEGER NOT NULL,
+        ${MediaColumns.updatedAt}  INTEGER NOT NULL
+      );`,
+      // 3. Copy rows over, reclassifying media_type from mime_type / file extension.
+      `INSERT INTO ${MEDIA_TABLE} (
+        ${MediaColumns.id}, ${MediaColumns.mediaType}, ${MediaColumns.source},
+        ${MediaColumns.filePath}, ${MediaColumns.fileName}, ${MediaColumns.fileSize},
+        ${MediaColumns.width}, ${MediaColumns.height}, ${MediaColumns.duration},
+        ${MediaColumns.mimeType}, ${MediaColumns.createdAt}, ${MediaColumns.updatedAt}
+      )
+      SELECT
+        ${MediaColumns.id},
+        CASE
+          WHEN ${MediaColumns.mediaType} = 'video' THEN 'video'
+          WHEN ${MediaColumns.mimeType} LIKE 'video/%' THEN 'video'
+          WHEN ${MediaColumns.mimeType} LIKE 'audio/%' THEN 'audio'
+          WHEN ${MediaColumns.mimeType} LIKE 'image/%' THEN 'image'
+          WHEN ${MediaColumns.mimeType} = 'application/pdf'
+            OR ${MediaColumns.mimeType} LIKE 'application/vnd.%'
+            OR ${MediaColumns.mimeType} LIKE 'application/msword%'
+            OR ${MediaColumns.mimeType} LIKE 'application/rtf%'
+            OR ${MediaColumns.mimeType} = 'application/epub+zip'
+            OR ${MediaColumns.mimeType} LIKE 'text/%' THEN 'document'
+          WHEN lower(${MediaColumns.fileName}) LIKE '%.mp4'
+            OR lower(${MediaColumns.fileName}) LIKE '%.mov'
+            OR lower(${MediaColumns.fileName}) LIKE '%.mkv'
+            OR lower(${MediaColumns.fileName}) LIKE '%.webm'
+            OR lower(${MediaColumns.fileName}) LIKE '%.3gp'
+            OR lower(${MediaColumns.fileName}) LIKE '%.m4v' THEN 'video'
+          WHEN lower(${MediaColumns.fileName}) LIKE '%.mp3'
+            OR lower(${MediaColumns.fileName}) LIKE '%.wav'
+            OR lower(${MediaColumns.fileName}) LIKE '%.aac'
+            OR lower(${MediaColumns.fileName}) LIKE '%.m4a'
+            OR lower(${MediaColumns.fileName}) LIKE '%.ogg'
+            OR lower(${MediaColumns.fileName}) LIKE '%.flac'
+            OR lower(${MediaColumns.fileName}) LIKE '%.opus'
+            OR lower(${MediaColumns.fileName}) LIKE '%.amr' THEN 'audio'
+          WHEN lower(${MediaColumns.fileName}) LIKE '%.pdf'
+            OR lower(${MediaColumns.fileName}) LIKE '%.doc'
+            OR lower(${MediaColumns.fileName}) LIKE '%.docx'
+            OR lower(${MediaColumns.fileName}) LIKE '%.xls'
+            OR lower(${MediaColumns.fileName}) LIKE '%.xlsx'
+            OR lower(${MediaColumns.fileName}) LIKE '%.ppt'
+            OR lower(${MediaColumns.fileName}) LIKE '%.pptx'
+            OR lower(${MediaColumns.fileName}) LIKE '%.txt'
+            OR lower(${MediaColumns.fileName}) LIKE '%.csv'
+            OR lower(${MediaColumns.fileName}) LIKE '%.rtf'
+            OR lower(${MediaColumns.fileName}) LIKE '%.odt'
+            OR lower(${MediaColumns.fileName}) LIKE '%.ods'
+            OR lower(${MediaColumns.fileName}) LIKE '%.odp'
+            OR lower(${MediaColumns.fileName}) LIKE '%.epub' THEN 'document'
+          ELSE 'image'
+        END,
+        ${MediaColumns.source}, ${MediaColumns.filePath}, ${MediaColumns.fileName},
+        ${MediaColumns.fileSize}, ${MediaColumns.width}, ${MediaColumns.height},
+        ${MediaColumns.duration}, ${MediaColumns.mimeType}, ${MediaColumns.createdAt},
+        ${MediaColumns.updatedAt}
+      FROM ${MEDIA_TABLE}_legacy_v2;`,
+      // 4. Drop the legacy table (this also drops its now-orphaned indexes,
+      //    freeing the index names for recreation below).
+      `DROP TABLE ${MEDIA_TABLE}_legacy_v2;`,
+      // 5. Recreate every index on the rebuilt table.
+      `CREATE INDEX IF NOT EXISTS idx_media_type
+        ON ${MEDIA_TABLE} (${MediaColumns.mediaType});`,
+      `CREATE INDEX IF NOT EXISTS idx_media_created_at
+        ON ${MEDIA_TABLE} (${MediaColumns.createdAt} DESC);`,
+      `CREATE INDEX IF NOT EXISTS idx_media_file_path
+        ON ${MEDIA_TABLE} (${MediaColumns.filePath});`,
+      `CREATE INDEX IF NOT EXISTS idx_media_type_created_at
+        ON ${MEDIA_TABLE} (${MediaColumns.mediaType}, ${MediaColumns.createdAt} DESC);`,
+    ],
+  },
+  {
+    version: 4,
+    description:
+      'Add size_is_display_estimate flag: true when file_size is a compressed video’s proportional display figure, not the exact bytes on disk',
+    // Purely additive. Existing rows get NULL (read back as false), so nothing
+    // that was stored before this column re-stats differently. Only compressed
+    // videos published from the editor set it to 1 (see CameraAsset.sizeIsDisplayEstimate).
+    statements: [
+      `ALTER TABLE ${MEDIA_TABLE} ADD COLUMN ${MediaColumns.sizeIsDisplayEstimate} INTEGER;`,
+    ],
+  },
+];
+
+/** The schema version the app expects after all migrations are applied. */
+export const LATEST_SCHEMA_VERSION =
+  MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1]!.version : 0;
+
+/** Minimal executor contract so migrations don't depend on the concrete manager. */
+export interface MigrationExecutor {
+  /** Reads the current `PRAGMA user_version`. */
+  getVersion(): Promise<number>;
+  /** Runs the given statements atomically in a single transaction. */
+  runBatch(statements: string[]): Promise<void>;
+}
+
+/**
+ * Applies all pending migrations. Safe to call on every launch — a fully
+ * up-to-date database performs only a cheap version read and returns.
+ *
+ * @returns the schema version after migration.
+ */
+export async function runMigrations(
+  executor: MigrationExecutor
+): Promise<number> {
+  const currentVersion = await executor.getVersion();
+
+  if (currentVersion >= LATEST_SCHEMA_VERSION) {
+    return currentVersion;
+  }
+
+  const pending = MIGRATIONS.filter((m) => m.version > currentVersion).sort(
+    (a, b) => a.version - b.version
+  );
+
+  for (const migration of pending) {
+    // Each migration is atomic: the DDL statements and the version bump land in
+    // one transaction, or the whole step rolls back and the next launch retries.
+    await executor.runBatch([
+      ...migration.statements,
+      `PRAGMA user_version = ${Math.floor(migration.version)};`,
+    ]);
+  }
+
+  return LATEST_SCHEMA_VERSION;
+}

package/src/db/react-native-sqlcipher.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Ambient type declaration for `react-native-sqlcipher`.
+ *
+ * `react-native-sqlcipher` is a SQLCipher-backed fork of
+ * `react-native-sqlite-storage` and ships without TypeScript types. This
+ * declaration types only the subset of the WebSQL-style API that the database
+ * layer in `src/db` actually consumes, so the project typechecks whether or not
+ * the native package has been installed yet.
+ *
+ * The runtime API is loaded lazily (see `DatabaseManager`), so a missing package
+ * is a graceful runtime fallback rather than a build error.
+ */
+declare module 'react-native-sqlcipher' {
+  export interface ResultSetRowList {
+    length: number;
+    item(index: number): any;
+    raw(): any[];
+  }
+
+  export interface ResultSet {
+    insertId?: number;
+    rowsAffected: number;
+    rows: ResultSetRowList;
+  }
+
+  export interface Transaction {
+    executeSql(
+      sqlStatement: string,
+      args?: any[]
+    ): Promise<[Transaction, ResultSet]>;
+  }
+
+  export interface SQLiteDatabase {
+    transaction(scope: (tx: Transaction) => void): Promise<Transaction>;
+    readTransaction(scope: (tx: Transaction) => void): Promise<Transaction>;
+    executeSql(
+      sqlStatement: string,
+      args?: any[]
+    ): Promise<[ResultSet]>;
+    close(): Promise<void>;
+    attach?(...args: any[]): Promise<any>;
+    dbName?: string;
+  }
+
+  export interface OpenDatabaseParams {
+    /** Database file name, e.g. `media_secure.db`. */
+    name: string;
+    /** SQLCipher passphrase used to encrypt/decrypt the database. */
+    key?: string;
+    /** Storage location. `default` = app's internal Documents/Databases dir. */
+    location?: 'default' | 'Library' | 'Documents';
+    createFromLocation?: number | string;
+  }
+
+  export interface SQLiteStatic {
+    /** Enable promise-based API (must be called before openDatabase). */
+    enablePromise(enabled: boolean): void;
+    /** Enable/disable verbose native logging. */
+    DEBUG(enabled: boolean): void;
+    openDatabase(
+      params: OpenDatabaseParams
+    ): Promise<SQLiteDatabase>;
+    openDatabase(
+      params: OpenDatabaseParams,
+      success?: (db: SQLiteDatabase) => void,
+      error?: (err: any) => void
+    ): SQLiteDatabase;
+    deleteDatabase(params: {
+      name: string;
+      location?: string;
+    }): Promise<void>;
+  }
+
+  const SQLite: SQLiteStatic;
+  export default SQLite;
+}

package/src/db/secureKey.ts

@@ -0,0 +1,100 @@
+/**
+ * Encryption-key provisioning for the SQLCipher database.
+ *
+ * Strategy (most secure first):
+ *   1. Native `SecureKeyModule` (Android) — generates a cryptographically random
+ *      256-bit key on first launch and persists it in `EncryptedSharedPreferences`,
+ *      which is sealed by a master key held in the Android Keystore. The raw key
+ *      material therefore never lives in the JS bundle or in plaintext on disk.
+ *   2. Fallback — a locally derived key used only when the native module is
+ *      unavailable (web, iOS without the native helper, or an older build). This
+ *      keeps the app functional but is NOT hardware-backed; see the warning below.
+ *
+ * The resolved key is cached in-memory for the process lifetime so the native
+ * bridge is hit at most once.
+ */
+import { NativeModules, Platform } from 'react-native';
+
+/** Shape of the optional native key module. */
+interface SecureKeyNativeModule {
+  getOrCreateDatabaseKey(): Promise<string>;
+}
+
+const nativeKeyModule: SecureKeyNativeModule | undefined = (
+  NativeModules as Record<string, SecureKeyNativeModule | undefined>
+).SecureKeyModule;
+
+let cachedKey: string | null = null;
+
+/**
+ * Deterministic fallback key. Used ONLY when no native Keystore-backed module is
+ * present. It is intentionally derived (not a bare literal) but, because it is
+ * reconstructable from the bundle, it does not provide hardware-backed secrecy.
+ * On Android the native module supersedes this path.
+ */
+function deriveFallbackKey(): string {
+  // A stable, app-scoped seed combined into a 64-hex-char (256-bit) string.
+  const seed = `rncc.media.${Platform.OS}.v1.9f3ac21e-secure-media-store`;
+  let h1 = 0x811c9dc5;
+  let h2 = 0xc2b2ae35;
+  for (let i = 0; i < seed.length; i++) {
+    const c = seed.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ c, 0x85ebca77) >>> 0;
+  }
+  // Expand the two 32-bit hashes into 64 hex chars deterministically.
+  let out = '';
+  let a = h1 >>> 0;
+  let b = h2 >>> 0;
+  for (let i = 0; i < 8; i++) {
+    a = (Math.imul(a, 0x9e3779b1) + 0x7f4a7c15) >>> 0;
+    b = (Math.imul(b, 0x85ebca6b) + 0xc2b2ae35) >>> 0;
+    out += a.toString(16).padStart(8, '0');
+    out += b.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, 64);
+}
+
+/**
+ * Resolve the SQLCipher passphrase, preferring the hardware-backed native key.
+ * The result is memoized for the lifetime of the JS runtime.
+ */
+export async function getDatabaseKey(): Promise<string> {
+  if (cachedKey) return cachedKey;
+
+  if (nativeKeyModule?.getOrCreateDatabaseKey) {
+    try {
+      const key = await nativeKeyModule.getOrCreateDatabaseKey();
+      if (key && key.length >= 16) {
+        cachedKey = key;
+        return cachedKey;
+      }
+      console.warn(
+        '[SecureKey] Native module returned an unusable key; using fallback.'
+      );
+    } catch (error) {
+      console.warn(
+        '[SecureKey] Native key retrieval failed; using fallback.',
+        error
+      );
+    }
+  } else if (Platform.OS === 'android') {
+    console.warn(
+      '[SecureKey] SecureKeyModule not linked. Rebuild the Android app to enable ' +
+        'Keystore-backed encryption; using derived fallback key for now.'
+    );
+  }
+
+  cachedKey = deriveFallbackKey();
+  return cachedKey;
+}
+
+/** True when the hardware-backed native key module is available. */
+export function isHardwareBackedKeyAvailable(): boolean {
+  return Boolean(nativeKeyModule?.getOrCreateDatabaseKey);
+}
+
+/** Test/hot-reload helper: clears the in-memory key cache. */
+export function __resetDatabaseKeyCache(): void {
+  cachedKey = null;
+}

package/src/db/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Strongly-typed media models for the encrypted SQLCipher database.
+ *
+ * These types describe the *persistence* shape of a media item — the exact
+ * columns stored in the `media` table — independently of the UI-facing
+ * `CameraAsset` type. Mapping between the two lives in `MediaMapper.ts`, keeping
+ * a clean separation between the database schema and the rest of the app.
+ */
+
+/**
+ * Persisted media kind. Photos are normalized to `image`; documents and audio
+ * are first-class kinds so a picked PDF/track is never mis-stored as an image.
+ */
+export type MediaType = 'image' | 'video' | 'document' | 'audio';
+
+/** Where a media item originated. */
+export type MediaSource = 'camera' | 'gallery';
+
+/**
+ * A single row of the `media` table — the canonical, strongly-typed record.
+ *
+ * `null` is used (never `undefined`) for absent optional columns so the shape
+ * maps 1:1 onto SQL rows.
+ */
+export interface MediaRecord {
+  /** Unique identifier (primary key). */
+  id: string;
+  /** `image` or `video`. */
+  mediaType: MediaType;
+  /** `camera` or `gallery`. */
+  source: MediaSource;
+  /** Absolute file path or content URI. */
+  filePath: string;
+  /** Display file name, e.g. `photo_1699999999999.jpg`. */
+  fileName: string;
+  /** File size in bytes, or null if unknown. */
+  fileSize: number | null;
+  /** Pixel width, or null if unknown. */
+  width: number | null;
+  /** Pixel height, or null if unknown. */
+  height: number | null;
+  /** Duration in milliseconds (videos only), or null. */
+  duration: number | null;
+  /** MIME type such as `image/jpeg` or `video/mp4`, or null. */
+  mimeType: string | null;
+  /** Creation timestamp (epoch ms). */
+  createdAt: number;
+  /** Last-updated timestamp (epoch ms). */
+  updatedAt: number;
+  /**
+   * True when {@link fileSize} is a DISPLAY convention (a compressed video's
+   * proportional figure) rather than the exact bytes on disk. Read back onto
+   * `CameraAsset.sizeIsDisplayEstimate` so the preview / Info panel keeps the
+   * quoted size instead of re-statting the file. Absent (legacy) rows read false.
+   */
+  sizeIsDisplayEstimate: boolean;
+}
+
+/**
+ * Fields required to insert a new media record. Timestamps are optional on
+ * input — the repository fills `createdAt`/`updatedAt` when omitted.
+ */
+export interface MediaRecordInput {
+  id: string;
+  mediaType: MediaType;
+  source: MediaSource;
+  filePath: string;
+  fileName: string;
+  fileSize?: number | null;
+  width?: number | null;
+  height?: number | null;
+  duration?: number | null;
+  mimeType?: string | null;
+  createdAt?: number;
+  updatedAt?: number;
+  /** See {@link MediaRecord.sizeIsDisplayEstimate}. Stored as INTEGER 1/0. */
+  sizeIsDisplayEstimate?: boolean | null;
+}
+
+/** Filter used when querying the media list. */
+export type MediaFilter = 'all' | 'image' | 'video' | 'document' | 'audio';
+
+/**
+ * Aggregate counts computed directly from the database via `COUNT(*)`.
+ * Backs the filter-card counters (All / Photos / Videos / Documents / Audio).
+ */
+export interface MediaCounts {
+  all: number;
+  image: number;
+  video: number;
+  document: number;
+  audio: number;
+}
+
+/** Options for ordered/paged queries against the media table. */
+export interface MediaQueryOptions {
+  filter?: MediaFilter;
+  /** Column to order by. Defaults to `createdAt`. */
+  orderBy?: 'createdAt' | 'updatedAt' | 'fileName';
+  /** Sort direction. Defaults to `DESC` (newest first). */
+  direction?: 'ASC' | 'DESC';
+  limit?: number;
+  offset?: number;
+}
+
+/** Table + column name constants — single source of truth for SQL strings. */
+export const MEDIA_TABLE = 'media';
+
+export const MediaColumns = {
+  id: 'id',
+  mediaType: 'media_type',
+  source: 'source',
+  filePath: 'file_path',
+  fileName: 'file_name',
+  fileSize: 'file_size',
+  width: 'width',
+  height: 'height',
+  duration: 'duration',
+  mimeType: 'mime_type',
+  createdAt: 'created_at',
+  updatedAt: 'updated_at',
+  sizeIsDisplayEstimate: 'size_is_display_estimate',
+} as const;