Example script: download every album's photos and metadata (closes #144)

`examples/download-albums.ts` logs in with `QUAK_EMAIL` and `QUAK_PASSWORD`,
opens the library, and for every album downloads each photo to its save path,
writes `{savePath}.json` with the photo's record (cache paths left out) and its
EXIF fields, and writes `albums/{collectionID}.json` with the album's save
paths. A JSON file is written only when its content changed, so a second run
downloads and rewrites nothing. `tsconfig.json` includes `examples/`, so the
build type-checks it. A test runs it twice against a stand-in account.

Model: opus-5-5

test/examples/download-albums.test.ts

@@ -0,0 +1,287 @@
+/**
+ * The example script `examples/download-albums.ts` (issue #144), run twice
+ * against a stand-in account, as a user would run it twice.
+ *
+ * The account has two albums sharing one photo, and one of its photos is a
+ * live photo whose image is a HEIC with EXIF. The first run puts every
+ * original at its save path, writes each photo's metadata beside it and each
+ * album's photos under `albums/`. The second run fetches nothing and changes
+ * no file.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+    existsSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    statSync,
+    utimesSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { downloadAlbums } from "../../examples/download-albums.js";
+import { Library, type ContentSource } from "../../src/index.js";
+import type { CollectionsPage, FilesPage } from "../../src/client.js";
+import type { Collection, EnteFile } from "../../src/model/types.js";
+import { HEIC_WITH_EXIF } from "../exif-heic.js";
+import {
+    asLivePhoto,
+    cdnSource,
+    livePhotoHash,
+    livePhotoZip,
+    VIDEO,
+} from "../live-photo.js";
+
+const USER_ID = 7;
+
+// Every photo is taken at noon local time on 2026-03-01, so the machine's time
+// zone cannot move it to another day; it is saved in the folder `DAY`. Ente
+// stores times in microseconds.
+const TAKEN_MS = new Date(2026, 2, 1, 12).getTime();
+const DAY = join("2026", "2026-03", "2026-03-01");
+
+const collection = (id: number, name: string): Collection => ({
+    id,
+    ownerID: USER_ID,
+    key: new Uint8Array([id]),
+    name,
+    type: "album",
+    updationTime: 1,
+    isShared: false,
+});
+
+const file = (id: number, collectionID: number): EnteFile => ({
+    id,
+    collectionID,
+    ownerID: USER_ID,
+    key: new Uint8Array([id]),
+    metadata: {
+        title: `file-${id}.jpg`,
+        fileType: "image",
+        creationTime: TAKEN_MS * 1000,
+        modificationTime: TAKEN_MS * 1000,
+    },
+    file: { decryptionHeader: "aGVhZGVy" },
+    thumbnail: { decryptionHeader: "dGh1bWI=" },
+    updationTime: 1,
+});
+
+let root: string;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "quak-download-albums-"));
+});
+
+afterEach(() => {
+    if (root && existsSync(root))
+        rmSync(root, { recursive: true, force: true });
+});
+
+// Every file and directory under `dir`, by path.
+const entries = (dir: string): string[] =>
+    readdirSync(dir, { recursive: true, encoding: "utf-8" });
+
+// Set the modification time of everything under `dir` to the epoch, so that
+// anything written there afterwards has a later one, however soon it comes.
+const backdate = (dir: string): void => {
+    for (const name of entries(dir)) utimesSync(join(dir, name), 0, 0);
+};
+
+// The modification time of everything under `dir`, by path.
+const mtimes = (dir: string): Map<string, number> =>
+    new Map(
+        entries(dir).map((name) => [name, statSync(join(dir, name)).mtimeMs]),
+    );
+
+const readJSON = (path: string): unknown =>
+    JSON.parse(readFileSync(path, "utf-8"));
+
+describe("examples/download-albums.ts", () => {
+    it("downloads every album's photos with their metadata, and nothing on a second run", async () => {
+        // Album 1, "Trip", holds photos 1 and 2. Album 2, "Family", holds
+        // photo 2 and photo 3, a live photo.
+        const live = await asLivePhoto(
+            file(3, 2),
+            livePhotoZip({ "image.heic": HEIC_WITH_EXIF, "video.mov": VIDEO }),
+            livePhotoHash(HEIC_WITH_EXIF, VIDEO),
+        );
+        const client = {
+            whoami: () => ({ email: "u@example.com", userID: USER_ID }),
+            collectionsSince: async (): Promise<CollectionsPage> => ({
+                collections: [collection(1, "Trip"), collection(2, "Family")],
+                deleted: [],
+                cursor: 1,
+            }),
+            filesSince: async (args: {
+                collectionID: number;
+            }): Promise<FilesPage> => ({
+                files:
+                    args.collectionID === 1
+                        ? [file(1, 1), file(2, 1)]
+                        : [file(2, 2), live.file],
+                deleted: [],
+                cursor: 1,
+            }),
+        };
+
+        // Photo 3 comes from a stand-in server, encrypted as Ente serves a
+        // live photo. Any other original is a few bytes naming its photo.
+        // `calls` counts every fetch, thumbnails included.
+        const server = cdnSource(new Map([[3, live.body]]));
+        let calls = 0;
+        const source: ContentSource = {
+            original: async (args) => {
+                calls++;
+                if (args.file.id === 3) return server.original(args);
+                const bytes = `original-${args.file.id}`;
+                writeFileSync(args.destination, bytes);
+                return { bytesWritten: bytes.length };
+            },
+            thumbnail: async (args) => {
+                calls++;
+                return server.thumbnail(args);
+            },
+        };
+
+        const dir = join(root, "photos");
+        const open = (): Promise<Library> =>
+            Library.open({
+                client,
+                cacheDirectory: join(root, "cache"),
+                downloadDirectory: dir,
+                contentSource: source,
+                refreshIntervalSeconds: 3600,
+                precacheThumbnails: false,
+                precacheOriginals: false,
+            });
+
+        const first = await open();
+        // The cache already holds photo 1's original, so its record names a
+        // cache path, which the metadata leaves out. download() copies it
+        // from the cache rather than fetching it again.
+        await first.photos.byID({ fileID: 1 })!.original();
+        expect(await downloadAlbums(first, dir)).toEqual({
+            downloaded: 3,
+            alreadyLocal: 0,
+        });
+        await first.close();
+        expect(calls).toBe(3);
+
+        // Each original at its save path, a live photo as its image, its video
+        // and the file naming them, and each photo's metadata beside it.
+        const day = join(dir, DAY);
+        expect(readdirSync(day).sort()).toEqual([
+            "2026-03-01.1.jpg",
+            "2026-03-01.1.jpg.json",
+            "2026-03-01.2.jpg",
+            "2026-03-01.2.jpg.json",
+            "2026-03-01.3.heic",
+            "2026-03-01.3.heic.json",
+            "2026-03-01.3.livephoto.json",
+            "2026-03-01.3.mov",
+        ]);
+        expect(readFileSync(join(day, "2026-03-01.1.jpg"), "utf-8")).toBe(
+            "original-1",
+        );
+        expect(readFileSync(join(day, "2026-03-01.2.jpg"), "utf-8")).toBe(
+            "original-2",
+        );
+        expect(readFileSync(join(day, "2026-03-01.3.heic"))).toEqual(
+            Buffer.from(HEIC_WITH_EXIF),
+        );
+        expect(readFileSync(join(day, "2026-03-01.3.mov"))).toEqual(
+            Buffer.from(VIDEO),
+        );
+
+        // The metadata is the photo's record and its EXIF fields. The
+        // originals of photos 1 and 2 are not image data, so they have no
+        // EXIF fields. Photo 3's image holds a camera, an exposure and a
+        // position, and the date it was taken is written as an ISO 8601
+        // string. `record` holds the fields the three records share.
+        const record = {
+            takenAt: TAKEN_MS,
+            modifiedAt: TAKEN_MS,
+            fileType: "image",
+            isArchived: false,
+            isHidden: false,
+        };
+        expect(readJSON(join(day, "2026-03-01.1.jpg.json"))).toEqual({
+            ...record,
+            fileID: 1,
+            albumIDs: [1],
+            title: "file-1.jpg",
+            exif: {},
+        });
+        expect(readJSON(join(day, "2026-03-01.2.jpg.json"))).toEqual({
+            ...record,
+            fileID: 2,
+            albumIDs: [1, 2],
+            title: "file-2.jpg",
+            exif: {},
+        });
+        expect(readJSON(join(day, "2026-03-01.3.heic.json"))).toEqual({
+            ...record,
+            fileID: 3,
+            albumIDs: [2],
+            title: "file-3.jpg",
+            fileType: "livePhoto",
+            hash: livePhotoHash(HEIC_WITH_EXIF, VIDEO),
+            exif: {
+                make: "Canon",
+                model: "EOS R5",
+                lensModel: "RF50mm F1.8 STM",
+                dateTimeOriginal: "2021-07-15T14:30:00.000Z",
+                offsetTimeOriginal: "+02:00",
+                exposureTime: 1 / 250,
+                fNumber: 2.8,
+                iso: 400,
+                focalLength: 50,
+                orientation: 6,
+                gpsLatitude: 40 + 26 / 60 + 46 / 3600,
+                gpsLongitude: -(79 + 58 / 60 + 56 / 3600),
+                gpsAltitude: -12.5,
+            },
+        });
+
+        // Each album's photos, newest first, by save path relative to `dir`.
+        // Photo 2 is in both.
+        expect(readdirSync(join(dir, "albums")).sort()).toEqual([
+            "1.json",
+            "2.json",
+        ]);
+        expect(readJSON(join(dir, "albums", "1.json"))).toEqual({
+            collectionID: 1,
+            name: "Trip",
+            savePaths: [
+                join(DAY, "2026-03-01.2.jpg"),
+                join(DAY, "2026-03-01.1.jpg"),
+            ],
+        });
+        expect(readJSON(join(dir, "albums", "2.json"))).toEqual({
+            collectionID: 2,
+            name: "Family",
+            savePaths: [
+                join(DAY, "2026-03-01.3.heic"),
+                join(DAY, "2026-03-01.2.jpg"),
+            ],
+        });
+
+        // The second run, with a newly opened library, finds every photo
+        // already local, fetches nothing, and writes, renames or adds no
+        // file.
+        backdate(dir);
+        const before = mtimes(dir);
+        const second = await open();
+        expect(await downloadAlbums(second, dir)).toEqual({
+            downloaded: 0,
+            alreadyLocal: 3,
+        });
+        await second.close();
+        expect(calls).toBe(3);
+        expect(mtimes(dir)).toEqual(before);
+    });
+});