kempo-inventory 0.2.0

package/sdk.js

@@ -0,0 +1,65 @@
+/*
+  The server SDK other extensions build on. Every function resolves to [error, result].
+
+  An extension that adds to inventory declares `"dependencies": ["kempo-inventory"]` in its
+  kempo-config.json, registers its fields in install.js, and removes them in uninstall.js:
+
+    import { registerFields } from 'kempo-inventory/sdk';
+    export default async () => {
+      const [error] = await registerFields('my-extension', [
+        { key: 'manufacturer', label: 'Manufacturer', type: 'text' },
+      ]);
+      if(error) throw new Error(error.msg);
+    };
+
+  Fields, categories and items can all be owned. Pass your extension name as `owner` and only you can
+  delete them or change the parts that define them; people keep editing everything else (stock
+  included) in the admin. Owner is never read from an HTTP request, only from these server calls:
+
+    registerCategory(owner, { name, description })       registerField(owner, { ..., category })
+    createItem(data, { owner })                          updateItem(id, data, { owner })
+    deleteItem(id, { owner })                            saveCategory(name, changes, { owner })
+    unregisterItems(owner, { release }) / unregisterCategories(owner) / unregisterFields(owner)
+*/
+export {
+  getItems,
+  getItem,
+  getItemBySku,
+  getLinked,
+  getMedia,
+  createItem,
+  updateItem,
+  deleteItem,
+  unregisterItems,
+  adjustStock,
+  getMovements,
+} from './server/utils/items.js';
+
+export {
+  getFields,
+  getField,
+  createField,
+  updateField,
+  deleteField,
+  registerField,
+  registerFields,
+  unregisterFields,
+} from './server/utils/fields.js';
+
+export { getSuggestions } from './server/utils/suggestions.js';
+export { buildExport, importData } from './server/utils/importExport.js';
+export { previewImport, applyImport } from './server/utils/importFile.js';
+export { buildZip } from './server/utils/zip.js';
+export { getTags } from './server/utils/tagList.js';
+export { normalizeTags, MAX_TAG, MAX_TAGS } from './server/utils/tags.js';
+export {
+  getCategories,
+  saveCategory,
+  setCategoryImage,
+  deleteCategory,
+  registerCategory,
+  unregisterCategories,
+} from './server/utils/categories.js';
+export { mediaAvailable, uploadProvider } from './server/utils/media.js';
+export { FIELD_TYPES } from './server/utils/fieldTypes.js';
+export { EVENTS } from './server/utils/events.js';

package/server/db/schema.js

@@ -0,0 +1,74 @@
+import { pgTable, text, timestamp, integer, boolean, jsonb, index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+/*
+  An item has only the core columns. Everything else lives in `data`, keyed by the `key` of a
+  kempoInventoryField row, so fields can be added and removed without touching the schema.
+*/
+export const kempoInventoryItem = pgTable('kempoInventoryItem', {
+  id: text('id').primaryKey(),
+  sku: text('sku').notNull(),
+  name: text('name').notNull(),
+  description: text('description').notNull().default(''),
+  category: text('category').notNull().default(''), // built in and optional; '' means uncategorised
+  quantity: integer('quantity').notNull().default(0),
+  tags: jsonb('tags').notNull().default([]), // built in: short lower-case labels search finds
+  data: jsonb('data').notNull().default({}),
+  owner: text('owner').notNull().default(''), // '' for items people manage, or the extension that created it; see ownership.js
+  created: timestamp('created').notNull(),
+  updated: timestamp('updated').notNull(),
+}, table => [uniqueIndex('kempoInventoryItemSkuIdx').on(table.sku), index('kempoInventoryItemOwnerIdx').on(table.owner)]);
+
+/*
+  `owner` is '' for fields a user created in the admin, or the name of the extension that
+  registered it. Only the owner can delete a field or change what it holds.
+
+  `category` scopes a field: '' is the default scope, shown on every item, and a category key makes
+  it appear only on items in that category. A key is unique within its scope, and a category cannot
+  reuse a key the default scope has, because both would be stored under the same name on its items.
+*/
+export const kempoInventoryField = pgTable('kempoInventoryField', {
+  id: text('id').primaryKey(),
+  key: text('key').notNull(),
+  label: text('label').notNull(),
+  type: text('type').notNull(),
+  description: text('description').notNull().default(''),
+  required: boolean('required').notNull().default(false),
+  listed: boolean('listed').notNull().default(true),
+  suggest: boolean('suggest').notNull().default(false), // text fields: offer values already used on other items
+  options: jsonb('options').notNull().default([]),
+  owner: text('owner').notNull().default(''),
+  position: integer('position').notNull().default(0),
+  imageRatio: text('imageRatio').notNull().default(''), // media fields: the shape photos are cropped to, e.g. '1 / 1'; '' = any shape
+  imageMax: integer('imageMax').notNull().default(0),   // media fields: photos are kept within this many pixels on a side; 0 = no limit
+  category: text('category').notNull().default(''), // '' = every item; otherwise the key of the one category it belongs to
+  created: timestamp('created').notNull(),
+}, table => [uniqueIndex('kempoInventoryFieldKeyIdx').on(table.category, table.key)]);
+
+export const kempoInventoryMovement = pgTable('kempoInventoryMovement', {
+  id: text('id').primaryKey(),
+  itemId: text('itemId').notNull(),
+  delta: integer('delta').notNull(),
+  quantityAfter: integer('quantityAfter').notNull(),
+  reason: text('reason').notNull().default('adjustment'),
+  note: text('note').notNull().default(''),
+  userId: text('userId').notNull().default(''),
+  created: timestamp('created').notNull(),
+}, table => [index('kempoInventoryMovementItemIdx').on(table.itemId)]);
+
+/*
+  Extra information about a category (currently its image), matched to items by `key`: the
+  category name lower-cased with its spacing tidied, so "Paint" and "paint" are one category. Items
+  do not point at these; they keep their plain text field. A category with no record still exists,
+  it just has no image.
+*/
+export const kempoInventoryCategory = pgTable('kempoInventoryCategory', {
+  id: text('id').primaryKey(),
+  key: text('key').notNull(),
+  name: text('name').notNull(),
+  image: text('image'), // a stored media id, as held by a media field
+  description: text('description').notNull().default(''),
+  tags: jsonb('tags').notNull().default([]),
+  owner: text('owner').notNull().default(''), // '' for categories people manage, or the extension that registered it
+  created: timestamp('created').notNull(),
+  updated: timestamp('updated').notNull(),
+}, table => [uniqueIndex('kempoInventoryCategoryKeyIdx').on(table.key)]);

package/server/utils/access.js

@@ -0,0 +1,43 @@
+import { currentUserHasPermission, getSession, getSetting } from 'kempo/server/sdk.js';
+import authorize from './authorize.js';
+
+/*
+  Who may read the inventory, and whether they may see stock counts.
+
+  Normally reading needs the `items:read` permission. With the `public_read` setting on, anyone can
+  read, signed in or not, so the inventory can be shared as a catalogue. Either way, **stock counts
+  are only for people who manage stock**: callers without `stock:adjust` or `items:update` get items
+  with no `quantity` and no stock history.
+
+  Resolves to [null, { userId, canSeeStock, anonymous }] or [{ code, msg }, null].
+*/
+export const publicReadEnabled = async () => {
+  const [, value] = await getSetting('kempo-inventory', 'public_read', false);
+  return value === true || value === 'true';
+};
+
+const holds = async (token, permission) => {
+  const [, allowed] = await currentUserHasPermission(token, `kempo-inventory:${permission}`);
+  return Boolean(allowed);
+};
+
+export const authorizeRead = async request => {
+  const token = request.cookies?.session_token;
+  const [error, auth] = await authorize(request, 'items:read');
+  if(!error){
+    const canSeeStock = (await holds(token, 'stock:adjust')) || (await holds(token, 'items:update'));
+    return [null, { userId: auth.userId, canSeeStock, anonymous: false }];
+  }
+  if(await publicReadEnabled()){
+    const [sessionError, session] = token ? await getSession({ token }) : [true, null];
+    return [null, { userId: !sessionError && session?.user ? session.user.id : null, canSeeStock: false, anonymous: true }];
+  }
+  return [error, null];
+};
+
+/* An item as the caller may see it: no stock count unless they manage stock. */
+export const forCaller = (item, access) => {
+  if(access.canSeeStock) return item;
+  const { quantity, ...rest } = item;
+  return rest;
+};

package/server/utils/authorize.js

@@ -0,0 +1,13 @@
+import { currentUserHasPermission, getSession } from 'kempo/server/sdk.js';
+
+/*
+  Resolves to [null, { userId }] when the request's user holds the permission, or [{ code, msg }, null].
+*/
+export default async (request, permission) => {
+  const token = request.cookies.session_token;
+  const [sessionError, session] = await getSession({ token });
+  if(sessionError || !session?.user) return [{ code: 401, msg: 'Authentication required' }, null];
+  const [, allowed] = await currentUserHasPermission(token, `kempo-inventory:${permission}`);
+  if(!allowed) return [{ code: 403, msg: 'Insufficient permissions' }, null];
+  return [null, { userId: session.user.id }];
+};

package/server/utils/categories.js

@@ -0,0 +1,267 @@
+import db from 'kempo/server/db/index.js';
+import { sql, eq } from 'drizzle-orm';
+import crypto from 'crypto';
+import { kempoInventoryItem, kempoInventoryCategory, kempoInventoryField } from '../db/schema.js';
+import { normalizeTags, tidyTag } from './tags.js';
+import { categoryKey, groupCategories, tidyCategory, MAX_CATEGORY, MAX_DESCRIPTION } from './categoryLogic.js';
+import { coerceValue } from './fieldTypes.js';
+import { getAssets, checkAssets } from './media.js';
+import { EVENTS, guard, notify } from './hooks.js';
+import { blockingOwner, mayManage, notYours, ownerLabel } from './ownership.js';
+
+/* Matches an item's category to a key the same way the category list groups them. */
+const sameCategory = key => sql`lower(regexp_replace(btrim(${kempoInventoryItem.category}), '[[:space:]]+', ' ', 'g')) = ${key}`;
+
+const countItems = async key => {
+  const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(kempoInventoryItem).where(sameCategory(key));
+  return total;
+};
+
+/*
+  The categories, each with how many items it has, its image (if any) and description:
+    { categories: [{ name, key, count, image, description }], uncategorised }
+
+  A category is the value of an item's built-in `category` property, so there is no list to
+  maintain: they are the distinct values, merged ignoring case and spacing. By default only
+  categories some item has are returned; `includeEmpty` also returns ones that exist only as a
+  record (created in the admin before any item uses them). `uncategorised` counts items with none.
+*/
+export const getCategories = async ({ includeEmpty = false, q = '', tag = '', owner } = {}) => {
+  try {
+    const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(kempoInventoryItem);
+
+    const rows = [...await db.execute(sql`
+      SELECT ${kempoInventoryItem.category} AS value, count(*)::int AS uses
+      FROM ${kempoInventoryItem}
+      WHERE btrim(${kempoInventoryItem.category}) <> ''
+      GROUP BY 1`)];
+    const records = await db.select().from(kempoInventoryCategory);
+
+    const grouped = groupCategories(rows, records, { includeEmpty });
+    const assets = await getAssets(grouped.map(c => c.image).filter(Boolean));
+    const fieldRows = [...await db.execute(sql`SELECT ${kempoInventoryField.category} AS key, count(*)::int AS total FROM ${kempoInventoryField} WHERE ${kempoInventoryField.category} <> '' GROUP BY 1`)];
+    const fieldCounts = new Map(fieldRows.map(r => [r.key, r.total]));
+    let categories = grouped.map(c => ({ ...c, fields: fieldCounts.get(c.key) ?? 0, image: c.image ? assets[c.image] ?? null : null }));
+
+    /* `q` finds categories by name, description or tag; `tag` keeps those with every tag named (exact). */
+    const term = String(q ?? '').trim().toLowerCase();
+    if(term) categories = categories.filter(c => [c.name, c.description, ...c.tags].some(text => String(text).toLowerCase().includes(term)));
+    if(owner !== undefined) categories = categories.filter(c => c.owner === String(owner ?? ''));
+    const wanted = [tag].flat().map(tidyTag).filter(Boolean);
+    if(wanted.length) categories = categories.filter(c => wanted.every(t => c.tags.includes(t)));
+    const categorised = rows.reduce((sum, r) => sum + r.uses, 0);
+
+    const defaultFields = [...await db.execute(sql`SELECT count(*)::int AS total FROM ${kempoInventoryField} WHERE ${kempoInventoryField.category} = ''`)][0].total;
+    return [null, { categories, uncategorised: Math.max(0, total - categorised), defaultFields }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve categories' }, null];
+  }
+};
+
+/*
+  Creates or updates a category, by name (any spelling of it finds the same one). Only what is
+  passed changes:
+
+    saveCategory('Paint', { description: 'Hobby paints' })
+    saveCategory('Paint', { image: 'files:0123456789abcdef' })     // a stored media id; null clears it
+    saveCategory('Paint', { newName: 'Paints' })                   // renames, and updates the items
+
+  Renaming changes the category on every item that has it. Renaming onto a name that already exists
+  merges the two: the items join the existing category, which keeps its own image and description
+  unless new ones are given. Resolves to [null, { name, key, image, description, tags, owner, moved }]
+  where `moved` is how many items were renamed.
+
+  A category with an `owner` (see registerCategory) can only be renamed, or merged into or out of,
+  by that owner; anyone can still change its image, description and tags. `owner` here is the
+  extension making the call ('' for a person), and a category created by this call belongs to it.
+*/
+export const saveCategory = async (name, { newName, image, description, tags } = {}, { userId = '', owner = '' } = {}) => {
+  const displayName = tidyCategory(name);
+  const key = categoryKey(displayName);
+  if(!key) return [{ code: 400, msg: 'A category name is required' }, null];
+
+  const changes = {};
+  if(description !== undefined){
+    const text = String(description ?? '').trim();
+    if(text.length > MAX_DESCRIPTION) return [{ code: 400, msg: `A description must be ${MAX_DESCRIPTION} characters or fewer` }, null];
+    changes.description = text;
+  }
+  if(tags !== undefined){
+    const [tagsError, cleanTags] = normalizeTags(tags);
+    if(tagsError) return [tagsError, null];
+    changes.tags = cleanTags;
+  }
+  if(image !== undefined){
+    if(image === null || image === ''){
+      changes.image = null;
+    } else {
+      const [invalid, ids] = coerceValue({ type: 'media', label: 'Image' }, [image]);
+      if(invalid) return [invalid, null];
+      const problem = await checkAssets([ids[0]], 'Image');
+      if(problem) return [problem, null];
+      changes.image = ids[0];
+    }
+  }
+
+  let targetName = displayName;
+  if(newName !== undefined){
+    targetName = tidyCategory(newName);
+    if(!targetName) return [{ code: 400, msg: 'A category needs a name' }, null];
+    if(targetName.length > MAX_CATEGORY) return [{ code: 400, msg: `A category name must be ${MAX_CATEGORY} characters or fewer` }, null];
+  }
+  const targetKey = categoryKey(targetName);
+  const renaming = targetName !== displayName;
+
+  const refused = await guard(EVENTS.categoryBeforeUpdate, { name: displayName, newName: renaming ? targetName : null, changes, userId, actor: owner });
+  if(refused) return [refused, null];
+
+  try {
+    /* A category's own fields go with it when it is renamed. Merging two that both define a key would lose one. */
+    if(targetKey !== key){
+      const clash = [...await db.execute(sql`
+        SELECT a."key" FROM ${kempoInventoryField} a JOIN ${kempoInventoryField} b ON a."key" = b."key"
+        WHERE a."category" = ${key} AND b."category" = ${targetKey} LIMIT 1`)];
+      if(clash.length) return [{ code: 409, msg: `Both categories have a field with the key "${clash[0].key}". Delete or change one first` }, null];
+    }
+
+    const now = new Date();
+    const outcome = await db.transaction(async tx => {
+      const [source] = await tx.select().from(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, key));
+      const [target] = targetKey === key ? [source] : await tx.select().from(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, targetKey));
+
+      /*
+        Renaming rewrites the category on every item in it and moves its fields, and merging does the
+        same to the other category's, so neither may touch what another extension owns.
+      */
+      if(renaming || targetKey !== key){
+        if(!mayManage(source, owner)) return { refused: notYours('category', source, owner) };
+        if(!mayManage(target, owner)) return { refused: notYours('category', target, owner) };
+        const keys = [...new Set([key, targetKey])];
+        const holders = [...await tx.execute(sql`
+          SELECT DISTINCT owner FROM (
+            SELECT ${kempoInventoryItem.owner} AS owner FROM ${kempoInventoryItem} WHERE ${sql.join(keys.map(k => sameCategory(k)), sql` OR `)}
+            UNION ALL
+            SELECT ${kempoInventoryField.owner} AS owner FROM ${kempoInventoryField} WHERE ${kempoInventoryField.category} IN (${sql.join(keys.map(k => sql`${k}`), sql`, `)})
+          ) held`)].map(r => r.owner);
+        const blocker = blockingOwner(holders, owner);
+        if(blocker) return { refused: { code: 403, msg: `This category holds items or fields managed by ${ownerLabel(blocker)}, so it cannot be renamed or merged here` } };
+      }
+
+      /* Items first, so a failure leaves the record untouched. Both spellings end up as the new name. */
+      let moved = 0;
+      if(renaming){
+        const rows = await tx.update(kempoInventoryItem)
+          .set({ category: targetName, updated: now })
+          .where(targetKey === key ? sameCategory(key) : sql`${sameCategory(key)} OR ${sameCategory(targetKey)}`)
+          .returning({ id: kempoInventoryItem.id });
+        moved = rows.length;
+      }
+
+      if(targetKey !== key) await tx.update(kempoInventoryField).set({ category: targetKey }).where(eq(kempoInventoryField.category, key));
+
+      /* What the category ends up holding: this call's changes, then the existing record, then the one merged away. */
+      const merged = {
+        image: changes.image !== undefined ? changes.image : (target?.image ?? source?.image ?? null),
+        description: changes.description !== undefined ? changes.description : (target?.description || source?.description || ''),
+        /* Merging two categories keeps the tags of both. */
+        tags: changes.tags !== undefined ? changes.tags : [...new Set([...(target?.tags ?? []), ...(source && source !== target ? source.tags ?? [] : [])])],
+      };
+
+      if(targetKey !== key && source) await tx.delete(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, key));
+
+      let row;
+      if(target){
+        [row] = await tx.update(kempoInventoryCategory).set({ name: targetName, ...merged, updated: now }).where(eq(kempoInventoryCategory.key, targetKey)).returning();
+      } else {
+        [row] = await tx.insert(kempoInventoryCategory)
+          .values({ id: crypto.randomBytes(8).toString('hex'), key: targetKey, name: targetName, ...merged, owner, created: now, updated: now })
+          .returning();
+      }
+      return { row, moved, previous: source ?? null };
+    });
+    if(outcome.refused) return [outcome.refused, null];
+
+    await notify(EVENTS.categoryUpdated, { category: outcome.row, previous: outcome.previous, moved: outcome.moved, userId, actor: owner });
+    return [null, { name: outcome.row.name, key: outcome.row.key, image: outcome.row.image, description: outcome.row.description, tags: outcome.row.tags ?? [], owner: outcome.row.owner, moved: outcome.moved }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to save the category' }, null];
+  }
+};
+
+/* Kept for callers that only set a picture. */
+export const setCategoryImage = (name, image = null, options) => saveCategory(name, { image }, options);
+
+/*
+  Deletes a category's record (its image and description). Refused while any item is still in the
+  category, so deleting can never quietly strip categories off items: move or clear those first.
+*/
+export const deleteCategory = async (name, { userId = '', owner = '' } = {}) => {
+  const key = categoryKey(name);
+  if(!key) return [{ code: 400, msg: 'A category name is required' }, null];
+  try {
+    const [record] = await db.select().from(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, key));
+    if(record && !mayManage(record, owner)) return [notYours('category', record, owner), null];
+    const refused = await guard(EVENTS.categoryBeforeDelete, { category: record ?? null, name: tidyCategory(name), userId, actor: owner });
+    if(refused) return [refused, null];
+    const [{ fields }] = await db.select({ fields: sql`count(*)::int` }).from(kempoInventoryField).where(eq(kempoInventoryField.category, key));
+    if(fields) return [{ code: 409, msg: `This category has ${fields} field${fields === 1 ? '' : 's'}. Delete ${fields === 1 ? 'it' : 'them'} first` }, null];
+    const used = await countItems(key);
+    if(used) return [{ code: 409, msg: `${used} item${used === 1 ? ' is' : 's are'} still in this category. Move or clear ${used === 1 ? 'it' : 'them'} first` }, null];
+    const [row] = await db.delete(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, key)).returning();
+    if(!row) return [{ code: 404, msg: 'Category not found' }, null];
+    await notify(EVENTS.categoryDeleted, { category: row, userId, actor: owner });
+    return [null, { success: true }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to delete the category' }, null];
+  }
+};
+
+/*
+  Idempotent: safe to call from an extension's install.js and again on every update. Makes the
+  category a record the extension owns, so people cannot rename or delete it, and refreshes the
+  description, tags and image the owner supplies. Refuses a category people already manage unless
+  `adopt` is set, which takes it over (its items stay as they are, and stay people's).
+
+    registerCategory('kempo-products', { name: 'Finished goods', description: 'Ready to ship' })
+*/
+export const registerCategory = async (owner, { name, description, tags, image } = {}, { adopt = false } = {}) => {
+  if(!owner) return [{ code: 400, msg: 'An owner (your extension name) is required' }, null];
+  const key = categoryKey(name);
+  if(!key) return [{ code: 400, msg: 'A category name is required' }, null];
+  try {
+    const [existing] = await db.select().from(kempoInventoryCategory).where(eq(kempoInventoryCategory.key, key));
+    if(existing && existing.owner !== owner && (existing.owner || !adopt)){
+      return [{ code: 409, msg: `The category "${existing.name}" is already managed by ${ownerLabel(existing.owner)}` }, null];
+    }
+    const [error, saved] = await saveCategory(name, { description, tags, image }, { owner });
+    if(error) return [error, null];
+    if(existing && existing.owner !== owner) await db.update(kempoInventoryCategory).set({ owner }).where(eq(kempoInventoryCategory.key, key));
+    return [null, { ...saved, owner }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to register the category' }, null];
+  }
+};
+
+/*
+  For an extension's uninstall.js, after unregisterItems and unregisterFields. Deletes the
+  categories it registered, except any that items or fields still use: those are handed back to
+  the people who manage the inventory rather than leaving them stranded or stripping their items.
+*/
+export const unregisterCategories = async owner => {
+  if(!owner) return [{ code: 400, msg: 'An owner (your extension name) is required' }, null];
+  try {
+    const rows = await db.select().from(kempoInventoryCategory).where(eq(kempoInventoryCategory.owner, owner));
+    let removed = 0;
+    let released = 0;
+    for(const row of rows){
+      const [error] = await deleteCategory(row.name, { owner });
+      if(!error){ removed++; continue; }
+      if(error.code !== 409) return [error, null];
+      await db.update(kempoInventoryCategory).set({ owner: '' }).where(eq(kempoInventoryCategory.key, row.key));
+      released++;
+    }
+    return [null, { removed, released }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to remove the categories' }, null];
+  }
+};

package/server/utils/categoryLogic.js

@@ -0,0 +1,54 @@
+/*
+  Pure helpers for categories, with no database access so they can be tested without a server.
+
+  An item's category is a built-in text property (like its SKU), not something items point at. What
+  this extension adds is a small record per category name that can hold an image and a description,
+  matched to items by a normalised key, so "Paint", "paint" and " Paint " are one category.
+*/
+
+export const MAX_CATEGORY = 100;
+export const MAX_DESCRIPTION = 500;
+
+/* How a category is stored: trimmed, with runs of whitespace collapsed to one space. */
+export const tidyCategory = name => String(name ?? '').trim().replace(/\s+/g, ' ');
+
+export const categoryKey = name => String(name ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+
+/*
+  Builds the list a client shows from two sources:
+    rows     [{ value, uses }]  every distinct value items hold, with how many items hold it
+    records  [{ key, name, image, description, owner }]  the stored category records
+
+  Spellings that differ only in case or spacing are merged and counted together. The name shown is
+  the stored record's if there is one, otherwise the most used spelling (on a tie, the one that
+  starts with a capital). Categories no item has are left out unless `includeEmpty` is set, which an
+  admin screen uses so a category can exist, with its picture and description, before it has items.
+  Sorted by name.
+*/
+export const groupCategories = (rows, records = [], { includeEmpty = false } = {}) => {
+  const byKey = new Map();
+  for(const { value, uses } of rows){
+    const key = categoryKey(value);
+    if(!key) continue;
+    const entry = byKey.get(key) ?? { count: 0, spellings: new Map() };
+    entry.count += uses;
+    entry.spellings.set(value, (entry.spellings.get(value) ?? 0) + uses);
+    byKey.set(key, entry);
+  }
+
+  const recordByKey = new Map(records.map(record => [record.key, record]));
+  const startsUpper = text => /^\p{Lu}/u.test(text);
+
+  const used = [...byKey.entries()].map(([key, entry]) => {
+    const record = recordByKey.get(key);
+    const spelling = [...entry.spellings.entries()]
+      .sort((a, b) => b[1] - a[1] || Number(startsUpper(b[0])) - Number(startsUpper(a[0])) || a[0].localeCompare(b[0]))[0][0];
+    return { key, name: record?.name ?? spelling, count: entry.count, image: record?.image ?? null, description: record?.description ?? '', tags: record?.tags ?? [], owner: record?.owner ?? '' };
+  });
+
+  const empty = includeEmpty
+    ? records.filter(record => !byKey.has(record.key)).map(record => ({ key: record.key, name: record.name, count: 0, image: record.image ?? null, description: record.description ?? '', tags: record.tags ?? [], owner: record.owner ?? '' }))
+    : [];
+
+  return [...used, ...empty].sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+};

package/server/utils/events.js

@@ -0,0 +1,31 @@
+/*
+  Events this extension fires. Other extensions subscribe by declaring them in their own
+  kempo-config.json `hooks`, e.g. { "kempo-inventory:item:created": "./hooks/item-created.js" }.
+
+  Guards ("before" events) run first and can change the pending operation or refuse it:
+    - the payload carries a mutable `draft` (or `changes`); edit it in place to alter what is saved
+    - throw `{ code, msg }` to refuse; the caller receives exactly that error
+  Category and field guards can only refuse. Every payload carries `actor`: the extension that made
+  the change through the server SDK, or '' for a person using the admin.
+  Notifications ("after" events) run once the work is committed; nothing they do can undo it.
+*/
+export const EVENTS = {
+  itemBeforeCreate: 'kempo-inventory:item:before_create',
+  itemCreated: 'kempo-inventory:item:created',
+  itemBeforeUpdate: 'kempo-inventory:item:before_update',
+  itemUpdated: 'kempo-inventory:item:updated',
+  itemBeforeDelete: 'kempo-inventory:item:before_delete',
+  itemDeleted: 'kempo-inventory:item:deleted',
+  stockBeforeAdjust: 'kempo-inventory:stock:before_adjust',
+  stockAdjusted: 'kempo-inventory:stock:adjusted',
+  categoryBeforeUpdate: 'kempo-inventory:category:before_update',
+  categoryUpdated: 'kempo-inventory:category:updated',
+  categoryBeforeDelete: 'kempo-inventory:category:before_delete',
+  categoryDeleted: 'kempo-inventory:category:deleted',
+  fieldBeforeCreate: 'kempo-inventory:field:before_create',
+  fieldCreated: 'kempo-inventory:field:created',
+  fieldBeforeUpdate: 'kempo-inventory:field:before_update',
+  fieldUpdated: 'kempo-inventory:field:updated',
+  fieldBeforeDelete: 'kempo-inventory:field:before_delete',
+  fieldDeleted: 'kempo-inventory:field:deleted',
+};