Add bulk-tag script

This commit is contained in:
Alan Grainger
2026-10-19 17:51:53 +13:00
parent ac34a03482
commit 5140786e3d
7 changed files with 564 additions and 5 deletions
+3 -2
View File
@@ -88,10 +88,11 @@ upload-app/ immich-public-proxy-upload - one page per share; strea
share.ts Share lookup through core, cached 60 s share.ts Share lookup through core, cached 60 s
gate.ts The upload permit: the share's Immich toggle and the slug-link gate 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 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 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 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 idleTimeoutStream.ts Drops a request body that stalls
view/upload.tsx The upload page, in the look of Immich's upload UI 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 client/upload.ts The page client: queue, XHR uploads with retry, the upload panel
+1 -1
View File
@@ -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 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 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 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` ### `fieldSeparator`
+48
View File
@@ -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. - 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 - 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`. `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 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 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 script that splits on the separator reads all of them: the last piece is the original filename, the rest are the
fields in order. 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/<name>`: `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 <tag>` | `Uploaded` | The parent tag. `--parent "Guests/Wedding"` gives `Guests/Wedding/jane-smith`. |
| `--prefix <text>` | `upload.filenamePrefix` | The prefix to look for, when the files were stored with a different one. |
| `--separator <chars>` | `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 ## 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 Immich has no approval queue for uploads through a shared link, but a workflow can move each upload into your
+1 -1
View File
@@ -49,7 +49,7 @@ What the owner sees in Immich:
[turned off](/config/upload-service#filenameprefix). [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, - 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 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). [turned off](/config/upload-service#askname).
- The owner removes unwanted files in Immich, like any other photo. - The owner removes unwanted files in Immich, like any other photo.
+41 -1
View File
@@ -52,6 +52,11 @@ export function uploaderSlug (raw: unknown): string {
.replace(/-+$/, '') .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. */ /** The header for these fields, in order, or empty when none has a value. */
function fieldHeader (fields: string[], separator: string): string { function fieldHeader (fields: string[], separator: string): string {
if (!fields.some(Boolean)) return '' 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. // An empty stem is a dotfile; a leading dot is a traversal remnant.
if (!stem || stem.startsWith('.')) return undefined 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 // Don't stack the prefix, or the name, on a file that already carries the prefix
const hasPrefix = cleanPrefix !== '' && stem.startsWith(cleanPrefix) const hasPrefix = cleanPrefix !== '' && stem.startsWith(cleanPrefix)
const wanted = hasPrefix ? '' : cleanPrefix + fieldHeader([uploader], separator) const wanted = hasPrefix ? '' : cleanPrefix + fieldHeader([uploader], separator)
const room = MAX_FILENAME_LENGTH - wanted.length - extension.length const room = MAX_FILENAME_LENGTH - wanted.length - extension.length
return wanted + stem.slice(0, Math.max(1, room)) + extension 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 }
}
+254
View File
@@ -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=<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 <tag>] [--prefix <text>] [--separator <chars>]
--apply Add the tags. Without it, only report what would be tagged.
--parent <tag> Parent tag for the visitor tags. Default "${DEFAULT_PARENT}".
--prefix <text> Filename prefix to look for. Default ipp.upload.filenamePrefix.
--separator <chars> 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<string, string[]>
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<T> (apiKey: string, method: string, path: string, body?: unknown): Promise<T> {
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<Asset[]> {
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
* `<parent>/<name>` tag to each named one.
*/
export async function tagUploads (options: TagOptions): Promise<TagSummary> {
const { apiKey, apply, parent, prefix, separator, print } = options
const summary: TagSummary = { named: new Map(), anonymous: 0, unreadable: 0, tagged: 0 }
const fileNames = new Map<string, string[]>()
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<string, string>()
if (apply && names.length) {
const tags = await immich<Array<{ id: string, value: string }>>(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<number> {
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 })
}
+216
View File
@@ -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<Record<string, unknown>> = []) {
let next = 0
const asset = (originalFileName: string, extra: Record<string, unknown> = {}) => ({
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<string, string>()
const tagged = new Set<string>()
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<string, string>)['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> = {}): 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)
})
})