kempo-inventory 0.2.0

package/server/utils/items.js

@@ -0,0 +1,412 @@
+import db from 'kempo/server/db/index.js';
+import { eq, and, or, ilike, sql, desc, asc, inArray } from 'drizzle-orm';
+import crypto from 'crypto';
+import { kempoInventoryItem, kempoInventoryMovement } from '../db/schema.js';
+import { getFields } from './fields.js';
+import { coerceValues, applicableFields, KEY_PATTERN, isEmpty } from './fieldTypes.js';
+import { EVENTS, guard, notify } from './hooks.js';
+import { tidyCategory, categoryKey, MAX_CATEGORY } from './categoryLogic.js';
+import { normalizeTags, tidyTag } from './tags.js';
+import { getAssets, checkAssets } from './media.js';
+import { lockedItemChanges, notYours, ownerLabel } from './ownership.js';
+
+const newId = () => crypto.randomBytes(8).toString('hex');
+
+const toInt = (value, fallback) => {
+  if(isEmpty(value)) return fallback;
+  const n = Number(value);
+  return Number.isInteger(n) ? n : NaN;
+};
+
+const isUniqueViolation = error => (error?.code || error?.cause?.code) === '23505';
+
+/*
+  The shape callers see: core properties plus `fields`, the values of the custom fields.
+*/
+const shape = row => row && ({
+  id: row.id,
+  sku: row.sku,
+  name: row.name,
+  description: row.description,
+  category: row.category,
+  quantity: row.quantity,
+  tags: row.tags ?? [],
+  fields: row.data ?? {},
+  owner: row.owner,
+  created: row.created,
+  updated: row.updated,
+});
+
+/*
+  Returns a map of id -> { id, sku, name } for every item the given items link to, so a client can
+  show "Widget (W-100)" instead of an opaque id. A missing entry means the linked item was deleted.
+*/
+const resolveLinks = async (items, fields) => {
+  const linkKeys = fields.filter(f => f.type === 'item').map(f => f.key);
+  const ids = new Set();
+  for(const item of items) for(const key of linkKeys) if(item.fields[key]) ids.add(item.fields[key]);
+  if(!ids.size) return {};
+  const rows = await db.select({ id: kempoInventoryItem.id, sku: kempoInventoryItem.sku, name: kempoInventoryItem.name })
+    .from(kempoInventoryItem).where(inArray(kempoInventoryItem.id, [...ids]));
+  return Object.fromEntries(rows.map(r => [r.id, r]));
+};
+
+/*
+  Checks every `item` value points at a real item (and not at the item itself).
+*/
+/*
+  `existing` is the item's current values when updating. Files it already holds are not checked
+  again: an item with a photo from a library that is switched off can still be renamed, because
+  only files being *added* need their library to be there.
+*/
+const checkLinks = async (fields, values, ownId = null, existing = {}) => {
+  for(const field of fields.filter(f => f.type === 'item')){
+    const id = values[field.key];
+    if(!id) continue;
+    if(id === ownId) return { code: 400, msg: `${field.label}: an item cannot link to itself` };
+    const [row] = await db.select({ id: kempoInventoryItem.id }).from(kempoInventoryItem).where(eq(kempoInventoryItem.id, id));
+    if(!row) return { code: 400, msg: `${field.label}: the linked item does not exist` };
+  }
+  for(const field of fields.filter(f => f.type === 'media')){
+    const ids = values[field.key];
+    if(!ids?.length) continue;
+    const added = ids.filter(id => !(existing[field.key] ?? []).includes(id));
+    const problem = added.length ? await checkAssets(added, field.label) : null;
+    if(problem) return problem;
+  }
+  return null;
+};
+
+/*
+  Returns a map of id -> a description of each media file the given items hold, for display.
+  Empty when kempo-media is not installed, so a client simply has nothing to show.
+*/
+const resolveMedia = async (items, fields) => {
+  const mediaKeys = fields.filter(f => f.type === 'media').map(f => f.key);
+  const ids = [];
+  for(const item of items) for(const key of mediaKeys) ids.push(...(item.fields[key] ?? []));
+  return getAssets(ids);
+};
+
+const withoutNulls = values => Object.fromEntries(Object.entries(values).filter(([, v]) => v !== null));
+
+/*
+  `ids` fetches exactly those items (any that no longer exist are simply absent), and `owner` keeps
+  the items one owner manages: an extension name, or '' for the ones people manage.
+*/
+export const getItems = async ({ q, category, tag, uncategorised = false, filters = {}, ids, owner, limit = 50, offset = 0 } = {}) => {
+  try {
+    const [fieldsError, fields] = await getFields();
+    if(fieldsError) return [fieldsError, null];
+    const known = new Set(fields.map(f => f.key));
+
+    const conditions = [];
+    if(q){
+      const like = `%${q}%`;
+      conditions.push(or(
+        ilike(kempoInventoryItem.name, like),
+        ilike(kempoInventoryItem.sku, like),
+        ilike(kempoInventoryItem.description, like),
+        ilike(kempoInventoryItem.category, like),
+        sql`${kempoInventoryItem.tags}::text ilike ${like}`,
+        sql`${kempoInventoryItem.data}::text ilike ${like}`
+      ));
+    }
+    /* Categories match ignoring case and spacing, the same way the category list groups them. */
+    if(category){
+      conditions.push(sql`lower(regexp_replace(btrim(${kempoInventoryItem.category}), '[[:space:]]+', ' ', 'g')) = ${categoryKey(category)}`);
+    }
+    /* Exact tags, any number of them: an item must have every one. */
+    for(const wanted of [tag].flat().map(tidyTag).filter(Boolean)){
+      conditions.push(sql`${kempoInventoryItem.tags} @> ${JSON.stringify([wanted])}::jsonb`);
+    }
+    if(uncategorised) conditions.push(sql`btrim(${kempoInventoryItem.category}) = ''`);
+    if(ids !== undefined) conditions.push(inArray(kempoInventoryItem.id, [ids].flat().map(String)));
+    if(owner !== undefined) conditions.push(eq(kempoInventoryItem.owner, String(owner ?? '')));
+    for(const [key, value] of Object.entries(filters || {})){
+      if(!KEY_PATTERN.test(key) || !known.has(key)) return [{ code: 400, msg: `Unknown field "${key}"` }, null];
+      conditions.push(sql`${kempoInventoryItem.data}->>${key} = ${String(value)}`);
+    }
+    const where = conditions.length ? and(...conditions) : undefined;
+
+    const rows = await db.select().from(kempoInventoryItem).where(where)
+      .orderBy(asc(kempoInventoryItem.name), asc(kempoInventoryItem.id)).limit(limit).offset(offset);
+    const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(kempoInventoryItem).where(where);
+    const items = rows.map(shape);
+    return [null, { items, total, linked: await resolveLinks(items, fields), media: await resolveMedia(items, fields) }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve items' }, null];
+  }
+};
+
+export const getItem = async id => {
+  if(!id) return [{ code: 400, msg: 'Item ID is required' }, null];
+  try {
+    const [row] = await db.select().from(kempoInventoryItem).where(eq(kempoInventoryItem.id, id));
+    if(!row) return [{ code: 404, msg: 'Item not found' }, null];
+    return [null, shape(row)];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve item' }, null];
+  }
+};
+
+export const getItemBySku = async sku => {
+  if(!sku) return [{ code: 400, msg: 'SKU is required' }, null];
+  try {
+    const [row] = await db.select().from(kempoInventoryItem).where(eq(kempoInventoryItem.sku, sku));
+    if(!row) return [{ code: 404, msg: 'Item not found' }, null];
+    return [null, shape(row)];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve item' }, null];
+  }
+};
+
+/*
+  Resolves link ids for a single item (see resolveLinks).
+*/
+export const getLinked = async items => {
+  const [error, fields] = await getFields();
+  if(error) return [error, null];
+  try {
+    return [null, await resolveLinks(Array.isArray(items) ? items : [items], fields)];
+  } catch {
+    return [{ code: 500, msg: 'Failed to resolve linked items' }, null];
+  }
+};
+
+/*
+  Resolves media values to display descriptions (see resolveMedia).
+*/
+export const getMedia = async items => {
+  const [error, fields] = await getFields();
+  if(error) return [error, null];
+  try {
+    return [null, await resolveMedia(Array.isArray(items) ? items : [items], fields)];
+  } catch {
+    return [{ code: 500, msg: 'Failed to resolve media' }, null];
+  }
+};
+
+/*
+  `owner` (an extension name, from the server SDK only) marks the item as that extension's: see
+  ownership.js for what that protects. It cannot be changed afterwards and is not part of the draft.
+*/
+export const createItem = async ({ sku, name, description = '', category = '', tags = [], quantity, fields: values = {}, userId = '' } = {}, { owner = '' } = {}) => {
+  /*
+    The draft is what a before_create hook sees and may edit: it can fill in or change any
+    property, or throw { code, msg } to refuse. Everything is validated after the hooks have run,
+    so a hook cannot smuggle in a value that would not otherwise be accepted.
+  */
+  const draft = { sku, name, description, category, tags, quantity, fields: { ...values } };
+  const refused = await guard(EVENTS.itemBeforeCreate, { draft, userId, actor: owner });
+  if(refused) return [refused, null];
+
+  const cleanSku = String(draft.sku ?? '').trim();
+  const cleanName = String(draft.name ?? '').trim();
+  if(!cleanSku) return [{ code: 400, msg: 'SKU is required' }, null];
+  if(!cleanName) return [{ code: 400, msg: 'Name is required' }, null];
+  const cleanCategory = tidyCategory(draft.category);
+  if(cleanCategory.length > MAX_CATEGORY) return [{ code: 400, msg: `Category must be ${MAX_CATEGORY} characters or fewer` }, null];
+  const [tagsError, cleanTags] = normalizeTags(draft.tags);
+  if(tagsError) return [tagsError, null];
+  const qty = toInt(draft.quantity, 0);
+  if(Number.isNaN(qty) || qty < 0) return [{ code: 400, msg: 'Quantity must be a non-negative whole number' }, null];
+
+  const [fieldsError, fields] = await getFields();
+  if(fieldsError) return [fieldsError, null];
+  const [invalid, coerced] = coerceValues(applicableFields(fields, cleanCategory), draft.fields ?? {});
+  if(invalid) return [invalid, null];
+  const linkError = await checkLinks(fields, coerced);
+  if(linkError) return [linkError, null];
+
+  const now = new Date();
+  try {
+    const row = await db.transaction(async tx => {
+      const [created] = await tx.insert(kempoInventoryItem).values({
+        id: newId(), sku: cleanSku, name: cleanName, description: String(draft.description ?? '').trim(), category: cleanCategory, tags: cleanTags,
+        quantity: qty, data: withoutNulls(coerced), owner, created: now, updated: now,
+      }).returning();
+      if(qty > 0){
+        await tx.insert(kempoInventoryMovement).values({
+          id: newId(), itemId: created.id, delta: qty, quantityAfter: qty,
+          reason: 'initial', note: 'Initial stock', userId, created: now,
+        });
+      }
+      return created;
+    });
+    const item = shape(row);
+    await notify(EVENTS.itemCreated, { item, userId, actor: owner });
+    return [null, item];
+  } catch(error) {
+    if(isUniqueViolation(error)) return [{ code: 409, msg: 'An item with that SKU already exists' }, null];
+    return [{ code: 500, msg: 'Failed to create item' }, null];
+  }
+};
+
+/*
+  Updates sku, name, description and custom field values. Quantity is not editable here: it only
+  changes through adjustStock, which keeps the movement history honest.
+*/
+export const updateItem = async (id, { sku, name, description, category, tags, fields: values, userId = '' } = {}, { owner = '' } = {}) => {
+  const [lookupError, existing] = await getItem(id);
+  if(lookupError) return [lookupError, null];
+
+  const changes = {};
+  if(sku !== undefined) changes.sku = sku;
+  if(name !== undefined) changes.name = name;
+  if(description !== undefined) changes.description = description;
+  if(category !== undefined) changes.category = category;
+  if(tags !== undefined) changes.tags = tags;
+  if(values !== undefined) changes.fields = { ...values };
+
+  const refused = await guard(EVENTS.itemBeforeUpdate, { item: existing, changes, userId, actor: owner });
+  if(refused) return [refused, null];
+
+  /* After the guards, so a hook cannot edit its way past it. */
+  const locked = lockedItemChanges(existing, changes, owner);
+  if(locked.length) return [{ code: 403, msg: `${locked.join(', ')} can only be changed by ${ownerLabel(existing.owner)}` }, null];
+
+  const updates = {};
+  if(changes.sku !== undefined){
+    updates.sku = String(changes.sku).trim();
+    if(!updates.sku) return [{ code: 400, msg: 'SKU cannot be empty' }, null];
+  }
+  if(changes.name !== undefined){
+    updates.name = String(changes.name).trim();
+    if(!updates.name) return [{ code: 400, msg: 'Name cannot be empty' }, null];
+  }
+  if(changes.description !== undefined) updates.description = String(changes.description).trim();
+  if(changes.category !== undefined){
+    updates.category = tidyCategory(changes.category);
+    if(updates.category.length > MAX_CATEGORY) return [{ code: 400, msg: `Category must be ${MAX_CATEGORY} characters or fewer` }, null];
+  }
+
+  if(changes.tags !== undefined){
+    const [tagsError, cleanTags] = normalizeTags(changes.tags);
+    if(tagsError) return [tagsError, null];
+    updates.tags = cleanTags;
+  }
+
+  if(changes.fields !== undefined){
+    const [fieldsError, fields] = await getFields();
+    if(fieldsError) return [fieldsError, null];
+    /* Only the fields of the category the item will be in. Values it holds for others are kept, just not shown. */
+    const [invalid, coerced] = coerceValues(applicableFields(fields, updates.category ?? existing.category), changes.fields, { partial: true });
+    if(invalid) return [invalid, null];
+    const linkError = await checkLinks(fields, coerced, id, existing.fields);
+    if(linkError) return [linkError, null];
+    updates.data = withoutNulls({ ...existing.fields, ...coerced });
+    for(const [key, value] of Object.entries(coerced)) if(value === null) delete updates.data[key];
+  }
+  if(!Object.keys(updates).length) return [{ code: 400, msg: 'No changes provided' }, null];
+  updates.updated = new Date();
+
+  try {
+    const [row] = await db.update(kempoInventoryItem).set(updates).where(eq(kempoInventoryItem.id, id)).returning();
+    if(!row) return [{ code: 404, msg: 'Item not found' }, null];
+    const item = shape(row);
+    await notify(EVENTS.itemUpdated, { item, previous: existing, userId, actor: owner });
+    return [null, item];
+  } catch(error) {
+    if(isUniqueViolation(error)) return [{ code: 409, msg: 'An item with that SKU already exists' }, null];
+    return [{ code: 500, msg: 'Failed to update item' }, null];
+  }
+};
+
+export const deleteItem = async (id, { userId = '', owner = '' } = {}) => {
+  const [lookupError, existing] = await getItem(id);
+  if(lookupError) return [lookupError, null];
+  if(existing.owner !== owner) return [notYours('item', existing, owner), null];
+
+  const refused = await guard(EVENTS.itemBeforeDelete, { item: existing, userId, actor: owner });
+  if(refused) return [refused, null];
+
+  try {
+    const deleted = await db.transaction(async tx => {
+      const rows = await tx.delete(kempoInventoryItem).where(eq(kempoInventoryItem.id, id)).returning();
+      if(rows.length) await tx.delete(kempoInventoryMovement).where(eq(kempoInventoryMovement.itemId, id));
+      return rows.length;
+    });
+    if(!deleted) return [{ code: 404, msg: 'Item not found' }, null];
+    await notify(EVENTS.itemDeleted, { item: existing, userId, actor: owner });
+    return [null, { success: true }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to delete item' }, null];
+  }
+};
+
+/*
+  Atomic: the quantity changes in a single UPDATE guarded against going negative,
+  so concurrent adjustments cannot oversell.
+*/
+/* Anyone may adjust stock, owned item or not; `owner` only tells hooks which extension did it. */
+export const adjustStock = async (id, { delta, reason = 'adjustment', note = '', userId = '', owner = '' } = {}) => {
+  const [lookupError, existing] = await getItem(id);
+  if(lookupError) return [lookupError, null];
+
+  const draft = { delta, reason, note };
+  const refused = await guard(EVENTS.stockBeforeAdjust, { item: existing, draft, userId, actor: owner });
+  if(refused) return [refused, null];
+
+  const change = toInt(draft.delta, NaN);
+  if(Number.isNaN(change) || change === 0) return [{ code: 400, msg: 'delta must be a non-zero whole number' }, null];
+
+  try {
+    const result = await db.transaction(async tx => {
+      const [row] = await tx.update(kempoInventoryItem)
+        .set({ quantity: sql`${kempoInventoryItem.quantity} + ${change}`, updated: new Date() })
+        .where(and(eq(kempoInventoryItem.id, id), sql`${kempoInventoryItem.quantity} + ${change} >= 0`))
+        .returning();
+      if(!row) return null;
+      const [movement] = await tx.insert(kempoInventoryMovement).values({
+        id: newId(), itemId: id, delta: change, quantityAfter: row.quantity,
+        reason: String(draft.reason || 'adjustment'), note: String(draft.note || ''), userId, created: new Date(),
+      }).returning();
+      return { row, movement };
+    });
+    if(!result) return [{ code: 409, msg: 'Insufficient stock' }, null];
+
+    const item = shape(result.row);
+    await notify(EVENTS.stockAdjusted, {
+      item, previousQuantity: item.quantity - change, delta: change,
+      reason: result.movement.reason, note: result.movement.note, movement: result.movement, userId, actor: owner,
+    });
+    return [null, item];
+  } catch {
+    return [{ code: 500, msg: 'Failed to adjust stock' }, null];
+  }
+};
+
+export const getMovements = async ({ itemId, limit = 50, offset = 0 } = {}) => {
+  try {
+    const where = itemId ? eq(kempoInventoryMovement.itemId, itemId) : undefined;
+    const movements = await db.select().from(kempoInventoryMovement).where(where)
+      .orderBy(desc(kempoInventoryMovement.created), desc(kempoInventoryMovement.id)).limit(limit).offset(offset);
+    return [null, movements];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve movements' }, null];
+  }
+};
+
+/*
+  For an extension's uninstall.js: deletes every item it owns, with their history. With `release`
+  the items are kept and handed back to the people who manage the inventory instead, which is the
+  right choice when they hold real stock.
+*/
+export const unregisterItems = async (owner, { release = false } = {}) => {
+  if(!owner) return [{ code: 400, msg: 'An owner (your extension name) is required' }, null];
+  try {
+    if(release){
+      const rows = await db.update(kempoInventoryItem).set({ owner: '' }).where(eq(kempoInventoryItem.owner, owner)).returning({ id: kempoInventoryItem.id });
+      return [null, { released: rows.length }];
+    }
+    const rows = await db.select({ id: kempoInventoryItem.id }).from(kempoInventoryItem).where(eq(kempoInventoryItem.owner, owner));
+    for(const { id } of rows){
+      const [error] = await deleteItem(id, { owner });
+      if(error) return [error, null];
+    }
+    return [null, { removed: rows.length }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to remove the items' }, null];
+  }
+};

package/server/utils/media.js

@@ -0,0 +1,245 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { getExtension, getSetting, triggerHook } from 'kempo/server/sdk.js';
+import { extensionOf, safeFileName } from './mediaSafety.js';
+import { DEFAULT_RATIOS, resolveRatio } from './ratio.js';
+import { parseMediaId, filesId } from './fieldTypes.js';
+
+/*
+  Where item photos and files live. Three optional extensions can take part, and inventory works
+  the same with none of them installed:
+
+    kempo-media   a media library with its own image thumbnails
+    kempo-files   a private file library; uploads need a signed-in user with files:download to view
+    kempo-thumbs  generates thumbnails for kempo-files (images, and frames from video and audio)
+
+  Nothing here imports them up front. Each is loaded on demand and only counts as available when it
+  is both installed as a package and enabled in kempo. Because kempo-thumbs only works on
+  kempo-files, it is only ever used for files stored there.
+
+  A stored value says where it lives: a bare id is a kempo-media asset, "files:<id>" is a
+  kempo-files file. So values from either place keep resolving, whichever is used for new uploads.
+*/
+const loaders = {
+  'kempo-media': () => import('kempo-media/sdk'),
+  'kempo-files': () => import('kempo-files/sdk'),
+  'kempo-thumbs': () => import('kempo-thumbs/sdk'),
+};
+
+const loaded = {};
+
+const load = async name => loaded[name] ??= await loaders[name]().catch(() => null);
+
+const available = async name => {
+  const [error, extension] = await getExtension({ name });
+  if(error || !extension?.enabled) return false;
+  return Boolean(await load(name));
+};
+
+/*
+  What can be used right now. `thumbs` is only true alongside `files`, since that is the only
+  place it can generate thumbnails.
+*/
+export const providers = async () => {
+  const [media, files, thumbs] = await Promise.all([available('kempo-media'), available('kempo-files'), available('kempo-thumbs')]);
+  return { media, files, thumbs: files && thumbs };
+};
+
+export const mediaAvailable = async () => {
+  const found = await providers();
+  return found.media || found.files;
+};
+
+/*
+  Which provider new uploads go to: 'media', 'files' or null when neither is installed.
+
+  The `media_provider` setting can force one ('kempo-media' or 'kempo-files'). Left on 'auto',
+  kempo-files wins when kempo-thumbs is there to thumbnail it, because that is a better result than
+  kempo-media's; otherwise kempo-media wins, since a bare kempo-files has no thumbnails at all.
+*/
+export const uploadProvider = async () => {
+  const found = await providers();
+  const [, choice] = await getSetting('kempo-inventory', 'media_provider', 'auto');
+  if(choice === 'kempo-media' && found.media) return 'media';
+  if(choice === 'kempo-files' && found.files) return 'files';
+  if(found.files && found.thumbs) return 'files';
+  if(found.media) return 'media';
+  if(found.files) return 'files';
+  return null;
+};
+
+/*
+  The aspect ratios images are shown at, as CSS ("4 / 3"): { category, item }. They come from the
+  `category_image_ratio` and `item_image_ratio` settings; a blank or invalid one falls back to the default.
+*/
+export const getImageRatios = async () => {
+  const [, category] = await getSetting('kempo-inventory', 'category_image_ratio', DEFAULT_RATIOS.category);
+  const [, item] = await getSetting('kempo-inventory', 'item_image_ratio', DEFAULT_RATIOS.item);
+  return { category: resolveRatio(category, 'category'), item: resolveRatio(item, 'item') };
+};
+
+/* Whether photos uploaded to kempo-files are made public, so people who can only read the inventory can see them. */
+export const publicPhotos = async () => {
+  const [, value] = await getSetting('kempo-inventory', 'public_photos', true);
+  return value !== false && value !== 'false';
+};
+
+export const capabilities = async () => {
+  const found = await providers();
+  return { media: found.media || found.files, providers: found, upload: await uploadProvider(), publicFiles: await publicPhotos() };
+};
+
+/*
+  The smallest thumbnail that is ready, preferring the one labelled "sm".
+*/
+const pickThumbnail = rows => {
+  const ready = (rows ?? []).filter(row => row.status === 'ready' && row.url);
+  return (ready.find(row => row.label === 'sm') ?? ready[0])?.url ?? null;
+};
+
+const describeMedia = asset => ({
+  id: asset.id,
+  kind: asset.kind,
+  name: asset.originalName,
+  alt: asset.altText,
+  path: `/${asset.path}`,
+  thumbnail: asset.thumbnailPath ? `/${asset.thumbnailPath}` : null,
+  width: asset.width,
+  height: asset.height,
+});
+
+const describeFile = (file, thumbnails) => ({
+  id: filesId(file.id),
+  kind: file.kind,
+  name: file.name,
+  alt: file.altText,
+  path: file.alias ? `/${file.alias}` : `/kempo-files/api/files/${file.id}`,
+  thumbnail: pickThumbnail(thumbnails),
+  width: null,
+  height: null,
+});
+
+/*
+  Looks up stored values. Returns a map of stored id -> a small description of each file; an id
+  with no entry means it was deleted from its library, or its library is not available right now.
+*/
+export const getAssets = async ids => {
+  const wanted = [...new Set(ids)];
+  if(!wanted.length) return {};
+  const found = await providers();
+  const parsed = wanted.map(id => ({ id, ...parseMediaId(id) }));
+  const result = {};
+
+  const mediaIds = parsed.filter(p => p.provider === 'media');
+  if(found.media && mediaIds.length){
+    const { getMediaAsset } = await load('kempo-media');
+    const lookups = await Promise.all(mediaIds.map(async p => [p.id, await getMediaAsset(p.rawId)]));
+    for(const [id, [error, asset]] of lookups) if(!error) result[id] = describeMedia(asset);
+  }
+
+  const fileIds = parsed.filter(p => p.provider === 'files');
+  if(found.files && fileIds.length){
+    const { getFile } = await load('kempo-files');
+    const lookups = await Promise.all(fileIds.map(async p => [p, await getFile(p.rawId)]));
+
+    let thumbnails = {};
+    if(found.thumbs){
+      const { thumbnailsForMany } = await load('kempo-thumbs');
+      const [, data] = await thumbnailsForMany(fileIds.map(p => p.rawId));
+      thumbnails = data?.bySource ?? {};
+    }
+    for(const [p, [error, file]] of lookups) if(!error) result[p.id] = describeFile(file, thumbnails[p.rawId]);
+  }
+  return result;
+};
+
+/*
+  The bytes of a stored file, for an export: [null, { name, kind, alt, bytes }], or an error when it is
+  gone from its library (or the library is not installed).
+*/
+export const readMedia = async storedId => {
+  const { provider, rawId } = parseMediaId(storedId);
+  const found = await providers();
+  try {
+    if(provider === 'files' && found.files){
+      const { getFile, filePath } = await load('kempo-files');
+      const [error, file] = await getFile(rawId);
+      if(error) return [error, null];
+      const [pathError, absolute] = await filePath(file);
+      if(pathError) return [pathError, null];
+      return [null, { name: file.name, kind: file.kind, alt: file.altText ?? '', bytes: await readFile(absolute) }];
+    }
+    if(provider === 'media' && found.media){
+      const { getMediaAsset } = await load('kempo-media');
+      const [error, asset] = await getMediaAsset(rawId);
+      if(error) return [error, null];
+      return [null, { name: asset.originalName, kind: asset.kind, alt: asset.altText ?? '', bytes: await readFile(join(process.cwd(), 'public', asset.path)) }];
+    }
+  } catch {
+    return [{ code: 404, msg: 'The file could not be read' }, null];
+  }
+  return [{ code: 409, msg: 'The library holding this file is not installed' }, null];
+};
+
+const MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', avif: 'image/avif', bmp: 'image/bmp', mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg', m4a: 'audio/mp4', pdf: 'application/pdf' };
+
+/*
+  Stores a file in whichever library new uploads go to (the same choice as an upload from the form), on
+  behalf of `userId`, and resolves to [null, storedId]. The caller is responsible for having checked who
+  may do this and what the file is (see mediaSafety.js); this is only the storing. A name that is taken is
+  retried with a short random suffix, the way the form's uploader does.
+*/
+export const storeMedia = async ({ name, bytes, altText = '', userId }) => {
+  const provider = await uploadProvider();
+  if(!provider) return [{ code: 409, msg: 'Uploading needs the kempo-media or kempo-files extension' }, null];
+  const safe = safeFileName(name);
+  const data = Buffer.from(bytes);
+  const withSuffix = () => safe.replace(/(.[^.]*)?$/, ext => `-${Math.random().toString(36).slice(2, 7)}${ext ?? ''}`);
+  try {
+    if(provider === 'files'){
+      const { storeUpload } = await load('kempo-files');
+      const [, maxMb] = await getSetting('kempo-files', 'max_upload_size_mb', 250);
+      const isPublic = await publicPhotos();
+      let attempt = safe;
+      for(let n = 0; n < 5; n++){
+        const [error, file] = await storeUpload({ name: attempt, data, altText, ownerId: userId, public: isPublic, maxBytes: Number(maxMb) * 1024 * 1024 });
+        if(!error){
+          await triggerHook('file:uploaded', { file });
+          return [null, filesId(file.id)];
+        }
+        if(error.code !== 409) return [error, null];
+        attempt = withSuffix();
+      }
+      return [{ code: 409, msg: 'No free file name could be found' }, null];
+    }
+    const { storeUpload, createMediaAsset } = await load('kempo-media');
+    const [, maxMb] = await getSetting('kempo-media', 'max_upload_size_mb', 250);
+    const [, thumbnailMaxDimension] = await getSetting('kempo-media', 'thumbnail_max_dimension', 480);
+    const [error, asset] = await storeUpload({
+      rootDir: join(process.cwd(), 'public'), filename: safe, data, mimeType: MIME[extensionOf(safe)] ?? 'application/octet-stream',
+      altText, uploadedBy: userId, maxBytes: Number(maxMb) * 1024 * 1024, thumbnailMaxDimension: Number(thumbnailMaxDimension),
+    });
+    if(error) return [error, null];
+    const [recordError, row] = await createMediaAsset(asset);
+    return recordError ? [recordError, null] : [null, row.id];
+  } catch {
+    return [{ code: 500, msg: 'The file could not be stored' }, null];
+  }
+};
+
+/*
+  Returns an { code, msg } for the first id that cannot be used, or null when all can: its library
+  is not installed (409), or it no longer exists (400).
+*/
+export const checkAssets = async (ids, label) => {
+  const found = await providers();
+  for(const id of ids){
+    const { provider } = parseMediaId(id);
+    if(!found[provider]){
+      return { code: 409, msg: `${label}: ${provider === 'files' ? 'kempo-files' : 'kempo-media'} is not installed` };
+    }
+  }
+  const assets = await getAssets(ids);
+  const missing = ids.find(id => !assets[id]);
+  return missing ? { code: 400, msg: `${label}: a selected file no longer exists in its library` } : null;
+};