kempo-inventory 0.2.2 → 0.3.0

package/README.md

@@ -130,7 +130,7 @@ Reading the inventory needs the `items:read` permission. Turn on the `public_rea
 
 ## Who can see photos
 
-kempo-files only serves a file to people with its `files:download` permission, which someone who can merely *read* the inventory does not have, so their photos would be broken images. The `public_photos` setting (on by default) uploads photos to kempo-files as **public**: viewable by anyone who has the link (ids are unguessable), which includes every inventory reader. Turn it off to keep photos behind `files:download`; then give your readers that permission. Changing the setting only affects new uploads. `update.js` also marks the photos items and categories already use (and their thumbnails) public when the setting is on. kempo-media files are ordinary static files and are always viewable.
+kempo-files only serves a file to people with its `files:download` permission, which someone who can merely *read* the inventory does not have, so their photos would be broken images. The `public_photos` setting (on by default) uploads photos as **public**, whether they go to kempo-media or kempo-files: viewable by anyone who has the link (ids are unguessable), which includes every inventory reader. Turn it off to keep photos behind `files:download`; then give your readers that permission. Changing the setting only affects new uploads. `update.js` also marks the photos items and categories already use (and their thumbnails) public when the setting is on.
 
 ## Photos and files (optional)
 
@@ -138,21 +138,15 @@ Three optional extensions can take part. Inventory never imports any of them up
 
 | Extension | Role |
 |---|---|
-| [kempo-media](https://github.com/dustinpoissant/kempo-media) | A media library with its own image thumbnails. Files are served from `public/media/`, so anyone who knows a URL can fetch them |
-| [kempo-files](https://github.com/dustinpoissant/kempo-files) | A private file library: files live outside `public/` and every download is permission-checked |
-| [kempo-thumbs](https://github.com/dustinpoissant/kempo-thumbs) | Generates thumbnails for kempo-files, including frames from video and audio. It only works on kempo-files |
+| [kempo-media](https://github.com/dustinpoissant/kempo-media) | A media library: a kempo-files file plus kind, dimensions and alt text, with thumbnails from kempo-thumbs. It requires the other two, so installing it brings all three |
+| [kempo-files](https://github.com/dustinpoissant/kempo-files) | A file library: files live outside `public/` and every download is permission-checked, unless the file is marked public |
+| [kempo-thumbs](https://github.com/dustinpoissant/kempo-thumbs) | Generates thumbnails for kempo-files, including frames from video and audio |
 
 When an item has more than one photo, the first is its **primary** photo (the one shown on cards and lists). In the item form each other photo has a **Make primary** button that moves it to the front.
 
-Add a field of type "Photos / files" and every item gets an upload area. New uploads go to one library, chosen by the `media_provider` setting:
+Add a field of type "Photos / files" and every item gets an upload area. New uploads go to kempo-media when it is installed (it is kempo-files with thumbnails, so one upload gives you a stored file and its thumbnail), and to kempo-files directly on a site that has only that. There is no setting to choose; the old `media_provider` setting was retired, and `update.js` removes it.
 
-| Setting | Uploads go to |
-|---|---|
-| `auto` (default) | kempo-files when kempo-thumbs is also installed, otherwise kempo-media, otherwise kempo-files |
-| `kempo-media` | kempo-media (if installed) |
-| `kempo-files` | kempo-files (if installed) |
-
-A stored value records where its file lives, so files from both libraries keep working on the same item whichever one takes new uploads. The API returns a `media` map (stored id → `{ kind, name, alt, path, thumbnail }`) next to `linked`, so a client can show them. A kempo-files photo has no `thumbnail` until kempo-thumbs has generated one, so clients should fall back to `path`.
+A stored value records where its file lives (a bare id is a kempo-media asset, `files:<id>` a kempo-files file), so values written before this change, or by a site with only kempo-files, keep working on the same item as newer ones. The API returns a `media` map (stored id → `{ kind, name, alt, path, thumbnail }`) next to `linked`, so a client can show them. A kempo-files photo has no `thumbnail` until kempo-thumbs has generated one, so clients should fall back to `path`.
 
 - If a library is disabled later, items keep their stored ids and everything else keeps working. Files from that library show as missing, and only *adding* a file from it is refused; an item can still be edited with its existing list unchanged.
 - Deleting a file from its library leaves the id on the item, shown as a missing file.
@@ -448,3 +442,7 @@ All routes require a session holding the permission above.
 - Uninstalling drops the item, field and movement tables, including your data.
 - Custom values are stored in a single `jsonb` column, so adding a field never alters the schema.
 - `item` links store the linked item's id. Deleting an item leaves any links to it in place, shown as "(deleted item)".
+
+## Development
+
+The documentation site is written in `docs-src/` and built into `docs/` (served by GitHub Pages from the `docs` folder). Edit `docs-src/`, never `docs/`, then run `npm run docs:build`; `npm run docs:dev` serves it on port 4050. Screenshots come in pairs: write `<img src="./media/name.png" ...>` in a page, and put `name-light.png` and `name-dark.png` in `docs-src/media`. The build turns the tag into both images and the site shows the one matching the visitor's theme.

package/admin/nav.global.html

@@ -1,3 +1,3 @@
 <content id="kempo-inventory-nav" name="Inventory" owner="kempo-inventory" enabled="true" locked="true" location="admin-nav-extensions" priority="20">
-<k-aside-item icon="archive" href="/admin/extension/kempo-inventory/" no-expand>Inventory</k-aside-item>
+<k-aside-item icon="archive" group="Commerce" href="/admin/extension/kempo-inventory/" no-expand>Inventory</k-aside-item>
 </content>

package/kempo-config.json

@@ -63,12 +63,6 @@
     }
   ],
   "settings": [
-    {
-      "name": "media_provider",
-      "value": "auto",
-      "type": "string",
-      "description": "Where new photos and files are uploaded: auto, kempo-media or kempo-files. Auto uses kempo-files when kempo-thumbs is installed to thumbnail it, otherwise kempo-media."
-    },
     {
       "name": "import_max_mb",
       "value": 250,
@@ -85,7 +79,7 @@
       "name": "public_photos",
       "value": true,
       "type": "boolean",
-      "description": "Photos uploaded to kempo-files are viewable by anyone with the link, so every person who can read the inventory sees them (kempo-files otherwise needs each of them to have its files:download permission). Turn off to keep photos behind that permission."
+      "description": "New photos are viewable by anyone with the link, so every person who can read the inventory sees them (a private file otherwise needs each of them to have the files:download permission). Turn off to keep photos behind that permission."
     },
     {
       "name": "category_image_ratio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-inventory",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A basic inventory management system for kempo cms",
   "license": "MIT",
   "author": "Dustin Poissant",
@@ -16,7 +16,9 @@
   "main": "sdk.js",
   "scripts": {
     "test": "node --test",
-    "link:local": "npm install ../kempo --no-save"
+    "link:local": "npm install ../kempo ../kempo-server ../kempo-ui --no-save --no-legacy-peer-deps --force",
+    "docs:build": "node scripts/build-docs.js",
+    "docs:dev": "npx kempo-server --root docs --port 4050"
   },
   "kempo": {
     "public-scope": "inventory"
@@ -41,7 +43,7 @@
   "peerDependencies": {
     "kempo": ">=4.3.0",
     "kempo-ui": ">=0.5.0",
-    "kempo-media": ">=0.2.3",
+    "kempo-media": ">=0.3.0",
     "kempo-files": ">=0.1.3",
     "kempo-thumbs": ">=0.1.3"
   },
@@ -55,5 +57,8 @@
     "kempo-thumbs": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "highlight.js": "^11.11.1"
   }
 }

package/public/components/ItemFields.js

@@ -42,7 +42,7 @@ const MEDIA_ACCEPT = 'image/*,video/*,audio/*,.glb,.gltf,.obj,.fbx,.zip';
 
 /*
   Which library new uploads go to ('media', 'files' or null), decided by the server from what is
-  installed and the media_provider setting. Asked once per page.
+  installed: kempo-media when it is there, otherwise kempo-files. Asked once per page.
 */
 let infoPromise = null;
 const fieldInfo = () => infoPromise ??= getFields().then(([error, data]) => {
@@ -50,7 +50,7 @@ const fieldInfo = () => infoPromise ??= getFields().then(([error, data]) => {
   return error ? null : data;
 });
 const uploadProvider = () => fieldInfo().then(data => data?.capabilities.upload ?? null);
-/* Whether files uploaded to kempo-files are made public (the public_photos setting). */
+/* Whether new uploads are made public (the public_photos setting). */
 const uploadsArePublic = () => fieldInfo().then(data => data?.capabilities.publicFiles !== false);
 
 /*
@@ -66,7 +66,7 @@ export const imageRatios = () => fieldInfo().then(data => data?.imageRatios ?? {
 */
 const uploadToMedia = async file => {
   const { uploadMedia } = await import('/kempo-media/sdk.js');
-  const [error, data] = await uploadMedia(file);
+  const [error, data] = await uploadMedia(file, { public: await uploadsArePublic() });
   if(error) return [error, null];
   const asset = data.asset;
   return [null, { id: asset.id, asset: {

package/server/utils/media.js

@@ -1,7 +1,6 @@
 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 { safeFileName } from './mediaSafety.js';
 import { DEFAULT_RATIOS, resolveRatio } from './ratio.js';
 import { parseMediaId, filesId } from './fieldTypes.js';
 
@@ -9,16 +8,18 @@ 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-media   a media library: a kempo-files file plus kind, dimensions and alt text, with
+                  thumbnails from kempo-thumbs. It requires the other two.
+    kempo-files   a file library; a non-public file needs 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.
+  is both installed as a package and enabled in kempo.
 
-  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.
+  New uploads go to kempo-media when it is there, because it already is kempo-files with thumbnails;
+  only a site with kempo-files alone uploads to kempo-files directly. Stored values keep saying where
+  they live, so older ones keep resolving: a bare id is a kempo-media asset, "files:<id>" is a
+  kempo-files file.
 */
 const loaders = {
   'kempo-media': () => import('kempo-media/sdk'),
@@ -51,22 +52,11 @@ export const mediaAvailable = async () => {
 };
 
 /*
-  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.
+  Which library new uploads go to: 'media', 'files' or null when neither is installed.
 */
-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;
-};
+export const chooseUploadProvider = found => found.media ? 'media' : found.files ? 'files' : null;
+
+export const uploadProvider = async () => chooseUploadProvider(await providers());
 
 /*
   The aspect ratios images are shown at, as CSS ("4 / 3"): { category, item }. They come from the
@@ -78,7 +68,7 @@ export const getImageRatios = async () => {
   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. */
+/* Whether new photos 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';
@@ -173,7 +163,13 @@ export const readMedia = async storedId => {
       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)) }];
+      // The asset's id is its kempo-files file id, and its bytes live in kempo-files
+      const { getFile, filePath } = await load('kempo-files');
+      const [fileError, file] = await getFile(asset.fileId);
+      if(fileError) return [fileError, null];
+      const [pathError, absolute] = await filePath(file);
+      if(pathError) return [pathError, null];
+      return [null, { name: asset.originalName, kind: asset.kind, alt: asset.altText ?? '', bytes: await readFile(absolute) }];
     }
   } catch {
     return [{ code: 404, msg: 'The file could not be read' }, null];
@@ -181,8 +177,6 @@ export const readMedia = async storedId => {
   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
@@ -212,16 +206,12 @@ export const storeMedia = async ({ name, bytes, altText = '', userId }) => {
       }
       return [{ code: 409, msg: 'No free file name could be found' }, null];
     }
-    const { storeUpload, createMediaAsset } = await load('kempo-media');
+    const { uploadMediaAsset } = 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),
+    const [error, asset] = await uploadMediaAsset({
+      filename: safe, data, altText, uploadedBy: userId, maxBytes: Number(maxMb) * 1024 * 1024, public: await publicPhotos(),
     });
-    if(error) return [error, null];
-    const [recordError, row] = await createMediaAsset(asset);
-    return recordError ? [recordError, null] : [null, row.id];
+    return error ? [error, null] : [null, asset.id];
   } catch {
     return [{ code: 500, msg: 'The file could not be stored' }, null];
   }

package/update.js

@@ -1,6 +1,6 @@
 import { sql } from 'drizzle-orm';
 import db from 'kempo/server/db/index.js';
-import { getSetting, setSetting } from 'kempo/server/sdk.js';
+import { getSetting, setSetting, deleteSetting } from 'kempo/server/sdk.js';
 
 /*
   kempo creates tables that are new in an update but never alters ones that already exist, so a
@@ -8,6 +8,9 @@ import { getSetting, setSetting } from 'kempo/server/sdk.js';
   this on a database that already has the change is harmless.
 */
 export default async () => {
+  // Next: media_provider is retired. kempo-media sits on kempo-files, so new uploads go through it whenever it is installed.
+  await deleteSetting('kempo-inventory', 'media_provider');
+
   // 0.15: items and categories can be owned by an extension ('' = managed by people, as before)
   await db.execute(sql`ALTER TABLE "kempoInventoryItem" ADD COLUMN IF NOT EXISTS "owner" text NOT NULL DEFAULT ''`);
   await db.execute(sql`ALTER TABLE "kempoInventoryCategory" ADD COLUMN IF NOT EXISTS "owner" text NOT NULL DEFAULT ''`);