kempo-inventory 0.2.0

package/server/utils/fieldTypes.js

@@ -0,0 +1,227 @@
+/*
+  Pure helpers with no database access, so field definitions and values can be validated
+  and unit tested without a server.
+*/
+
+import { categoryKey } from './categoryLogic.js';
+import { parseRatio } from './ratio.js';
+
+export const FIELD_TYPES = ['text', 'longtext', 'number', 'boolean', 'date', 'color', 'rating', 'select', 'item', 'media'];
+
+/*
+  Types that depend on another extension being installed. They are always valid in a definition,
+  but creating one is refused when the extension that backs it is missing (see fields.js).
+*/
+export const OPTIONAL_TYPES = { media: 'kempo-media or kempo-files' };
+
+export const MAX_MEDIA = 20;
+export const MAX_RATING = 5;
+export const MAX_IMAGE_EDGE = 8000;
+
+/*
+  The only type changes that cannot lose or reject what items already hold: a choice list becomes
+  free text (its values are already plain strings), and short text becomes long text. Anything
+  else, such as text to a number, could orphan existing values, so it is refused: delete the field
+  and make a new one instead.
+*/
+export const CONVERSIONS = { select: ['text'], text: ['longtext'] };
+
+export const canConvert = (from, to) => from === to || (CONVERSIONS[from] ?? []).includes(to);
+
+/*
+  A `media` value is a list of ids, each saying where the file lives. A bare id is a kempo-media
+  asset; "files:<id>" is a kempo-files file.
+*/
+const FILES_PREFIX = 'files:';
+const MEDIA_ID = /^(files:)?[a-f0-9]{16}$/;
+
+export const filesId = id => `${FILES_PREFIX}${id}`;
+
+export const parseMediaId = id => id.startsWith(FILES_PREFIX)
+  ? { provider: 'files', rawId: id.slice(FILES_PREFIX.length) }
+  : { provider: 'media', rawId: id };
+
+export const CORE_KEYS = ['id', 'sku', 'name', 'description', 'category', 'quantity', 'tags', 'created', 'updated', 'fields', 'data', 'linked'];
+
+export const KEY_PATTERN = /^[a-z][a-zA-Z0-9]{0,39}$/;
+
+const MAX_TEXT = 1000;
+const MAX_LONGTEXT = 20000;
+
+export const isEmpty = value => value === undefined || value === null || value === '';
+
+/*
+  Turns a human label into a valid key: "Reorder level" -> "reorderLevel".
+*/
+export const keyFromLabel = label => {
+  const words = String(label ?? '').replace(/[^a-zA-Z0-9]+/g, ' ').trim().split(' ').filter(Boolean);
+  if(!words.length) return '';
+  const key = words.map((w, i) => i === 0 ? w.charAt(0).toLowerCase() + w.slice(1) : w.charAt(0).toUpperCase() + w.slice(1)).join('');
+  return /^[a-z]/.test(key) ? key.slice(0, 40) : '';
+};
+
+/*
+  Validates and normalises a field definition. Returns [error, definition].
+*/
+export const normalizeFieldDefinition = (input = {}) => {
+  const label = String(input.label ?? '').trim();
+  if(!label) return [{ code: 400, msg: 'Field label is required' }, null];
+
+  const key = String(input.key ?? keyFromLabel(label)).trim();
+  if(!KEY_PATTERN.test(key)){
+    return [{ code: 400, msg: 'Field key must start with a lowercase letter and contain only letters and numbers (max 40)' }, null];
+  }
+  if(CORE_KEYS.includes(key)) return [{ code: 400, msg: `"${key}" is reserved` }, null];
+
+  if(!FIELD_TYPES.includes(input.type)) return [{ code: 400, msg: `Field type must be one of: ${FIELD_TYPES.join(', ')}` }, null];
+
+  let options = [];
+  if(input.type === 'select'){
+    options = [...new Set((Array.isArray(input.options) ? input.options : []).map(o => String(o).trim()).filter(Boolean))];
+    if(!options.length) return [{ code: 400, msg: 'A select field needs at least one option' }, null];
+  }
+
+  /*
+    A photo field can force how photos are saved: a shape (an aspect ratio such as 1:1 or 16:9) they
+    are cropped to as they are added, and a maximum size in pixels on either side. Other types ignore both.
+  */
+  let imageRatio = '';
+  let imageMax = 0;
+  if(input.type === 'media'){
+    if(!isEmpty(input.imageRatio)){
+      imageRatio = parseRatio(input.imageRatio);
+      if(!imageRatio) return [{ code: 400, msg: 'The photo shape must be a ratio such as 1:1, 4:3 or 16:9' }, null];
+    }
+    if(!isEmpty(input.imageMax)){
+      imageMax = Number(input.imageMax);
+      if(!Number.isInteger(imageMax) || imageMax < 0 || (imageMax > 0 && imageMax < 16) || imageMax > MAX_IMAGE_EDGE){
+        return [{ code: 400, msg: `The maximum photo size must be a whole number of pixels from 16 to ${MAX_IMAGE_EDGE} (or 0 for no limit)` }, null];
+      }
+    }
+  }
+
+  return [null, {
+    key,
+    label,
+    type: input.type,
+    description: String(input.description ?? ''),
+    required: Boolean(input.required),
+    listed: input.listed === undefined ? true : Boolean(input.listed),
+    suggest: input.type === 'text' && Boolean(input.suggest),
+    options,
+    position: Number.isInteger(input.position) ? input.position : 0,
+    imageRatio,
+    imageMax,
+  }];
+};
+
+/*
+  Coerces one raw value to the field's type. Returns [error, value], where an empty input
+  yields [null, null] (meaning "no value"). `item` fields are only shape-checked here; whether the
+  linked item exists is checked by the caller, which has the database.
+*/
+export const coerceValue = (field, raw) => {
+  if(field.type !== 'boolean' && (isEmpty(raw) || (Array.isArray(raw) && !raw.length))) return [null, null];
+  const bad = msg => [{ code: 400, msg: `${field.label}: ${msg}` }, null];
+
+  switch(field.type){
+    case 'text': {
+      /* Spaces before or after what was typed are never part of the value ("Vallejo " and "Vallejo" are one brand). */
+      const value = String(raw).trim();
+      if(!value) return [null, null];
+      return value.length > MAX_TEXT ? bad(`must be ${MAX_TEXT} characters or fewer`) : [null, value];
+    }
+    case 'longtext': {
+      const value = String(raw).trim();
+      if(!value) return [null, null];
+      return value.length > MAX_LONGTEXT ? bad(`must be ${MAX_LONGTEXT} characters or fewer`) : [null, value];
+    }
+    case 'number': {
+      const value = typeof raw === 'number' ? raw : Number(String(raw).trim());
+      return Number.isFinite(value) ? [null, value] : bad('must be a number');
+    }
+    case 'rating': {
+      /* A whole number of stars, 1 to 5. No stars (0) means no rating, the same as leaving it empty. */
+      const value = typeof raw === 'number' ? raw : Number(String(raw).trim());
+      if(!Number.isInteger(value) || value < 0 || value > MAX_RATING) return bad(`must be a whole number of stars from 1 to ${MAX_RATING}`);
+      return [null, value === 0 ? null : value];
+    }
+    case 'boolean': {
+      if(isEmpty(raw)) return [null, null];
+      if(typeof raw === 'boolean') return [null, raw];
+      if(raw === 'true') return [null, true];
+      if(raw === 'false') return [null, false];
+      return bad('must be true or false');
+    }
+    case 'date': {
+      const value = String(raw);
+      const valid = /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`))
+        && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+      return valid ? [null, value] : bad('must be a date (YYYY-MM-DD)');
+    }
+    case 'color': {
+      /* A hex colour. Stored as "#rrggbb", or "#rrggbbaa" when it is see-through; "#abc" is expanded. */
+      const text = String(raw).trim().toLowerCase();
+      const short = text.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])?$/);
+      const value = short ? `#${short.slice(1).filter(Boolean).map(c => c + c).join('')}` : text;
+      return /^#(?:[0-9a-f]{6}|[0-9a-f]{8})$/.test(value) ? [null, value.endsWith('ff') && value.length === 9 ? value.slice(0, 7) : value] : bad('must be a hex color such as #ff8800');
+    }
+    case 'select': {
+      const value = String(raw).trim();
+      if(!value) return [null, null];
+      return field.options.includes(value) ? [null, value] : bad(`must be one of: ${field.options.join(', ')}`);
+    }
+    case 'item': {
+      const value = String(raw);
+      return /^[a-f0-9]{16}$/.test(value) ? [null, value] : bad('must be a valid item');
+    }
+    case 'media': {
+      const list = Array.isArray(raw) ? raw : String(raw).split(',');
+      const ids = [...new Set(list.map(v => String(v).trim()).filter(Boolean))];
+      if(!ids.length) return [null, null];
+      if(ids.length > MAX_MEDIA) return bad(`can hold at most ${MAX_MEDIA} files`);
+      return ids.every(id => MEDIA_ID.test(id)) ? [null, ids] : bad('must be a list of media files');
+    }
+    default:
+      return bad('has an unsupported type');
+  }
+};
+
+/*
+  Validates `input` (an object keyed by field key) against `fields`.
+    partial=false: every required field must be present (creating an item)
+    partial=true:  only the keys supplied are checked (updating an item)
+  Returns [error, values] where `values[key]` is the coerced value or null to clear it.
+*/
+/*
+  The fields an item shows: the default ones (category '') plus those scoped to its category.
+  `category` is the item's category in any spelling; an uncategorised item gets only the defaults.
+*/
+export const applicableFields = (fields, category) => {
+  const key = categoryKey(category);
+  return fields.filter(f => !f.category || f.category === key);
+};
+
+export const coerceValues = (fields, input = {}, { partial = false } = {}) => {
+  if(input === null || typeof input !== 'object' || Array.isArray(input)){
+    return [{ code: 400, msg: 'fields must be an object' }, null];
+  }
+  const byKey = new Map(fields.map(f => [f.key, f]));
+  const values = {};
+
+  for(const key of Object.keys(input)){
+    if(!byKey.has(key)) return [{ code: 400, msg: `Unknown field "${key}"` }, null];
+  }
+
+  for(const field of fields){
+    const supplied = Object.prototype.hasOwnProperty.call(input, field.key);
+    if(partial && !supplied) continue;
+    const [error, value] = coerceValue(field, supplied ? input[field.key] : undefined);
+    if(error) return [error, null];
+    if(value === null && field.required){
+      return [{ code: 400, msg: `${field.label} is required` }, null];
+    }
+    if(supplied || value !== null) values[field.key] = value;
+  }
+  return [null, values];
+};

package/server/utils/fields.js

@@ -0,0 +1,238 @@
+import db from 'kempo/server/db/index.js';
+import { eq, and, asc, sql } from 'drizzle-orm';
+import crypto from 'crypto';
+import { kempoInventoryField, kempoInventoryItem, kempoInventoryCategory } from '../db/schema.js';
+import { categoryKey, tidyCategory, MAX_CATEGORY } from './categoryLogic.js';
+import { normalizeFieldDefinition, OPTIONAL_TYPES, canConvert } from './fieldTypes.js';
+import { mediaAvailable } from './media.js';
+import { EVENTS, guard, notify } from './hooks.js';
+
+const newId = () => crypto.randomBytes(8).toString('hex');
+
+const isUniqueViolation = error => (error?.code || error?.cause?.code) === '23505';
+
+/*
+  Properties an extension's own field accepts on update, and what anyone else (the admin UI) may
+  adjust on a field an extension owns. Key and ownership never change after creation, and the type
+  only changes where nothing can be lost (see CONVERSIONS in fieldTypes.js).
+*/
+const OWNER_EDITABLE = ['label', 'description', 'required', 'listed', 'suggest', 'options', 'position', 'type', 'imageRatio', 'imageMax'];
+const ANYONE_EDITABLE = ['label', 'description', 'listed', 'suggest', 'position', 'imageRatio', 'imageMax'];
+
+/*
+  Every field, each with the `category` key it is scoped to ('' = every item) and `categoryName`
+  for display. Pass `category` to get only the fields an item in that category shows: the default
+  ones plus that category's ('' gives just the defaults).
+*/
+export const getFields = async ({ category, owner } = {}) => {
+  try {
+    const rows = await db.select().from(kempoInventoryField)
+      .orderBy(asc(kempoInventoryField.position), asc(kempoInventoryField.created), asc(kempoInventoryField.id));
+    const records = await db.select({ key: kempoInventoryCategory.key, name: kempoInventoryCategory.name }).from(kempoInventoryCategory);
+    const names = new Map(records.map(r => [r.key, r.name]));
+    let fields = rows.map(f => ({ ...f, categoryName: f.category ? names.get(f.category) ?? f.category : '' }));
+    if(category !== undefined){
+      const key = categoryKey(category);
+      fields = fields.filter(f => !f.category || f.category === key);
+    }
+    if(owner !== undefined) fields = fields.filter(f => f.owner === String(owner ?? ''));
+    return [null, fields];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve fields' }, null];
+  }
+};
+
+/* A field is identified by its key and the category it belongs to ('' for the default scope). */
+export const getField = async (key, category = '') => {
+  if(!key) return [{ code: 400, msg: 'Field key is required' }, null];
+  try {
+    const [field] = await db.select().from(kempoInventoryField)
+      .where(and(eq(kempoInventoryField.key, key), eq(kempoInventoryField.category, categoryKey(category))));
+    if(!field) return [{ code: 404, msg: 'Field not found' }, null];
+    return [null, field];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retrieve field' }, null];
+  }
+};
+
+/* The items a field's values live on: everything for a default field, otherwise that category's items. */
+export const itemsInScope = category => category
+  ? sql`lower(regexp_replace(btrim(${kempoInventoryItem.category}), '[[:space:]]+', ' ', 'g')) = ${category}`
+  : sql`true`;
+
+/*
+  Creates a field. `owner` is '' for a field made by a person in the admin, or the extension's
+  name for one it registers itself.
+*/
+export const createField = async (definition, { owner = '' } = {}) => {
+  const [invalid, normalized] = normalizeFieldDefinition(definition);
+  if(invalid) return [invalid, null];
+
+  const refused = await guard(EVENTS.fieldBeforeCreate, { draft: { ...normalized, category: tidyCategory(definition?.category) }, actor: owner });
+  if(refused) return [refused, null];
+
+  /* `definition.category` names the category the field belongs to; empty means every item. */
+  const categoryName = tidyCategory(definition?.category);
+  if(categoryName.length > MAX_CATEGORY) return [{ code: 400, msg: `A category name must be ${MAX_CATEGORY} characters or fewer` }, null];
+  const scope = categoryKey(categoryName);
+  if(normalized.type === 'media' && !(await mediaAvailable())){
+    return [{ code: 409, msg: `Media fields need the ${OPTIONAL_TYPES.media} extension, which is not installed` }, null];
+  }
+
+  try {
+    /*
+      Items in a category hold the default fields and that category's under one set of names, so a
+      key cannot be reused where it would collide: a default field's key is taken in every category,
+      and a category's key is taken in the default scope.
+    */
+    const clash = await db.select({ category: kempoInventoryField.category }).from(kempoInventoryField).where(and(
+      eq(kempoInventoryField.key, normalized.key),
+      scope ? sql`${kempoInventoryField.category} in ('', ${scope})` : sql`true`,
+    ));
+    if(clash.length){
+      const where = clash[0].category === scope ? (scope ? 'this category' : 'the default fields') : (scope ? 'the default fields' : 'a category');
+      return [{ code: 409, msg: `A field with the key "${normalized.key}" already exists in ${where}` }, null];
+    }
+
+    const field = await db.transaction(async tx => {
+      if(scope){
+        /* A category with a field has to exist as a record, even before any item uses it. */
+        const now = new Date();
+        await tx.insert(kempoInventoryCategory)
+          .values({ id: newId(), key: scope, name: categoryName, image: null, created: now, updated: now })
+          .onConflictDoNothing();
+      }
+      const [created] = await tx.insert(kempoInventoryField)
+        .values({ id: newId(), ...normalized, category: scope, owner, created: new Date() })
+        .returning();
+      return created;
+    });
+    await notify(EVENTS.fieldCreated, { field, actor: owner });
+    return [null, field];
+  } catch(error) {
+    if(isUniqueViolation(error)) return [{ code: 409, msg: `A field with the key "${normalized.key}" already exists` }, null];
+    return [{ code: 500, msg: 'Failed to create field' }, null];
+  }
+};
+
+export const updateField = async (key, changes = {}, { owner = null, category = '' } = {}) => {
+  const [lookupError, existing] = await getField(key, category);
+  if(lookupError) return [lookupError, null];
+
+  const targetType = changes.type ?? existing.type;
+  if(!canConvert(existing.type, targetType)){
+    return [{ code: 409, msg: `A ${existing.type} field cannot be changed to ${targetType}. Delete it and create a new one instead` }, null];
+  }
+  const isOwner = existing.owner === (owner ?? '');
+  const allowed = isOwner ? OWNER_EDITABLE : ANYONE_EDITABLE;
+  const rejected = Object.keys(changes).filter(k => k !== 'key' && k !== 'category' && !(k === 'type' && targetType === existing.type) && !allowed.includes(k));
+  if(rejected.length){
+    return [{ code: 403, msg: `${rejected.join(', ')} can only be changed by ${existing.owner ? `the "${existing.owner}" extension` : 'the field\'s owner'}` }, null];
+  }
+
+  const [invalid, normalized] = normalizeFieldDefinition({ ...existing, ...changes, key: existing.key, type: targetType });
+  if(invalid) return [invalid, null];
+
+  const updates = {};
+  for(const property of allowed){
+    if(changes[property] !== undefined) updates[property] = normalized[property];
+  }
+  if(targetType !== existing.type){
+    /* Converting: the type changes, and what only made sense for the old type goes with it. */
+    updates.type = targetType;
+    updates.options = normalized.options;
+    updates.suggest = normalized.suggest;
+  }
+  if(!Object.keys(updates).length) return [{ code: 400, msg: 'No changes provided' }, null];
+
+  const refused = await guard(EVENTS.fieldBeforeUpdate, { field: existing, changes: updates, actor: owner ?? '' });
+  if(refused) return [refused, null];
+
+  try {
+    const [field] = await db.update(kempoInventoryField).set(updates)
+      .where(and(eq(kempoInventoryField.key, key), eq(kempoInventoryField.category, existing.category))).returning();
+    await notify(EVENTS.fieldUpdated, { field, previous: existing, actor: owner ?? '' });
+    return [null, field];
+  } catch {
+    return [{ code: 500, msg: 'Failed to update field' }, null];
+  }
+};
+
+/*
+  Deletes a field and the values items hold for it. A person using the admin deletes their own
+  fields (owner ''); an extension deletes the ones it registered.
+*/
+export const deleteField = async (key, { owner = '', category = '' } = {}) => {
+  const [lookupError, existing] = await getField(key, category);
+  if(lookupError) return [lookupError, null];
+  if(existing.owner !== owner){
+    return [{ code: 403, msg: `This field is managed by the "${existing.owner}" extension and cannot be deleted here` }, null];
+  }
+  const refused = await guard(EVENTS.fieldBeforeDelete, { field: existing, actor: owner });
+  if(refused) return [refused, null];
+
+  try {
+    await db.transaction(async tx => {
+      await tx.update(kempoInventoryItem).set({ data: sql`${kempoInventoryItem.data} - ${key}::text` }).where(itemsInScope(existing.category));
+      await tx.delete(kempoInventoryField).where(and(eq(kempoInventoryField.key, key), eq(kempoInventoryField.category, existing.category)));
+    });
+    await notify(EVENTS.fieldDeleted, { field: existing, actor: owner });
+    return [null, { success: true }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to delete field' }, null];
+  }
+};
+
+/*
+  Idempotent: safe to call from an extension's install.js and again on every update. Creates the
+  field if it is new, otherwise refreshes what the owner is allowed to change. Refuses to take
+  over a key another owner holds, or to change an existing field's type.
+
+  `definition.category` scopes the field to one category (see registerCategory); without it the
+  field is on every item.
+*/
+export const registerField = async (owner, definition) => {
+  if(!owner) return [{ code: 400, msg: 'An owner (your extension name) is required' }, null];
+  const [invalid, normalized] = normalizeFieldDefinition(definition);
+  if(invalid) return [invalid, null];
+
+  const category = tidyCategory(definition?.category);
+  const [lookupError, existing] = await getField(normalized.key, category);
+  if(lookupError && lookupError.code !== 404) return [lookupError, null];
+  if(!existing) return createField({ ...normalized, category }, { owner });
+
+  if(existing.owner !== owner){
+    return [{ code: 409, msg: `The key "${normalized.key}" is already used by ${existing.owner ? `the "${existing.owner}" extension` : 'a user-defined field'}` }, null];
+  }
+  if(existing.type !== normalized.type){
+    return [{ code: 409, msg: `"${normalized.key}" already exists as a ${existing.type} field` }, null];
+  }
+  const { key, type, ...changes } = normalized;
+  return updateField(normalized.key, changes, { owner, category });
+};
+
+export const registerFields = async (owner, definitions = []) => {
+  const registered = [];
+  for(const definition of definitions){
+    const [error, field] = await registerField(owner, definition);
+    if(error) return [error, registered];
+    registered.push(field);
+  }
+  return [null, registered];
+};
+
+/*
+  For an extension's uninstall.js: removes every field it registered, and their values.
+*/
+export const unregisterFields = async owner => {
+  if(!owner) return [{ code: 400, msg: 'An owner (your extension name) is required' }, null];
+  const [error, fields] = await getFields();
+  if(error) return [error, null];
+  let removed = 0;
+  for(const field of fields.filter(f => f.owner === owner)){
+    const [deleteError] = await deleteField(field.key, { owner, category: field.category });
+    if(deleteError) return [deleteError, null];
+    removed++;
+  }
+  return [null, { removed }];
+};

package/server/utils/hooks.js

@@ -0,0 +1,30 @@
+import { triggerHook } from 'kempo/server/sdk.js';
+
+import { EVENTS } from './events.js';
+
+export { EVENTS };
+
+/*
+  Resolves to null to proceed, or an `{ code, msg }` to stop. A handler that throws anything other
+  than `{ code, msg }` is logged and reported generically, so internals never reach the caller.
+*/
+export const guard = async (event, data) => {
+  try {
+    await triggerHook(event, data, { bail: true });
+    return null;
+  } catch(error) {
+    if(error && Number.isInteger(error.code) && typeof error.msg === 'string'){
+      return { code: error.code, msg: error.msg };
+    }
+    console.error(`[kempo-inventory] "${event}" hook failed:`, error);
+    return { code: 500, msg: 'The change was rejected by an extension' };
+  }
+};
+
+export const notify = async (event, data) => {
+  try {
+    await triggerHook(event, data);
+  } catch(error) {
+    console.error(`[kempo-inventory] "${event}" notification failed:`, error);
+  }
+};