@byline/core 3.18.0 → 3.19.0

package/dist/@types/collection-types.d.ts

@@ -132,6 +132,52 @@ export interface UploadConfig {
      * @see UploadHooks
      */
     hooks?: UploadHooks | UploadHooksLoader;
+    /**
+     * Form-value paths the admin upload executor resolves at submit time and
+     * posts alongside the file, so server-side `beforeStore` / `afterStore`
+     * hooks receive document context in `ctx.fields` (always strings —
+     * multipart form values arrive untyped).
+     *
+     * Paths use filesystem-style resolution relative to the upload field's
+     * containing scope. For a field at `files[2].filesGroup.publicationFile`:
+     *
+     *   - `'language'` (bare / `./`) → sibling: `files[2].filesGroup.language`
+     *   - `'../label'` → one level up: `files[2].label`
+     *   - `'/serialNumber'` → document root: `serialNumber`
+     *
+     * Each resolved value is posted under the path's **leaf name** (`language`,
+     * `serialNumber`); when two context paths share a leaf name the later
+     * declaration wins. Serialisation: strings pass through; numbers/booleans
+     * are stringified; relation envelopes post their `targetDocumentId`
+     * (hasMany: comma-joined); `null`/`undefined` values are omitted; anything
+     * else is JSON-stringified.
+     *
+     * Independent of `context`, the executor always posts `documentId` (edit
+     * mode only — absent while the document is unsaved) and `fieldPath` (the
+     * full form path of the upload field, e.g.
+     * `files[2].filesGroup.publicationFile`).
+     *
+     * Hooks must treat all of these as **client-supplied claims** and re-verify
+     * anything security- or integrity-relevant server-side (e.g. fetch the
+     * document by `documentId` rather than trusting a posted serial).
+     */
+    context?: string[];
+    /**
+     * When `true`, the admin renders a "save this document first" notice in
+     * place of the upload widget until the document has been persisted (i.e.
+     * the form is in edit mode with a document id). Existing stored values
+     * still render normally — only the *upload* affordance is gated.
+     *
+     * Use this when server-side upload hooks depend on state that exists only
+     * after the first save — allocator-assigned `counter` fields, the document
+     * id itself — e.g. a `beforeStore` hook that derives the storage key from
+     * the document's serial number.
+     *
+     * Admin-side UX only: API callers can still upload without a document.
+     * Enforce the invariant server-side in a `beforeStore` hook (reject with
+     * `{ error }` when the required context is missing).
+     */
+    requireSavedDocument?: boolean;
 }
 /**
  * The three status names that every workflow must contain.
@@ -520,7 +566,19 @@ export interface TreeChangeContext {
  *
  *   - Rename the file by returning a string or `{ filename }`. The
  *     override is threaded into `storage.upload(...)`, so generated
- *     image variants automatically inherit the new prefix.
+ *     image variants automatically inherit the new prefix. The storage
+ *     provider still derives the final key (e.g. local storage prefixes
+ *     `<collection>/<uuid>-` for collision avoidance).
+ *   - Take **full control of the storage key** by returning
+ *     `{ storagePath }` — a fully-qualified, POSIX-style path (no
+ *     leading slash) that is threaded into `storage.upload(...)` as
+ *     `targetStoragePath` and written **verbatim**: no UUID prefix, no
+ *     collection namespace, no provider rewriting. The hook assumes
+ *     responsibility for sanitisation and collision avoidance (see
+ *     `UploadFileOptions.targetStoragePath`). Generated image variants
+ *     derive their sibling paths from the custom original. When
+ *     `storagePath` is returned without `filename`, the stored
+ *     `filename` defaults to the path's basename.
  *   - Reject the upload by returning `{ error }`. Surfaces as
  *     `ERR_VALIDATION` with the supplied message; no file is written,
  *     no variants are generated, no document is created, no later
@@ -529,7 +587,8 @@ export interface TreeChangeContext {
  *
  * When configured as an array, hooks fold: each function receives the
  * filename returned by the previous function (or the original sanitised
- * filename if the previous returned `void`).
+ * filename if the previous returned `void`), and `ctx.storagePath`
+ * carries the most recent explicit storage-path override (if any).
  */
 export interface BeforeStoreContext {
     /** Name of the image/file field receiving this upload. */
@@ -538,6 +597,12 @@ export interface BeforeStoreContext {
     field: ImageField | FileField;
     /** Sanitised default filename. Hooks may override. */
     filename: string;
+    /**
+     * Explicit storage-path override set by an earlier hook in the chain
+     * (via `{ storagePath }`), if any. `undefined` means the storage
+     * provider will derive the key itself from `filename` + `collection`.
+     */
+    storagePath?: string;
     mimeType: string;
     fileSize: number;
     /**
@@ -550,22 +615,37 @@ export interface BeforeStoreContext {
     collectionPath: string;
     /** Authenticated request context. `actor.id`, `actor.tenantId`, etc. for prefixing. */
     requestContext: RequestContext;
+    /**
+     * The storage provider this upload will be written to (the field's
+     * `upload.storage` or the site-wide default). Lets hooks feature-detect
+     * and use the optional provider capabilities — e.g. `storage.exists?.(key)`
+     * to collision-check an explicit `{ storagePath }` before claiming it.
+     */
+    storage: IStorageProvider;
 }
 /**
  * Result returned by a `beforeStore` hook.
  *
  *   - `string`            → override filename (shorthand).
- *   - `{ filename }`      → override filename (object form).
+ *   - `{ filename }`      → override filename (object form). The storage
+ *                           provider still derives the final key.
+ *   - `{ storagePath }`   → take full control of the storage key: written
+ *                           verbatim via `UploadFileOptions.targetStoragePath`
+ *                           (no UUID prefix / provider rewriting). May be
+ *                           combined with `filename`; without it, the stored
+ *                           filename defaults to the path's basename.
  *   - `{ error }`         → reject the upload; surfaces as
  *                           `ERR_VALIDATION`. Short-circuits the chain.
  *   - `void` / undefined  → keep current defaults.
  */
 export type BeforeStoreResult = string | {
     filename?: string;
+    storagePath?: string;
     error?: undefined;
 } | {
     error: string;
     filename?: undefined;
+    storagePath?: undefined;
 } | void;
 /**
  * A `beforeStore` hook function. Async-capable.
@@ -595,6 +675,11 @@ export interface AfterStoreContext {
     fields: Record<string, string>;
     collectionPath: string;
     requestContext: RequestContext;
+    /**
+     * The storage provider the file was written to. See
+     * {@link BeforeStoreContext.storage}.
+     */
+    storage: IStorageProvider;
 }
 /** An `afterStore` hook function. Async-capable. */
 export type AfterStoreHookFn = (ctx: AfterStoreContext) => void | Promise<void>;

package/dist/@types/db-types.d.ts

@@ -424,6 +424,32 @@ export interface ICounterCommands {
      * and deletes. The facet-URL use case does not require gapless IDs.
      */
     nextCounterValue(groupName: string): Promise<number>;
+    /**
+     * Atomically allocate the next value from a **runtime-scoped** counter
+     * group, self-registering the group on first use.
+     *
+     * The schema-declared counter mechanism above is deliberately static:
+     * groups come from `CounterField.group` strings, are discovered and
+     * registered once at boot, and `nextCounterValue` throws for anything
+     * unregistered — that honesty catches configuration bugs. But some
+     * sequences are keyed on *data* that only exists at runtime — e.g. a
+     * per-document sub-sequence like "files attached to publication X",
+     * where each value must be unique and never reused within that scope
+     * (`publications:<documentId>:files` → 1, 2, 3, …). Those scopes cannot
+     * be known at boot, so this method performs an idempotent
+     * ensure-then-allocate instead of throwing on the first use.
+     *
+     * Semantics are otherwise identical to `nextCounterValue`: values are
+     * monotonic per scope and never reused (a Postgres SEQUENCE per scope
+     * in the Postgres adapter); gaps are expected on rolled-back or
+     * abandoned work.
+     *
+     * Callers own the scope-name namespace. Use a stable, collision-proof
+     * convention — `'<collectionPath>:<documentId>:<purpose>'` is
+     * recommended — and never derive scope names from mutable data
+     * (renaming a scope starts a fresh sequence at 1).
+     */
+    nextScopedCounterValue(scopeName: string): Promise<number>;
 }
 export interface ICollectionCommands {
     /**

package/dist/@types/storage-types.d.ts

@@ -97,4 +97,25 @@ export interface IStorageProvider {
      * signing logic here.
      */
     getUrl(storagePath: string): string;
+    /**
+     * Move (re-key) a previously stored file from one `storage_path` to
+     * another, returning the new location metadata. The destination path is
+     * written verbatim — same contract as `UploadFileOptions.targetStoragePath`
+     * (POSIX-style, no leading slash; the caller owns sanitisation and
+     * collision avoidance). Throws if the source does not exist.
+     *
+     * **Optional capability** — both first-party providers (`storage-local`,
+     * `storage-s3`) implement it, but custom providers may not. Callers must
+     * feature-detect (`if (storage.move) …`) before relying on it.
+     */
+    move?(fromPath: string, toPath: string): Promise<StoredFileLocation>;
+    /**
+     * Report whether a file exists at the given `storage_path`. Useful for
+     * collision checks when callers (e.g. `beforeStore` hooks assigning
+     * explicit storage keys via `{ storagePath }`) need to guarantee a key
+     * is free before claiming it.
+     *
+     * **Optional capability** — see `move`.
+     */
+    exists?(storagePath: string): Promise<boolean>;
 }

package/dist/services/assign-counter-values.test.node.js

@@ -20,6 +20,7 @@ function makeCounters(start = 1) {
                 calls.push(group);
                 return next++;
             }),
+            nextScopedCounterValue: vi.fn(),
         },
         calls,
     };

package/dist/services/collection-bootstrap.test.node.js

@@ -52,6 +52,7 @@ function createMockDb(options) {
             counters: {
                 ensureCounterGroup: vi.fn(fail),
                 nextCounterValue: vi.fn(fail),
+                nextScopedCounterValue: vi.fn(fail),
             },
         },
         queries: {
@@ -203,6 +204,7 @@ describe('ensureCollections', () => {
                 counters: {
                     ensureCounterGroup: vi.fn(),
                     nextCounterValue: vi.fn(),
+                    nextScopedCounterValue: vi.fn(),
                 },
             },
             queries: {

package/dist/services/discover-counter-groups.test.node.js

@@ -37,6 +37,7 @@ function makeAdapter(options) {
             counters: {
                 ensureCounterGroup,
                 nextCounterValue: vi.fn(fail),
+                nextScopedCounterValue: vi.fn(fail),
             },
         },
         queries: {

package/dist/services/document-lifecycle.test.node.js

@@ -63,6 +63,7 @@ function createMockDb() {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
             audit: { append: auditAppend },
         },

package/dist/services/field-upload.js

@@ -69,18 +69,22 @@ function normalizeUploadHook(hook) {
 }
 /**
  * Run the `beforeStore` chain. Each function receives the previous
- * function's filename override (fold). A function may:
+ * function's filename / storage-path overrides (fold). A function may:
  *
  *   - return a string or `{ filename }` to substitute a new filename;
+ *   - return `{ storagePath }` to take full control of the storage key
+ *     (bypasses provider key derivation — no UUID prefix). When set
+ *     without `filename`, the filename defaults to the path's basename;
  *   - return `{ error }` to short-circuit with `ERR_VALIDATION`;
- *   - return `void` / `undefined` to leave the filename unchanged.
+ *   - return `void` / `undefined` to leave current values unchanged.
  *
- * Returns the resolved filename.
+ * Returns the resolved filename and optional storage path.
  */
 async function runBeforeStoreChain(hooks, ctx, logger) {
     let effective = ctx.filename;
+    let effectiveStoragePath;
     for (const fn of hooks) {
-        const result = await fn({ ...ctx, filename: effective });
+        const result = await fn({ ...ctx, filename: effective, storagePath: effectiveStoragePath });
         if (result == null)
             continue;
         if (typeof result === 'string') {
@@ -96,14 +100,35 @@ async function runBeforeStoreChain(hooks, ctx, logger) {
                     details: { collectionPath: ctx.collectionPath, fieldName: ctx.fieldName },
                 }, runBeforeStoreChain).log(logger);
             }
+            let filenameOverridden = false;
             if ('filename' in result && typeof result.filename === 'string') {
                 const trimmed = result.filename.trim();
-                if (trimmed)
+                if (trimmed) {
                     effective = trimmed;
+                    filenameOverridden = true;
+                }
+            }
+            if ('storagePath' in result && typeof result.storagePath === 'string') {
+                // Normalise: POSIX-style, no leading slash (matches the
+                // UploadFileOptions.targetStoragePath contract).
+                const trimmed = result.storagePath.trim().replace(/^\/+/, '');
+                if (trimmed) {
+                    effectiveStoragePath = trimmed;
+                    // Keep the stored filename in sync with the explicit key
+                    // unless the hook also set filename itself.
+                    if (!filenameOverridden) {
+                        effective = posixBasename(trimmed);
+                    }
+                }
             }
         }
     }
-    return effective;
+    return { filename: effective, storagePath: effectiveStoragePath };
+}
+/** Last path segment of a POSIX-style storage path. */
+function posixBasename(storagePath) {
+    const idx = storagePath.lastIndexOf('/');
+    return idx === -1 ? storagePath : storagePath.slice(idx + 1);
 }
 export async function uploadField(ctx, params) {
     return withLogContext({ domain: 'services', module: 'upload', function: 'uploadField' }, async () => {
@@ -163,7 +188,7 @@ export async function uploadField(ctx, params) {
         // graphs out of the client bundle; the inline form returns as-is.
         const uploadHooks = await resolveUploadHooks(upload.hooks);
         const beforeStoreHooks = normalizeUploadHook(uploadHooks?.beforeStore);
-        const effectiveFilename = await runBeforeStoreChain(beforeStoreHooks, {
+        const { filename: effectiveFilename, storagePath: effectiveStoragePath } = await runBeforeStoreChain(beforeStoreHooks, {
             fieldName,
             field,
             filename: sanitised,
@@ -176,9 +201,14 @@ export async function uploadField(ctx, params) {
                 requestId: '',
                 readMode: 'any',
             },
+            storage,
         }, logger);
         // -- Storage write. Filename is the post-hook value, so generated
-        //    variants automatically inherit the new prefix.
+        //    variants automatically inherit the new prefix. An explicit
+        //    `storagePath` from the chain is threaded through as
+        //    `targetStoragePath`, which providers write verbatim (no UUID
+        //    prefix / key derivation) — variants still derive sibling paths
+        //    from the resulting `storedFile.storagePath`.
         let storedFile;
         try {
             storedFile = await storage.upload(buffer, {
@@ -186,6 +216,7 @@ export async function uploadField(ctx, params) {
                 mimeType,
                 size: fileSize,
                 collection: collectionPath,
+                ...(effectiveStoragePath !== undefined && { targetStoragePath: effectiveStoragePath }),
             });
         }
         catch (err) {
@@ -261,6 +292,7 @@ export async function uploadField(ctx, params) {
                         requestId: '',
                         readMode: 'any',
                     },
+                    storage,
                 };
                 await fn(afterCtx);
             }

package/dist/services/field-upload.test.node.js

@@ -66,6 +66,7 @@ function createMockDb() {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
         },
         queries: {
@@ -248,6 +249,84 @@ describe('uploadField service', () => {
         });
         expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ filename: 'PUB-42-tenant-hero.png' }));
     });
+    it('beforeStore { storagePath } threads targetStoragePath verbatim and derives the filename from its basename', async () => {
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: () => ({ storagePath: 'publications/forru-0000447-0001-en.png' }),
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        // Explicit key is handed to the provider verbatim — no UUID prefix,
+        // no collection-derived key.
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
+            targetStoragePath: 'publications/forru-0000447-0001-en.png',
+            filename: 'forru-0000447-0001-en.png',
+        }));
+        // Stored filename follows the explicit key's basename.
+        expect(result.storedFile.filename).toBe('forru-0000447-0001-en.png');
+    });
+    it('beforeStore { storagePath, filename } honours both; a leading slash is stripped from the key', async () => {
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: () => ({
+                    storagePath: '/publications/forru-0000447-0002-en.png',
+                    filename: 'display-name.png',
+                }),
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
+            targetStoragePath: 'publications/forru-0000447-0002-en.png',
+            filename: 'display-name.png',
+        }));
+        expect(result.storedFile.filename).toBe('display-name.png');
+    });
+    it('folds storagePath through a chain — later hooks see ctx.storagePath and may override it', async () => {
+        const secondHook = vi.fn(({ storagePath }) => ({
+            storagePath: storagePath.replace('-draft', ''),
+        }));
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: [() => ({ storagePath: 'publications/report-draft.png' }), secondHook],
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(secondHook).toHaveBeenCalledWith(expect.objectContaining({ storagePath: 'publications/report-draft.png' }));
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ targetStoragePath: 'publications/report.png' }));
+    });
+    it('no storagePath override → storage.upload receives no targetStoragePath', async () => {
+        const { ctx, upload } = buildCtx();
+        await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        const options = upload.mock.calls[0]?.[1];
+        expect(options).not.toHaveProperty('targetStoragePath');
+    });
     it('beforeStore { error } short-circuits — no storage write, no variants, no afterStore', async () => {
         const afterStore = vi.fn();
         const definition = withFieldUpload(uploadCollection, 'image', (f) => {

package/dist/services/populate.test.node.js

@@ -154,6 +154,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
         },
         queries: {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -76,7 +76,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "3.18.0"
+    "@byline/auth": "3.19.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",