@byline/admin 4.4.1 → 4.6.0

package/dist/modules/admin-preferences/commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Transport-agnostic commands for per-user admin preferences.
+ *
+ * Same self-service posture as admin-account: `auth` is
+ * `{ authenticated: true }` (no ability key), and the security property
+ * "you may only touch your own preferences" is structural — the target
+ * id comes from `actor.id`, never from the request payload.
+ */
+import { type Command } from '../../lib/create-command.js';
+import type { AdminStore } from '../../store.js';
+import type { GetPreferenceRequest, PreferenceResponse, SetPreferenceRequest } from './schemas.js';
+export interface AdminPreferencesCommandDeps {
+    store: AdminStore;
+}
+export declare const getPreferenceCommand: Command<GetPreferenceRequest, PreferenceResponse, AdminPreferencesCommandDeps>;
+export declare const setPreferenceCommand: Command<SetPreferenceRequest, PreferenceResponse, AdminPreferencesCommandDeps>;

package/dist/modules/admin-preferences/commands.js

@@ -0,0 +1,31 @@
+import { createCommand } from "../../lib/create-command.js";
+import { getPreferenceRequestSchema, preferenceResponseSchema, setPreferenceRequestSchema } from "./schemas.js";
+import { AdminPreferencesService } from "./service.js";
+function serviceOf(deps) {
+    return new AdminPreferencesService({
+        repo: deps.store.adminPreferences
+    });
+}
+const getPreferenceCommand = createCommand({
+    method: 'getPreference',
+    auth: {
+        authenticated: true
+    },
+    schemas: {
+        input: getPreferenceRequestSchema,
+        output: preferenceResponseSchema
+    },
+    handler: ({ input, deps, actor })=>serviceOf(deps).getPreference(actor.id, input.scope)
+});
+const setPreferenceCommand = createCommand({
+    method: 'setPreference',
+    auth: {
+        authenticated: true
+    },
+    schemas: {
+        input: setPreferenceRequestSchema,
+        output: preferenceResponseSchema
+    },
+    handler: ({ input, deps, actor })=>serviceOf(deps).setPreference(actor.id, input.scope, input.value)
+});
+export { getPreferenceCommand, setPreferenceCommand };

package/dist/modules/admin-preferences/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * `@byline/admin/admin-preferences` — scoped per-user key-value
+ * preferences for the currently signed-in admin user.
+ *
+ * Self-service like `@byline/admin/admin-account`: the actor IS the
+ * target, and there is no ability gate — authn-only. The `scope` string
+ * (e.g. `collections.docs.list`) is the generality lever: new admin
+ * surfaces claim their own scopes with no schema change.
+ */
+export { getPreferenceCommand, setPreferenceCommand } from './commands.js';
+export { getPreferenceRequestSchema, listViewPreferenceValueSchema, preferenceResponseSchema, preferenceScopeSchema, setPreferenceRequestSchema, } from './schemas.js';
+export { AdminPreferencesService } from './service.js';
+export type { AdminPreferencesCommandDeps } from './commands.js';
+export type { AdminPreferencesRepository, AdminUserPreferenceRow, } from './repository.js';
+export type { GetPreferenceRequest, PreferenceResponse, SetPreferenceRequest, } from './schemas.js';

package/dist/modules/admin-preferences/index.js

@@ -0,0 +1,3 @@
+export { getPreferenceCommand, setPreferenceCommand } from "./commands.js";
+export { getPreferenceRequestSchema, listViewPreferenceValueSchema, preferenceResponseSchema, preferenceScopeSchema, setPreferenceRequestSchema } from "./schemas.js";
+export { AdminPreferencesService } from "./service.js";

package/dist/modules/admin-preferences/repository.d.ts

@@ -0,0 +1,35 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * `AdminPreferencesRepository` — the DB-adapter-facing contract for the
+ * `byline_admin_user_preferences` table: a scoped per-user key-value
+ * store. One row per (user, scope); `value` is a JSONB object whose
+ * shape is owned by the scope's feature (validated at the command
+ * layer, not here).
+ *
+ * Adapters (e.g. `@byline/db-postgres`) implement this interface; the
+ * admin-preferences service consumes it via the `AdminStore` bundle.
+ */
+export interface AdminUserPreferenceRow {
+    user_id: string;
+    scope: string;
+    value: Record<string, unknown>;
+    created_at: Date;
+    updated_at: Date;
+}
+export interface AdminPreferencesRepository {
+    /** `null` when the user has no row for the scope. */
+    get(userId: string, scope: string): Promise<AdminUserPreferenceRow | null>;
+    /**
+     * Insert-or-merge. On conflict the JSONB `patch` is merged into the
+     * stored value **per key** (`value || patch`), so writing
+     * `{ page_size }` preserves a previously stored `order`/`desc`.
+     * Vid-less — preferences are last-writer-wins by design.
+     */
+    upsert(userId: string, scope: string, patch: Record<string, unknown>): Promise<AdminUserPreferenceRow>;
+}

package/dist/modules/admin-preferences/repository.js

@@ -0,0 +1 @@
+export { };

package/dist/modules/admin-preferences/schemas.d.ts

@@ -0,0 +1,50 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Zod schemas for the admin-preferences commands.
+ *
+ * Self-service, like admin-account: none of the request schemas accept a
+ * user id — the command resolves the target from `actor.id`.
+ *
+ * The `value` payload is validated against the list-view shape because
+ * that is the only registered scope family today
+ * (`collections.<path>.list`). When a second scope family arrives, this
+ * becomes a scope-keyed selection of value schemas.
+ */
+import { z } from 'zod';
+/** Dot-separated segment key, e.g. `collections.docs.list`. */
+export declare const preferenceScopeSchema: z.ZodString;
+/**
+ * Sticky list-view keys. All optional — clients send only the keys the
+ * interaction changed, and the repository merges per-key — but an empty
+ * object is rejected (nothing to write).
+ */
+export declare const listViewPreferenceValueSchema: z.ZodObject<{
+    page_size: z.ZodOptional<z.ZodNumber>;
+    order: z.ZodOptional<z.ZodString>;
+    desc: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const getPreferenceRequestSchema: z.ZodObject<{
+    scope: z.ZodString;
+}, z.core.$strip>;
+export type GetPreferenceRequest = z.infer<typeof getPreferenceRequestSchema>;
+export declare const setPreferenceRequestSchema: z.ZodObject<{
+    scope: z.ZodString;
+    value: z.ZodObject<{
+        page_size: z.ZodOptional<z.ZodNumber>;
+        order: z.ZodOptional<z.ZodString>;
+        desc: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+}, z.core.$strip>;
+export type SetPreferenceRequest = z.infer<typeof setPreferenceRequestSchema>;
+/** `value` is `null` when the user has no stored preference for the scope. */
+export declare const preferenceResponseSchema: z.ZodObject<{
+    scope: z.ZodString;
+    value: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PreferenceResponse = z.infer<typeof preferenceResponseSchema>;

package/dist/modules/admin-preferences/schemas.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+const preferenceScopeSchema = z.string().min(1).max(255).regex(/^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/i, {
+    message: 'scope must be dot-separated segments of [a-z0-9_-]'
+});
+const listViewPreferenceValueSchema = z.object({
+    page_size: z.number().int().min(1).max(100).optional(),
+    order: z.string().min(1).max(255).optional(),
+    desc: z.boolean().optional()
+}).strict().refine((v)=>Object.keys(v).length > 0, {
+    message: 'value cannot be empty'
+});
+const getPreferenceRequestSchema = z.object({
+    scope: preferenceScopeSchema
+});
+const setPreferenceRequestSchema = z.object({
+    scope: preferenceScopeSchema,
+    value: listViewPreferenceValueSchema
+});
+const preferenceResponseSchema = z.object({
+    scope: z.string(),
+    value: z.record(z.string(), z.unknown()).nullable()
+});
+export { getPreferenceRequestSchema, listViewPreferenceValueSchema, preferenceResponseSchema, preferenceScopeSchema, setPreferenceRequestSchema };

package/dist/modules/admin-preferences/schemas.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/admin-preferences/service.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Self-service business logic for per-user admin preferences. Every
+ * method takes `actorId` sourced server-side from the authenticated
+ * `RequestContext` — callers cannot supply a target user id.
+ */
+import type { AdminPreferencesRepository } from './repository.js';
+import type { PreferenceResponse } from './schemas.js';
+export declare class AdminPreferencesService {
+    #private;
+    constructor(deps: {
+        repo: AdminPreferencesRepository;
+    });
+    getPreference(actorId: string, scope: string): Promise<PreferenceResponse>;
+    setPreference(actorId: string, scope: string, patch: Record<string, unknown>): Promise<PreferenceResponse>;
+}

package/dist/modules/admin-preferences/service.js

@@ -0,0 +1,56 @@
+function _check_private_redeclaration(obj, privateCollection) {
+    if (privateCollection.has(obj)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+function _class_apply_descriptor_get(receiver, descriptor) {
+    if (descriptor.get) return descriptor.get.call(receiver);
+    return descriptor.value;
+}
+function _class_apply_descriptor_set(receiver, descriptor, value) {
+    if (descriptor.set) descriptor.set.call(receiver, value);
+    else {
+        if (!descriptor.writable) throw new TypeError("attempted to set read only private field");
+        descriptor.value = value;
+    }
+}
+function _class_extract_field_descriptor(receiver, privateMap, action) {
+    if (!privateMap.has(receiver)) throw new TypeError("attempted to " + action + " private field on non-instance");
+    return privateMap.get(receiver);
+}
+function _class_private_field_get(receiver, privateMap) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "get");
+    return _class_apply_descriptor_get(receiver, descriptor);
+}
+function _class_private_field_init(obj, privateMap, value) {
+    _check_private_redeclaration(obj, privateMap);
+    privateMap.set(obj, value);
+}
+function _class_private_field_set(receiver, privateMap, value) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "set");
+    _class_apply_descriptor_set(receiver, descriptor, value);
+    return value;
+}
+var _repo = /*#__PURE__*/ new WeakMap();
+class AdminPreferencesService {
+    async getPreference(actorId, scope) {
+        const row = await _class_private_field_get(this, _repo).get(actorId, scope);
+        return {
+            scope,
+            value: row?.value ?? null
+        };
+    }
+    async setPreference(actorId, scope, patch) {
+        const row = await _class_private_field_get(this, _repo).upsert(actorId, scope, patch);
+        return {
+            scope,
+            value: row.value
+        };
+    }
+    constructor(deps){
+        _class_private_field_init(this, _repo, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_set(this, _repo, deps.repo);
+    }
+}
+export { AdminPreferencesService };

package/dist/store.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { AdminPermissionsRepository } from './modules/admin-permissions/repository.js';
+import type { AdminPreferencesRepository } from './modules/admin-preferences/repository.js';
 import type { AdminRolesRepository } from './modules/admin-roles/repository.js';
 import type { AdminUsersRepository } from './modules/admin-users/repository.js';
 import type { RefreshTokensRepository } from './modules/auth/refresh-tokens-repository.js';
@@ -18,7 +19,7 @@ import type { RefreshTokensRepository } from './modules/auth/refresh-tokens-repo
  * `JwtSessionProvider`, to `seedSuperAdmin`, and (later) to admin-user
  * and admin-role commands.
  *
- * Keeping the four repositories together as a single argument avoids
+ * Keeping the five repositories together as a single argument avoids
  * exploding constructor signatures and makes "needs admin DB access" a
  * single, recognisable type.
  */
@@ -27,4 +28,5 @@ export interface AdminStore {
     adminRoles: AdminRolesRepository;
     adminPermissions: AdminPermissionsRepository;
     refreshTokens: RefreshTokensRepository;
+    adminPreferences: AdminPreferencesRepository;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.4.1",
+  "version": "4.6.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -72,6 +72,11 @@
       "import": "./dist/modules/admin-account/index.js",
       "require": "./dist/modules/admin-account/index.js"
     },
+    "./admin-preferences": {
+      "types": "./dist/modules/admin-preferences/index.d.ts",
+      "import": "./dist/modules/admin-preferences/index.js",
+      "require": "./dist/modules/admin-preferences/index.js"
+    },
     "./services": {
       "types": "./dist/services/admin-services-context.d.ts",
       "import": "./dist/services/admin-services-context.js",
@@ -168,10 +173,10 @@
     "react-diff-viewer-continued": "^4.4.0",
     "uuid": "^14.0.1",
     "zod": "^4.4.3",
-    "@byline/auth": "4.4.1",
-    "@byline/ui": "4.4.1",
-    "@byline/i18n": "4.4.1",
-    "@byline/core": "4.4.1"
+    "@byline/auth": "4.6.0",
+    "@byline/ui": "4.6.0",
+    "@byline/core": "4.6.0",
+    "@byline/i18n": "4.6.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/modules/admin-preferences/commands.ts

@@ -0,0 +1,57 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Transport-agnostic commands for per-user admin preferences.
+ *
+ * Same self-service posture as admin-account: `auth` is
+ * `{ authenticated: true }` (no ability key), and the security property
+ * "you may only touch your own preferences" is structural — the target
+ * id comes from `actor.id`, never from the request payload.
+ */
+
+import { type Command, createCommand } from '../../lib/create-command.js'
+import {
+  getPreferenceRequestSchema,
+  preferenceResponseSchema,
+  setPreferenceRequestSchema,
+} from './schemas.js'
+import { AdminPreferencesService } from './service.js'
+import type { AdminStore } from '../../store.js'
+import type { GetPreferenceRequest, PreferenceResponse, SetPreferenceRequest } from './schemas.js'
+
+export interface AdminPreferencesCommandDeps {
+  store: AdminStore
+}
+
+function serviceOf(deps: AdminPreferencesCommandDeps): AdminPreferencesService {
+  return new AdminPreferencesService({ repo: deps.store.adminPreferences })
+}
+
+export const getPreferenceCommand: Command<
+  GetPreferenceRequest,
+  PreferenceResponse,
+  AdminPreferencesCommandDeps
+> = createCommand({
+  method: 'getPreference',
+  auth: { authenticated: true },
+  schemas: { input: getPreferenceRequestSchema, output: preferenceResponseSchema },
+  handler: ({ input, deps, actor }) => serviceOf(deps).getPreference(actor.id, input.scope),
+})
+
+export const setPreferenceCommand: Command<
+  SetPreferenceRequest,
+  PreferenceResponse,
+  AdminPreferencesCommandDeps
+> = createCommand({
+  method: 'setPreference',
+  auth: { authenticated: true },
+  schemas: { input: setPreferenceRequestSchema, output: preferenceResponseSchema },
+  handler: ({ input, deps, actor }) =>
+    serviceOf(deps).setPreference(actor.id, input.scope, input.value),
+})

package/src/modules/admin-preferences/index.ts

@@ -0,0 +1,37 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/admin/admin-preferences` — scoped per-user key-value
+ * preferences for the currently signed-in admin user.
+ *
+ * Self-service like `@byline/admin/admin-account`: the actor IS the
+ * target, and there is no ability gate — authn-only. The `scope` string
+ * (e.g. `collections.docs.list`) is the generality lever: new admin
+ * surfaces claim their own scopes with no schema change.
+ */
+
+export { getPreferenceCommand, setPreferenceCommand } from './commands.js'
+export {
+  getPreferenceRequestSchema,
+  listViewPreferenceValueSchema,
+  preferenceResponseSchema,
+  preferenceScopeSchema,
+  setPreferenceRequestSchema,
+} from './schemas.js'
+export { AdminPreferencesService } from './service.js'
+export type { AdminPreferencesCommandDeps } from './commands.js'
+export type {
+  AdminPreferencesRepository,
+  AdminUserPreferenceRow,
+} from './repository.js'
+export type {
+  GetPreferenceRequest,
+  PreferenceResponse,
+  SetPreferenceRequest,
+} from './schemas.js'

package/src/modules/admin-preferences/repository.ts

@@ -0,0 +1,42 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `AdminPreferencesRepository` — the DB-adapter-facing contract for the
+ * `byline_admin_user_preferences` table: a scoped per-user key-value
+ * store. One row per (user, scope); `value` is a JSONB object whose
+ * shape is owned by the scope's feature (validated at the command
+ * layer, not here).
+ *
+ * Adapters (e.g. `@byline/db-postgres`) implement this interface; the
+ * admin-preferences service consumes it via the `AdminStore` bundle.
+ */
+
+export interface AdminUserPreferenceRow {
+  user_id: string
+  scope: string
+  value: Record<string, unknown>
+  created_at: Date
+  updated_at: Date
+}
+
+export interface AdminPreferencesRepository {
+  /** `null` when the user has no row for the scope. */
+  get(userId: string, scope: string): Promise<AdminUserPreferenceRow | null>
+  /**
+   * Insert-or-merge. On conflict the JSONB `patch` is merged into the
+   * stored value **per key** (`value || patch`), so writing
+   * `{ page_size }` preserves a previously stored `order`/`desc`.
+   * Vid-less — preferences are last-writer-wins by design.
+   */
+  upsert(
+    userId: string,
+    scope: string,
+    patch: Record<string, unknown>
+  ): Promise<AdminUserPreferenceRow>
+}

package/src/modules/admin-preferences/schemas.test.node.ts

@@ -0,0 +1,67 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  listViewPreferenceValueSchema,
+  preferenceScopeSchema,
+  setPreferenceRequestSchema,
+} from './schemas.js'
+
+describe('preferenceScopeSchema', () => {
+  it('accepts dot-separated scope keys', () => {
+    expect(preferenceScopeSchema.safeParse('collections.docs.list').success).toBe(true)
+    expect(preferenceScopeSchema.safeParse('collections.media-items.list').success).toBe(true)
+  })
+
+  it('rejects empty, spaced, and slash-separated keys', () => {
+    expect(preferenceScopeSchema.safeParse('').success).toBe(false)
+    expect(preferenceScopeSchema.safeParse('has space').success).toBe(false)
+    expect(preferenceScopeSchema.safeParse('a/b').success).toBe(false)
+  })
+})
+
+describe('listViewPreferenceValueSchema', () => {
+  it('accepts a page_size-only payload (partial writes are the norm)', () => {
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 50 }).success).toBe(true)
+  })
+
+  it('accepts a sort-only payload', () => {
+    expect(listViewPreferenceValueSchema.safeParse({ order: 'title', desc: true }).success).toBe(
+      true
+    )
+  })
+
+  it('enforces the 1-100 page_size bounds', () => {
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 0 }).success).toBe(false)
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 101 }).success).toBe(false)
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 12.5 }).success).toBe(false)
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 1 }).success).toBe(true)
+    expect(listViewPreferenceValueSchema.safeParse({ page_size: 100 }).success).toBe(true)
+  })
+
+  it('rejects an empty payload and unknown keys', () => {
+    expect(listViewPreferenceValueSchema.safeParse({}).success).toBe(false)
+    expect(listViewPreferenceValueSchema.safeParse({ page: 7 }).success).toBe(false)
+  })
+})
+
+describe('setPreferenceRequestSchema', () => {
+  it('requires both scope and a non-empty value', () => {
+    expect(
+      setPreferenceRequestSchema.safeParse({
+        scope: 'collections.docs.list',
+        value: { page_size: 30 },
+      }).success
+    ).toBe(true)
+    expect(
+      setPreferenceRequestSchema.safeParse({ scope: 'collections.docs.list', value: {} }).success
+    ).toBe(false)
+  })
+})

package/src/modules/admin-preferences/schemas.ts

@@ -0,0 +1,62 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Zod schemas for the admin-preferences commands.
+ *
+ * Self-service, like admin-account: none of the request schemas accept a
+ * user id — the command resolves the target from `actor.id`.
+ *
+ * The `value` payload is validated against the list-view shape because
+ * that is the only registered scope family today
+ * (`collections.<path>.list`). When a second scope family arrives, this
+ * becomes a scope-keyed selection of value schemas.
+ */
+
+import { z } from 'zod'
+
+/** Dot-separated segment key, e.g. `collections.docs.list`. */
+export const preferenceScopeSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/i, {
+    message: 'scope must be dot-separated segments of [a-z0-9_-]',
+  })
+
+/**
+ * Sticky list-view keys. All optional — clients send only the keys the
+ * interaction changed, and the repository merges per-key — but an empty
+ * object is rejected (nothing to write).
+ */
+export const listViewPreferenceValueSchema = z
+  .object({
+    page_size: z.number().int().min(1).max(100).optional(),
+    order: z.string().min(1).max(255).optional(),
+    desc: z.boolean().optional(),
+  })
+  .strict()
+  .refine((v) => Object.keys(v).length > 0, { message: 'value cannot be empty' })
+
+export const getPreferenceRequestSchema = z.object({
+  scope: preferenceScopeSchema,
+})
+export type GetPreferenceRequest = z.infer<typeof getPreferenceRequestSchema>
+
+export const setPreferenceRequestSchema = z.object({
+  scope: preferenceScopeSchema,
+  value: listViewPreferenceValueSchema,
+})
+export type SetPreferenceRequest = z.infer<typeof setPreferenceRequestSchema>
+
+/** `value` is `null` when the user has no stored preference for the scope. */
+export const preferenceResponseSchema = z.object({
+  scope: z.string(),
+  value: z.record(z.string(), z.unknown()).nullable(),
+})
+export type PreferenceResponse = z.infer<typeof preferenceResponseSchema>

package/src/modules/admin-preferences/service.ts

@@ -0,0 +1,38 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Self-service business logic for per-user admin preferences. Every
+ * method takes `actorId` sourced server-side from the authenticated
+ * `RequestContext` — callers cannot supply a target user id.
+ */
+
+import type { AdminPreferencesRepository } from './repository.js'
+import type { PreferenceResponse } from './schemas.js'
+
+export class AdminPreferencesService {
+  readonly #repo: AdminPreferencesRepository
+
+  constructor(deps: { repo: AdminPreferencesRepository }) {
+    this.#repo = deps.repo
+  }
+
+  async getPreference(actorId: string, scope: string): Promise<PreferenceResponse> {
+    const row = await this.#repo.get(actorId, scope)
+    return { scope, value: row?.value ?? null }
+  }
+
+  async setPreference(
+    actorId: string,
+    scope: string,
+    patch: Record<string, unknown>
+  ): Promise<PreferenceResponse> {
+    const row = await this.#repo.upsert(actorId, scope, patch)
+    return { scope, value: row.value }
+  }
+}

package/src/store.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AdminPermissionsRepository } from './modules/admin-permissions/repository.js'
+import type { AdminPreferencesRepository } from './modules/admin-preferences/repository.js'
 import type { AdminRolesRepository } from './modules/admin-roles/repository.js'
 import type { AdminUsersRepository } from './modules/admin-users/repository.js'
 import type { RefreshTokensRepository } from './modules/auth/refresh-tokens-repository.js'
@@ -20,7 +21,7 @@ import type { RefreshTokensRepository } from './modules/auth/refresh-tokens-repo
  * `JwtSessionProvider`, to `seedSuperAdmin`, and (later) to admin-user
  * and admin-role commands.
  *
- * Keeping the four repositories together as a single argument avoids
+ * Keeping the five repositories together as a single argument avoids
  * exploding constructor signatures and makes "needs admin DB access" a
  * single, recognisable type.
  */
@@ -29,4 +30,5 @@ export interface AdminStore {
   adminRoles: AdminRolesRepository
   adminPermissions: AdminPermissionsRepository
   refreshTokens: RefreshTokensRepository
+  adminPreferences: AdminPreferencesRepository
 }