From 5140786e3dae780be754d3c002f2eb00bd7381a2 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:51:53 +1300 Subject: [PATCH] Add bulk-tag script --- CONTRIBUTING.md | 5 +- docs/config/upload-service.md | 2 +- docs/tag-and-review-uploads.md | 48 ++++++ docs/visitor-uploads.md | 2 +- upload-app/src/filename.ts | 42 ++++- upload-app/src/tag-uploads.ts | 254 ++++++++++++++++++++++++++++ upload-app/tests/tagUploads.test.ts | 216 +++++++++++++++++++++++ 7 files changed, 564 insertions(+), 5 deletions(-) create mode 100644 upload-app/src/tag-uploads.ts create mode 100644 upload-app/tests/tagUploads.test.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a432ec..8d199e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,10 +88,11 @@ upload-app/ immich-public-proxy-upload - one page per share; strea share.ts Share lookup through core, cached 60 s gate.ts The upload permit: the share's Immich toggle and the slug-link gate receive.ts Validates one upload request: rate limit, length, filename, type, byte budget - forward.ts The only Immich write call: multipart POST /assets under the share key + forward.ts The service's only Immich write call: multipart POST /assets under the share key limits.ts Fixed-window budgets for the rate limit and the byte budget - filename.ts Stored filename: sanitised, prefixed, extension kept + filename.ts Stored filename: sanitised, prefixed, extension kept; and reading the visitor fields back notify.ts Optional JSON webhook per stored file + tag-uploads.ts Owner-run CLI that tags uploads by visitor name with the owner's API key; the service never loads it idleTimeoutStream.ts Drops a request body that stalls view/upload.tsx The upload page, in the look of Immich's upload UI client/upload.ts The page client: queue, XHR uploads with retry, the upload panel diff --git a/docs/config/upload-service.md b/docs/config/upload-service.md index 2265f5d..6c33ca5 100644 --- a/docs/config/upload-service.md +++ b/docs/config/upload-service.md @@ -111,7 +111,7 @@ field is not shown and a name sent anyway is ignored. The name is stored as a slug: lower case, letters and digits in any script, and a hyphen for anything else, at most 32 characters. A filename that already carries the prefix gets neither the prefix nor the name again. The name is the visitor's own claim; IPP cannot check it. For what to do with it, see -[Find each visitor's uploads](/tag-and-review-uploads#find-each-visitors-uploads). +[Find each visitor's uploads](/tag-and-review-uploads#find-each-visitor-s-uploads). ### `fieldSeparator` diff --git a/docs/tag-and-review-uploads.md b/docs/tag-and-review-uploads.md index 237ad44..656ab09 100644 --- a/docs/tag-and-review-uploads.md +++ b/docs/tag-and-review-uploads.md @@ -34,6 +34,8 @@ given is stored in the filename between the prefix and the original name, with a - Search for `ipp_upload_jane-smith,` to see everything Jane sent. - Add a workflow per visitor to tag or sort their uploads: **Filter by filename**, match type `startsWith`, pattern `ipp_upload_jane-smith,`, then **Add Tags** with a tag such as `Uploaded/Jane Smith`. +- Tag every visitor's uploads at once, including past ones, with the + [bulk-tag script](#tag-every-visitor-s-uploads-at-once). The comma matters: without it, `ipp_upload_jane` would also match `jane-smith` and `janet`. The name is whatever the visitor typed, made lower case with hyphens for spaces and punctuation. A visitor who leaves the field empty is stored @@ -55,6 +57,52 @@ goes on the end, an empty one is written empty, and a file with no fields at all script that splits on the separator reads all of them: the last piece is the original filename, the rest are the fields in order. +## Tag every visitor's uploads at once + +A workflow acts only on new uploads, and you need one for each visitor. The upload image includes a script that tags +every upload with a visitor name, old and new, as `Uploaded/`: `ipp_upload_jane-smith,IMG_0042.jpg` gets the +tag `Uploaded/jane-smith`. + +1. In Immich, sign in as the user who owns the shares. The script sees only that user's photos. +2. Open **Account Settings**, then **API Keys**, and create a **New API Key** with the permissions `asset.read`, + `user.read`, `tag.create` and `tag.asset`. +3. Run the script in the upload container. Without `--apply` it changes nothing, and lists each file under the tag + it would get: + + ```bash + docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js + ``` + +4. Check the list, then run it again with `--apply` to add the tags: + + ```bash + docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js --apply + ``` + +5. Delete the API key in Immich if you don't plan to run the script again. + +The API key reaches only that one command. The upload service itself still holds no key, as described in +[Why IPP marks the filename](#why-ipp-marks-the-filename-instead-of-tagging). + +The script reads [`upload.filenamePrefix`](/config/upload-service#filenameprefix) and +[`upload.fieldSeparator`](/config/upload-service#fieldseparator) from the container's config. A second run adds only +the tags that are missing, so you can run it again after each event. Files without a visitor name, trashed files and +files of other users are left alone. + +| Option | Default | Effect | +|-----------------------|-------------------------|-------------------------------------------------------------------------------------------| +| `--apply` | off | Add the tags. Without it, the script only reports. | +| `--parent ` | `Uploaded` | The parent tag. `--parent "Guests/Wedding"` gives `Guests/Wedding/jane-smith`. | +| `--prefix ` | `upload.filenamePrefix` | The prefix to look for, when the files were stored with a different one. | +| `--separator ` | `upload.fieldSeparator` | The separator to read, when the files were stored with a different one. Quote it: `'^'`. | + +The script does not run when `upload.filenamePrefix` is `""`, because visitor uploads then look like any other photo. + +Uploads from IPP 4.0.0 kept any comma in the visitor's filename, so `ipp_upload_Venice, Italy.jpg` looks as if it +has a visitor field. The script skips a file when the text before the separator is not a name IPP writes, or the +text after it starts with a space, and lists each file it skips. A 4.0.0 file named `ipp_upload_venice,italy.jpg` +still reads as a visitor called `venice`, so check the dry-run list before you use `--apply`. + ## Review uploads before they appear Immich has no approval queue for uploads through a shared link, but a workflow can move each upload into your diff --git a/docs/visitor-uploads.md b/docs/visitor-uploads.md index 57b0ce6..8eefcf7 100644 --- a/docs/visitor-uploads.md +++ b/docs/visitor-uploads.md @@ -49,7 +49,7 @@ What the owner sees in Immich: [turned off](/config/upload-service#filenameprefix). - The upload page asks for the visitor's name, optionally. A name given is stored in the filename after the prefix, as `ipp_upload_jane-smith,IMG_0042.jpg`, so you can see who sent what and - [find each visitor's uploads](/tag-and-review-uploads#find-each-visitors-uploads). The field can be + [find each visitor's uploads](/tag-and-review-uploads#find-each-visitor-s-uploads). The field can be [turned off](/config/upload-service#askname). - The owner removes unwanted files in Immich, like any other photo. diff --git a/upload-app/src/filename.ts b/upload-app/src/filename.ts index 351297a..aeae94f 100644 --- a/upload-app/src/filename.ts +++ b/upload-app/src/filename.ts @@ -52,6 +52,11 @@ export function uploaderSlug (raw: unknown): string { .replace(/-+$/, '') } +/** The prefix as it appears in a stored filename: sanitised and trimmed. */ +export function storedPrefix (prefix: string): string { + return sanitize(prefix).trim() +} + /** The header for these fields, in order, or empty when none has a value. */ function fieldHeader (fields: string[], separator: string): string { if (!fields.some(Boolean)) return '' @@ -78,10 +83,45 @@ export function uploadFilename (raw: unknown, prefix: string, uploader = '', sep // An empty stem is a dotfile; a leading dot is a traversal remnant. if (!stem || stem.startsWith('.')) return undefined - const cleanPrefix = sanitize(prefix).trim() + const cleanPrefix = storedPrefix(prefix) // Don't stack the prefix, or the name, on a file that already carries the prefix const hasPrefix = cleanPrefix !== '' && stem.startsWith(cleanPrefix) const wanted = hasPrefix ? '' : cleanPrefix + fieldHeader([uploader], separator) const room = MAX_FILENAME_LENGTH - wanted.length - extension.length return wanted + stem.slice(0, Math.max(1, room)) + extension } + +/** What a stored filename says about who sent it, from `readUploadFilename`. */ +export type StoredUpload = + | { kind: 'named', uploader: string } + | { kind: 'anonymous' } + | { kind: 'unreadable', reason: string } + +/** + * Read the visitor fields back from a name that `uploadFilename` stored. + * Undefined when the name does not start with `prefix`. The original filename + * never keeps the separator, so the last separator ends the fields and the + * first field is the uploader. A name that `uploadFilename` could not have + * written is unreadable rather than guessed at: 4.0.0 kept commas in the + * visitor's filename, so `ipp_upload_Venice, Italy.jpg` is not a visitor + * called `Venice`. + */ +export function readUploadFilename (name: string, prefix: string, separator: string): StoredUpload | undefined { + if (!prefix || !name.startsWith(prefix)) return undefined + const rest = name.slice(prefix.length) + if (!rest.includes(separator)) return { kind: 'anonymous' } + + const fields = rest.split(separator) + const original = fields.pop() || '' + // `uploadFilename` trims the original, so a leading space means the + // separator was part of the visitor's own filename + if (original === '' || original.trimStart() !== original) { + return { kind: 'unreadable', reason: 'the text after the separator is not a filename IPP wrote' } + } + const uploader = fields[0] + if (uploader === '') return { kind: 'anonymous' } + if (uploaderSlug(uploader) !== uploader) { + return { kind: 'unreadable', reason: '"' + uploader + '" is not a name IPP wrote' } + } + return { kind: 'named', uploader } +} diff --git a/upload-app/src/tag-uploads.ts b/upload-app/src/tag-uploads.ts new file mode 100644 index 0000000..a12062c --- /dev/null +++ b/upload-app/src/tag-uploads.ts @@ -0,0 +1,254 @@ +#!/usr/bin/env node + +/* + Bulk-tag visitor uploads by the name in their filename. The owner runs it in + the upload container with their own Immich API key, which the upload + service itself never holds: + + docker exec -e IMMICH_API_KEY= ipp-upload node dist/tag-uploads.js [--apply] + + `ipp_upload_jane-smith,IMG_0042.jpg` gets the tag `Uploaded/jane-smith`. + Without --apply it only reports what it would tag. A re-run is safe: Immich + skips a tag that an asset already has. +*/ + +import 'dotenv/config' +import { resolve } from 'path' +import { parseArgs } from 'util' +import { apiUrl, loadConfig } from '@ipp/core' +import { fieldSeparator, filenamePrefix } from './config' +import { isUsableSeparator, readUploadFilename, storedPrefix } from './filename' + +/** Immich's largest page for `POST /search/metadata`. */ +const SEARCH_PAGE_SIZE = 1000 +/** Assets per `PUT /tags/assets` call. */ +const TAG_BATCH_SIZE = 500 +const DEFAULT_PARENT = 'Uploaded' +const PERMISSIONS = 'asset.read, user.read, tag.create and tag.asset' + +const USAGE = `Tag visitor uploads in Immich by the name in their filename. + +Usage: node dist/tag-uploads.js [--apply] [--parent ] [--prefix ] [--separator ] + + --apply Add the tags. Without it, only report what would be tagged. + --parent Parent tag for the visitor tags. Default "${DEFAULT_PARENT}". + --prefix Filename prefix to look for. Default ipp.upload.filenamePrefix. + --separator Field separator to read. Default ipp.upload.fieldSeparator. + +IMMICH_API_KEY must hold an API key of the share owner, with the permissions +${PERMISSIONS}.` + +/** What `tagUploads` is told to do. */ +export interface TagOptions { + apiKey: string + apply: boolean + parent: string + prefix: string + separator: string + /** Where each report line goes. */ + print: (line: string) => void +} + +/** What `tagUploads` found and did. */ +export interface TagSummary { + /** Asset IDs per visitor name. */ + named: Map + anonymous: number + unreadable: number + /** Assets that got a tag they did not have. Always 0 in a dry run. */ + tagged: number +} + +/** The fields of an Immich `AssetResponseDto` that the script reads. */ +interface Asset { + id: string + ownerId: string + originalFileName: string + visibility: string + isTrashed: boolean +} + +/** A failed Immich call, with a message fit for the owner. */ +export class ImmichError extends Error {} + +/** One JSON call to the Immich API, authenticated with the owner's key. */ +async function immich (apiKey: string, method: string, path: string, body?: unknown): Promise { + let res: Response + try { + res = await fetch(apiUrl() + path, { + method, + headers: { + 'x-api-key': apiKey, + Accept: 'application/json', + ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) + }, + body: body === undefined ? undefined : JSON.stringify(body) + }) + } catch (e) { + throw new ImmichError('Could not reach Immich at ' + apiUrl() + ': ' + (e instanceof Error ? e.message : String(e))) + } + if (!res.ok) { + const reply = await res.json().catch(() => null) as { message?: unknown } | null + const message = Array.isArray(reply?.message) ? reply?.message.join(', ') : reply?.message + let text = method + ' ' + path + ' failed with status ' + res.status + if (typeof message === 'string' && message) text += ': ' + message + if (res.status === 401) text += '. Check IMMICH_API_KEY.' + if (res.status === 403) text += '. The API key needs the permissions ' + PERMISSIONS + '.' + throw new ImmichError(text) + } + return await res.json() as T +} + +/** + * The key owner's assets whose filename starts with `prefix`. Immich's + * filename search is a case-insensitive substring match that also returns + * partners' photos, so each result is checked here. Trashed assets and the + * hidden video half of a motion photo are left out. + */ +async function findUploads (apiKey: string, prefix: string): Promise { + const me = await immich<{ id: string }>(apiKey, 'GET', '/users/me') + const found: Asset[] = [] + let page: string | null = '1' + while (page) { + const reply: { assets: { items: Asset[], nextPage: string | null } } = await immich(apiKey, 'POST', '/search/metadata', { + originalFileName: prefix, + page: Number(page), + size: SEARCH_PAGE_SIZE + }) + for (const asset of reply.assets.items) { + if (asset.ownerId !== me.id || asset.isTrashed || asset.visibility === 'hidden') continue + if (asset.originalFileName.startsWith(prefix)) found.push(asset) + } + page = reply.assets.nextPage + } + return found +} + +/** `count` and the noun, singular or plural. */ +function files (count: number): string { + return count + (count === 1 ? ' file' : ' files') +} + +/** + * Find the visitor uploads, report them, and with `apply` add a + * `/` tag to each named one. + */ +export async function tagUploads (options: TagOptions): Promise { + const { apiKey, apply, parent, prefix, separator, print } = options + const summary: TagSummary = { named: new Map(), anonymous: 0, unreadable: 0, tagged: 0 } + const fileNames = new Map() + + const uploads = await findUploads(apiKey, prefix) + print('Found ' + files(uploads.length) + ' starting with "' + prefix + '".') + for (const asset of uploads) { + const stored = readUploadFilename(asset.originalFileName, prefix, separator) + if (!stored || stored.kind === 'anonymous') { + summary.anonymous++ + } else if (stored.kind === 'unreadable') { + summary.unreadable++ + print('Skipped ' + asset.originalFileName + ': ' + stored.reason + '.') + } else { + summary.named.set(stored.uploader, [...(summary.named.get(stored.uploader) || []), asset.id]) + fileNames.set(stored.uploader, [...(fileNames.get(stored.uploader) || []), asset.originalFileName]) + } + } + + const names = [...summary.named.keys()].sort() + const tagIds = new Map() + if (apply && names.length) { + const tags = await immich>(apiKey, 'PUT', '/tags', { + tags: names.map(name => parent + '/' + name) + }) + for (const tag of tags) tagIds.set(tag.value, tag.id) + } + + print('') + for (const name of names) { + const ids = summary.named.get(name) || [] + const tag = parent + '/' + name + if (!apply) { + print(tag + ': ' + files(ids.length)) + for (const fileName of (fileNames.get(name) || []).sort()) print(' ' + fileName) + continue + } + const tagId = tagIds.get(tag) + if (!tagId) throw new ImmichError('Immich did not return the tag ' + tag) + let added = 0 + for (let start = 0; start < ids.length; start += TAG_BATCH_SIZE) { + const reply = await immich<{ count: number }>(apiKey, 'PUT', '/tags/assets', { + tagIds: [tagId], + assetIds: ids.slice(start, start + TAG_BATCH_SIZE) + }) + added += reply.count + } + summary.tagged += added + print(tag + ': ' + files(ids.length) + ', ' + added + ' newly tagged') + } + + if (names.length === 0) print('No file has a visitor name.') + if (summary.anonymous) print(files(summary.anonymous) + ' with no visitor name, left untagged.') + if (summary.unreadable) print(files(summary.unreadable) + ' skipped, listed above.') + print('') + if (!apply) { + print('Dry run: nothing was changed. Run again with --apply to add these tags.') + } else { + print('Done. Tagged ' + files(summary.tagged) + '. Files that already had their tag were left as they were.') + } + return summary +} + +/** Read the flags, the environment and the config, run, and return the exit code. */ +export async function main (argv: string[]): Promise { + let values: { apply?: boolean, parent?: string, prefix?: string, separator?: string, help?: boolean } + try { + values = parseArgs({ + args: argv, + options: { + apply: { type: 'boolean' }, + parent: { type: 'string' }, + prefix: { type: 'string' }, + separator: { type: 'string' }, + help: { type: 'boolean', short: 'h' } + } + }).values + } catch (e) { + console.error((e instanceof Error ? e.message : String(e)) + '\n\n' + USAGE) + return 2 + } + if (values.help) { + console.log(USAGE) + return 0 + } + + // The same config file as the service, /app/config.json in the image + loadConfig({ defaultPath: resolve(__dirname, '../config.json') }) + const usage = (problem: string) => { + console.error(problem + '\n\n' + USAGE) + return 2 + } + const apiKey = process.env.IMMICH_API_KEY || '' + if (!apiKey) return usage('IMMICH_API_KEY is not set.') + if (!process.env.IMMICH_URL) return usage('IMMICH_URL is not set.') + const prefix = storedPrefix(values.prefix ?? filenamePrefix()) + if (!prefix) { + return usage('The filename prefix is empty, so visitor uploads cannot be told apart from your own photos. ' + + 'Pass --prefix with the prefix the files were stored with.') + } + const separator = values.separator ?? fieldSeparator() + if (!isUsableSeparator(separator)) return usage('"' + separator + '" cannot be a field separator.') + const parent = (values.parent ?? DEFAULT_PARENT).split('/').map(part => part.trim()).filter(Boolean).join('/') + if (!parent) return usage('The parent tag is empty.') + + try { + await tagUploads({ apiKey, apply: !!values.apply, parent, prefix, separator, print: line => console.log(line) }) + return 0 + } catch (e) { + if (!(e instanceof ImmichError)) throw e + console.error(e.message) + return 1 + } +} + +if (require.main === module) { + main(process.argv.slice(2)).then(code => { process.exitCode = code }) +} diff --git a/upload-app/tests/tagUploads.test.ts b/upload-app/tests/tagUploads.test.ts new file mode 100644 index 0000000..377f02d --- /dev/null +++ b/upload-app/tests/tagUploads.test.ts @@ -0,0 +1,216 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' +import { readUploadFilename, uploadFilename } from '../src/filename' +import { main, tagUploads, TagOptions } from '../src/tag-uploads' +import { resetConfig, setConfig } from './helpers' + +describe('readUploadFilename', () => { + const read = (name: string, separator = ',') => readUploadFilename(name, 'ipp_upload_', separator) + + it('reads the name that uploadFilename wrote', () => { + for (const [file, uploader] of [['IMG_0042.jpg', 'jane-smith'], ['Paris France.jpg', 'zoë-müller'], ['a.png', '山田-太郎']]) { + const stored = uploadFilename(file, 'ipp_upload_', uploader) || '' + expect(read(stored)).toEqual({ kind: 'named', uploader }) + } + }) + + it('reads a configured separator', () => { + expect(read('ipp_upload_jane-smith^Paris, France.jpg', '^')).toEqual({ kind: 'named', uploader: 'jane-smith' }) + }) + + it('takes the first field as the uploader when later fields exist', () => { + expect(read('ipp_upload_jane-smith,34,IMG_0042.jpg')).toEqual({ kind: 'named', uploader: 'jane-smith' }) + }) + + it('is anonymous with no fields or an empty name field', () => { + expect(read('ipp_upload_IMG_0042.jpg')).toEqual({ kind: 'anonymous' }) + expect(read('ipp_upload_,34,IMG_0042.jpg')).toEqual({ kind: 'anonymous' }) + }) + + it('refuses names that 4.0.0 stored with a comma in the visitor filename', () => { + expect(read('ipp_upload_Venice, Italy.jpg')?.kind).toBe('unreadable') + expect(read('ipp_upload_venice, italy.jpg')?.kind).toBe('unreadable') + expect(read('ipp_upload_Smith,John.jpg')?.kind).toBe('unreadable') + }) + + it('is undefined without the prefix, or with an empty prefix', () => { + expect(read('IMG_0042.jpg')).toBeUndefined() + expect(read('IPP_UPLOAD_jane-smith,IMG_0042.jpg')).toBeUndefined() + expect(readUploadFilename('jane-smith,IMG_0042.jpg', '', ',')).toBeUndefined() + }) +}) + +const ME = 'aaaaaaaa-0000-4000-8000-000000000001' +const PARTNER = 'aaaaaaaa-0000-4000-8000-000000000002' + +/** A fake Immich: one owner, a few uploads over two search pages, and tag state that persists between runs. */ +function fakeImmich (extraAssets: Array> = []) { + let next = 0 + const asset = (originalFileName: string, extra: Record = {}) => ({ + id: 'asset-' + (++next), ownerId: ME, originalFileName, visibility: 'timeline', isTrashed: false, ...extra + }) + const page1 = [ + asset('ipp_upload_jane-smith,IMG_0042.jpg'), + asset('ipp_upload_jane-smith,IMG_0043.jpg', { visibility: 'archive' }), + asset('ipp_upload_IMG_0044.jpg'), + asset('ipp_upload_Venice, Italy.jpg'), + asset('ipp_upload_bob,clip.mp4', { ownerId: PARTNER }), + asset('ipp_upload_bob,trashed.jpg', { isTrashed: true }), + asset('ipp_upload_bob,IMG_0045.mp4', { visibility: 'hidden' }), + asset('my_ipp_upload_bob,IMG_0046.jpg'), + asset('IPP_UPLOAD_bob,IMG_0047.jpg') + ] + const page2 = [asset('ipp_upload_zoë-müller,beach.png'), ...extraAssets.map(a => asset(String(a.originalFileName), a))] + const tags = new Map() + const tagged = new Set() + const calls: Array<{ method: string, path: string, body: { assetIds: string[] } }> = [] + + const fetch = vi.fn(async (url: string, init: RequestInit) => { + const path = url.replace('http://immich.test/api', '') + const body = init.body ? JSON.parse(String(init.body)) : undefined + calls.push({ method: init.method || 'GET', path, body }) + const json = (value: unknown, status = 200) => new Response(JSON.stringify(value), { status, headers: { 'Content-Type': 'application/json' } }) + if ((init.headers as Record)['x-api-key'] !== 'good-key') return json({ message: 'Invalid API key' }, 401) + if (path === '/users/me') return json({ id: ME }) + if (path === '/search/metadata') { + return json({ assets: body.page === 1 ? { items: page1, nextPage: '2' } : { items: page2, nextPage: null } }) + } + if (path === '/tags') { + return json(body.tags.map((value: string) => { + if (!tags.has(value)) tags.set(value, 'tag-' + (tags.size + 1)) + return { id: tags.get(value), value } + })) + } + if (path === '/tags/assets') { + let count = 0 + for (const tagId of body.tagIds) { + for (const assetId of body.assetIds) { + if (!tagged.has(tagId + ':' + assetId)) count++ + tagged.add(tagId + ':' + assetId) + } + } + return json({ count }) + } + return json({ message: 'Not found' }, 404) + }) + return { fetch, calls, tags, tagged } +} + +describe('tagUploads', () => { + let lines: string[] + const options = (overrides: Partial = {}): TagOptions => ({ + apiKey: 'good-key', apply: false, parent: 'Uploaded', prefix: 'ipp_upload_', separator: ',', print: line => lines.push(line), ...overrides + }) + + beforeEach(() => { + lines = [] + process.env.IMMICH_URL = 'http://immich.test' + }) + afterEach(() => { + vi.unstubAllGlobals() + delete process.env.IMMICH_URL + }) + + it('reports in a dry run and writes nothing', async () => { + const immich = fakeImmich() + vi.stubGlobal('fetch', immich.fetch) + const summary = await tagUploads(options()) + expect([...summary.named.keys()].sort()).toEqual(['jane-smith', 'zoë-müller']) + expect(summary.named.get('jane-smith')).toHaveLength(2) + expect(summary.anonymous).toBe(1) + expect(summary.unreadable).toBe(1) + expect(summary.tagged).toBe(0) + expect(immich.calls.filter(call => call.method === 'PUT')).toEqual([]) + expect(lines).toContain(' ipp_upload_jane-smith,IMG_0042.jpg') + expect(lines.some(line => line.startsWith('Skipped ipp_upload_Venice, Italy.jpg'))).toBe(true) + expect(lines.at(-1)).toMatch(/^Dry run/) + }) + + it('keeps only the owner\'s untrashed, visible files that start with the exact prefix', async () => { + const immich = fakeImmich() + vi.stubGlobal('fetch', immich.fetch) + const summary = await tagUploads(options()) + expect(summary.named.has('bob')).toBe(false) + expect(lines[0]).toBe('Found 5 files starting with "ipp_upload_".') + }) + + it('tags with --apply, and a second run tags nothing new', async () => { + const immich = fakeImmich() + vi.stubGlobal('fetch', immich.fetch) + const first = await tagUploads(options({ apply: true })) + expect(first.tagged).toBe(3) + expect([...immich.tags.keys()].sort()).toEqual(['Uploaded/jane-smith', 'Uploaded/zoë-müller']) + expect(lines).toContain('Uploaded/jane-smith: 2 files, 2 newly tagged') + + lines = [] + const second = await tagUploads(options({ apply: true })) + expect(second.tagged).toBe(0) + expect(lines).toContain('Uploaded/jane-smith: 2 files, 0 newly tagged') + }) + + it('sends large sets in batches', async () => { + const many = Array.from({ length: 1201 }, (_, i) => ({ originalFileName: `ipp_upload_crowd,IMG_${i}.jpg` })) + const immich = fakeImmich(many) + vi.stubGlobal('fetch', immich.fetch) + const summary = await tagUploads(options({ apply: true })) + const batches = immich.calls.filter(call => call.path === '/tags/assets').map(call => call.body.assetIds.length) + expect(batches).toEqual([500, 500, 201, 2, 1]) + expect(summary.tagged).toBe(1204) + }) + + it('uses the given parent and separator', async () => { + const immich = fakeImmich([{ originalFileName: 'ipp_upload_ann^Rome, Italy.jpg' }]) + vi.stubGlobal('fetch', immich.fetch) + await tagUploads(options({ apply: true, parent: 'Guests/2026', separator: '^' })) + expect([...immich.tags.keys()]).toEqual(['Guests/2026/ann']) + }) + + it('stops with a useful message when Immich refuses the key', async () => { + vi.stubGlobal('fetch', fakeImmich().fetch) + await expect(tagUploads(options({ apiKey: 'bad-key' }))).rejects.toThrow(/status 401: Invalid API key\. Check IMMICH_API_KEY\./) + }) +}) + +describe('main', () => { + let errors: string[] + beforeEach(() => { + errors = [] + vi.spyOn(console, 'error').mockImplementation((line: string) => { errors.push(line) }) + vi.spyOn(console, 'log').mockImplementation(() => {}) + process.env.IMMICH_URL = 'http://immich.test' + process.env.IMMICH_API_KEY = 'good-key' + }) + afterEach(() => { + vi.restoreAllMocks() + vi.unstubAllGlobals() + resetConfig() + delete process.env.IMMICH_URL + delete process.env.IMMICH_API_KEY + }) + + it('needs an API key', async () => { + delete process.env.IMMICH_API_KEY + expect(await main([])).toBe(2) + expect(errors[0]).toMatch(/^IMMICH_API_KEY is not set/) + }) + + it('refuses an empty prefix, which would match the owner\'s own photos', async () => { + setConfig({ ipp: { upload: { filenamePrefix: '' } } }) + expect(await main([])).toBe(2) + expect(errors[0]).toMatch(/prefix is empty/) + }) + + it('refuses an unknown flag or an unusable separator', async () => { + expect(await main(['--aply'])).toBe(2) + expect(await main(['--separator', '-'])).toBe(2) + }) + + it('reads the separator from config, and exits 1 on an Immich error', async () => { + setConfig({ ipp: { upload: { fieldSeparator: '^' } } }) + const immich = fakeImmich([{ originalFileName: 'ipp_upload_ann^Rome, Italy.jpg' }]) + vi.stubGlobal('fetch', immich.fetch) + expect(await main(['--apply'])).toBe(0) + expect([...immich.tags.keys()]).toEqual(['Uploaded/ann']) + process.env.IMMICH_API_KEY = 'bad-key' + expect(await main([])).toBe(1) + }) +})