@byline/admin 1.9.1 → 1.10.0

package/dist/index.d.ts

@@ -22,6 +22,7 @@
  */
 export { registerAdminAbilities } from './abilities.js';
 export { assertAdminActor, requireAdminActor } from './lib/assert-admin-actor.js';
+export { type Command, type CreateCommandAuthSpec, type CreateCommandHandlerArgs, type CreateCommandSpec, createCommand, } from './lib/create-command.js';
 export * from './modules/admin-account/index.js';
 export * from './modules/admin-permissions/index.js';
 export * from './modules/admin-roles/index.js';

package/dist/index.js

@@ -22,6 +22,7 @@
  */
 export { registerAdminAbilities } from './abilities.js';
 export { assertAdminActor, requireAdminActor } from './lib/assert-admin-actor.js';
+export { createCommand, } from './lib/create-command.js';
 export * from './modules/admin-account/index.js';
 export * from './modules/admin-permissions/index.js';
 export * from './modules/admin-roles/index.js';

package/dist/lib/create-command.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 type { AdminAuth, RequestContext } from '@byline/auth';
+import type { ZodType } from 'zod';
+/**
+ * `createCommand` — the wrapper that folds the four-step admin command
+ * contract (validate → authorise → invoke → shape) into a single
+ * declaration.
+ *
+ * Implements Phase 1 of `docs/CORE-COMPOSITION.md`. Today's scope is
+ * `@byline/admin`-internal: it gates against admin actor identity using
+ * the existing `assertAdminActor` / `requireAdminActor` helpers, which
+ * inherit the super-admin bypass from `AdminAuth.assertAbility`.
+ *
+ * The `auth` slot is a discriminated union:
+ *
+ *   - `{ ability }`         — full admin gate. Requires an `AdminAuth`
+ *                             actor holding the named ability. Maps to
+ *                             `assertAdminActor`.
+ *   - `{ authenticated }`   — identity gate only. Requires an `AdminAuth`
+ *                             actor but does not assert any ability. Used
+ *                             by self-service commands in `admin-account`
+ *                             where the security property is "you may
+ *                             only mutate your own row" and the target
+ *                             id is sourced from `actor.id`.
+ *
+ * The handler receives an args object so it can cherry-pick what it
+ * needs without positional ordering — `context` for downstream calls
+ * that need the full request context, `input` (already Zod-parsed),
+ * `deps` (typed by the module), and `actor` (already narrowed to
+ * `AdminAuth` by the auth step).
+ *
+ * The returned command preserves today's `(context, input, deps) =>
+ * Promise<Output>` signature so existing server-fn call sites keep
+ * working without change.
+ *
+ * Collection-document operations (create / update / delete / status /
+ * upload) are gated through a separate helper, `assertActorCanPerform`,
+ * which fires inside the `document-lifecycle` service functions in
+ * `@byline/core`. They do not flow through this wrapper today; if the
+ * two enforcement paths ever converge, the `auth` discriminator can
+ * grow a `collection` variant without breaking existing call sites.
+ */
+export type CreateCommandAuthSpec = {
+    readonly ability: string;
+    readonly authenticated?: never;
+} | {
+    readonly authenticated: true;
+    readonly ability?: never;
+};
+export interface CreateCommandHandlerArgs<TInput, TDeps> {
+    readonly context: RequestContext;
+    readonly input: TInput;
+    readonly deps: TDeps;
+    readonly actor: AdminAuth;
+}
+export interface CreateCommandSpec<TInput, TOutput, TDeps> {
+    /**
+     * Stable identifier for the command, used in error messages and
+     * future telemetry (Phase 1 of `CORE-COMPOSITION.md` calls out
+     * uniform logging as a downstream benefit of the wrapper).
+     */
+    readonly method: string;
+    readonly auth: CreateCommandAuthSpec;
+    readonly schemas: {
+        readonly input: ZodType<TInput>;
+        readonly output: ZodType<TOutput>;
+    };
+    readonly handler: (args: CreateCommandHandlerArgs<TInput, TDeps>) => Promise<TOutput> | TOutput;
+}
+export type Command<_TInput, TOutput, TDeps> = (context: RequestContext | undefined, input: unknown, deps: TDeps) => Promise<TOutput>;
+export declare function createCommand<TInput, TOutput, TDeps>(spec: CreateCommandSpec<TInput, TOutput, TDeps>): Command<TInput, TOutput, TDeps>;

package/dist/lib/create-command.js

@@ -0,0 +1,25 @@
+/**
+ * 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 { assertAdminActor, requireAdminActor } from './assert-admin-actor.js';
+export function createCommand(spec) {
+    return async function command(context, input, deps) {
+        const parsed = spec.schemas.input.parse(input ?? {});
+        const actor = spec.auth.ability !== undefined
+            ? assertAdminActor(context, spec.auth.ability)
+            : requireAdminActor(context, spec.method);
+        // `context` is non-null after the auth step — both helpers throw
+        // `ERR_UNAUTHENTICATED` when the request context is missing.
+        const result = await spec.handler({
+            context: context,
+            input: parsed,
+            deps,
+            actor,
+        });
+        return spec.schemas.output.parse(result);
+    };
+}

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

@@ -5,25 +5,23 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { RequestContext } from '@byline/auth';
+import { type Command } from '../../lib/create-command.js';
 import type { AdminStore } from '../../store.js';
-import type { AccountResponse } from './schemas.js';
+import type { AccountResponse, ChangeAccountPasswordRequest, GetAccountRequest, UpdateAccountRequest } from './schemas.js';
 /**
  * Transport-agnostic commands for admin-account self-service.
  *
- * Same shape as the other admin module commands (`*-users`, `*-roles`,
- * `*-permissions`) with one deliberate difference: enforcement uses
- * `requireAdminActor` rather than `assertAdminActor`. There is no
- * ability key to gate against — the security property is "you may
- * only mutate your own row," and these commands enforce it
- * structurally by sourcing the target id from `actor.id` rather than
- * from the request payload. A request with an `id` field would have
- * no way to express "operate on someone else" because the schemas
- * don't accept one.
+ * Same `createCommand` shape as the other admin modules, with one
+ * deliberate difference: `auth` is `{ authenticated: true }` rather than
+ * `{ ability }`. There is no ability key to gate against — the security
+ * property is "you may only mutate your own row," enforced structurally
+ * by sourcing the target id from `actor.id` rather than from the request
+ * payload. The request schemas do not accept an `id` field, so a caller
+ * has no way to express "operate on someone else."
  */
 export interface AdminAccountCommandDeps {
     store: AdminStore;
 }
-export declare function getAccountCommand(context: RequestContext | undefined, input: unknown, deps: AdminAccountCommandDeps): Promise<AccountResponse>;
-export declare function updateAccountCommand(context: RequestContext | undefined, input: unknown, deps: AdminAccountCommandDeps): Promise<AccountResponse>;
-export declare function changeAccountPasswordCommand(context: RequestContext | undefined, input: unknown, deps: AdminAccountCommandDeps): Promise<AccountResponse>;
+export declare const getAccountCommand: Command<GetAccountRequest, AccountResponse, AdminAccountCommandDeps>;
+export declare const updateAccountCommand: Command<UpdateAccountRequest, AccountResponse, AdminAccountCommandDeps>;
+export declare const changeAccountPasswordCommand: Command<ChangeAccountPasswordRequest, AccountResponse, AdminAccountCommandDeps>;

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

@@ -5,31 +5,28 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { requireAdminActor } from '../../lib/assert-admin-actor.js';
+import { createCommand } from '../../lib/create-command.js';
 import { adminUserResponseSchema } from '../admin-users/schemas.js';
 import { changeAccountPasswordRequestSchema, getAccountRequestSchema, updateAccountRequestSchema, } from './schemas.js';
 import { AdminAccountService } from './service.js';
 function serviceOf(deps) {
     return new AdminAccountService({ repo: deps.store.adminUsers });
 }
-export async function getAccountCommand(context, input, deps) {
-    // No-op parse — `getAccountRequestSchema` is `{}.strict()` so it
-    // rejects stray payloads but yields no usable data. The schema is
-    // validated for shape consistency with the other commands.
-    getAccountRequestSchema.parse(input ?? {});
-    const actor = requireAdminActor(context, 'reading own admin account');
-    const result = await serviceOf(deps).getAccount(actor.id);
-    return adminUserResponseSchema.parse(result);
-}
-export async function updateAccountCommand(context, input, deps) {
-    const parsed = updateAccountRequestSchema.parse(input);
-    const actor = requireAdminActor(context, 'updating own admin account');
-    const result = await serviceOf(deps).updateAccount(actor.id, parsed);
-    return adminUserResponseSchema.parse(result);
-}
-export async function changeAccountPasswordCommand(context, input, deps) {
-    const parsed = changeAccountPasswordRequestSchema.parse(input);
-    const actor = requireAdminActor(context, 'changing own admin password');
-    const result = await serviceOf(deps).changePassword(actor.id, parsed);
-    return adminUserResponseSchema.parse(result);
-}
+export const getAccountCommand = createCommand({
+    method: 'getAccount',
+    auth: { authenticated: true },
+    schemas: { input: getAccountRequestSchema, output: adminUserResponseSchema },
+    handler: ({ deps, actor }) => serviceOf(deps).getAccount(actor.id),
+});
+export const updateAccountCommand = createCommand({
+    method: 'updateAccount',
+    auth: { authenticated: true },
+    schemas: { input: updateAccountRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps, actor }) => serviceOf(deps).updateAccount(actor.id, input),
+});
+export const changeAccountPasswordCommand = createCommand({
+    method: 'changeAccountPassword',
+    auth: { authenticated: true },
+    schemas: { input: changeAccountPasswordRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps, actor }) => serviceOf(deps).changePassword(actor.id, input),
+});

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

@@ -5,15 +5,17 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { AbilityRegistry, RequestContext } from '@byline/auth';
+import type { AbilityRegistry } from '@byline/auth';
+import { type Command } from '../../lib/create-command.js';
 import type { AdminStore } from '../../store.js';
-import type { GetRoleAbilitiesResponse, ListRegisteredAbilitiesResponse, SetRoleAbilitiesResponse, WhoHasAbilityResponse } from './schemas.js';
+import type { GetRoleAbilitiesRequest, GetRoleAbilitiesResponse, ListRegisteredAbilitiesRequest, ListRegisteredAbilitiesResponse, SetRoleAbilitiesRequest, SetRoleAbilitiesResponse, WhoHasAbilityRequest, WhoHasAbilityResponse } from './schemas.js';
 /**
  * Transport-agnostic commands for the admin-permissions inspector.
  *
- * Same four-step shape as the other modules — Zod-validate, assert the
- * admin actor + ability, call the service, validate the output. The
- * inspector commands all gate on `admin.permissions.read`.
+ * Built through `createCommand`, which folds the four standard steps
+ * (validate → assert admin actor + ability → invoke service → validate
+ * output) into one declaration. All inspector reads gate on
+ * `admin.permissions.read`; the write gates on `admin.permissions.update`.
  *
  * Deps include the `AbilityRegistry` alongside the `AdminStore` because
  * the inspector reads the registered abilities directly from the
@@ -23,7 +25,7 @@ export interface AdminPermissionsCommandDeps {
     store: AdminStore;
     abilities: AbilityRegistry;
 }
-export declare function listRegisteredAbilitiesCommand(context: RequestContext | undefined, input: unknown, deps: AdminPermissionsCommandDeps): Promise<ListRegisteredAbilitiesResponse>;
-export declare function whoHasAbilityCommand(context: RequestContext | undefined, input: unknown, deps: AdminPermissionsCommandDeps): Promise<WhoHasAbilityResponse>;
-export declare function getRoleAbilitiesCommand(context: RequestContext | undefined, input: unknown, deps: AdminPermissionsCommandDeps): Promise<GetRoleAbilitiesResponse>;
-export declare function setRoleAbilitiesCommand(context: RequestContext | undefined, input: unknown, deps: AdminPermissionsCommandDeps): Promise<SetRoleAbilitiesResponse>;
+export declare const listRegisteredAbilitiesCommand: Command<ListRegisteredAbilitiesRequest, ListRegisteredAbilitiesResponse, AdminPermissionsCommandDeps>;
+export declare const whoHasAbilityCommand: Command<WhoHasAbilityRequest, WhoHasAbilityResponse, AdminPermissionsCommandDeps>;
+export declare const getRoleAbilitiesCommand: Command<GetRoleAbilitiesRequest, GetRoleAbilitiesResponse, AdminPermissionsCommandDeps>;
+export declare const setRoleAbilitiesCommand: Command<SetRoleAbilitiesRequest, SetRoleAbilitiesResponse, AdminPermissionsCommandDeps>;

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

@@ -5,34 +5,37 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertAdminActor } from '../../lib/assert-admin-actor.js';
+import { createCommand } from '../../lib/create-command.js';
 import { ADMIN_PERMISSIONS_ABILITIES } from './abilities.js';
 import { getRoleAbilitiesRequestSchema, getRoleAbilitiesResponseSchema, listRegisteredAbilitiesRequestSchema, listRegisteredAbilitiesResponseSchema, setRoleAbilitiesRequestSchema, setRoleAbilitiesResponseSchema, whoHasAbilityRequestSchema, whoHasAbilityResponseSchema, } from './schemas.js';
 import { AdminPermissionsService } from './service.js';
 function serviceOf(deps) {
     return new AdminPermissionsService({ store: deps.store, abilities: deps.abilities });
 }
-export async function listRegisteredAbilitiesCommand(context, input, deps) {
-    listRegisteredAbilitiesRequestSchema.parse(input ?? {});
-    assertAdminActor(context, ADMIN_PERMISSIONS_ABILITIES.read);
-    const result = serviceOf(deps).listRegisteredAbilities();
-    return listRegisteredAbilitiesResponseSchema.parse(result);
-}
-export async function whoHasAbilityCommand(context, input, deps) {
-    const parsed = whoHasAbilityRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_PERMISSIONS_ABILITIES.read);
-    const result = await serviceOf(deps).whoHasAbility(parsed);
-    return whoHasAbilityResponseSchema.parse(result);
-}
-export async function getRoleAbilitiesCommand(context, input, deps) {
-    const parsed = getRoleAbilitiesRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_PERMISSIONS_ABILITIES.read);
-    const result = await serviceOf(deps).getRoleAbilities(parsed);
-    return getRoleAbilitiesResponseSchema.parse(result);
-}
-export async function setRoleAbilitiesCommand(context, input, deps) {
-    const parsed = setRoleAbilitiesRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_PERMISSIONS_ABILITIES.update);
-    const result = await serviceOf(deps).setRoleAbilities(parsed);
-    return setRoleAbilitiesResponseSchema.parse(result);
-}
+export const listRegisteredAbilitiesCommand = createCommand({
+    method: 'listRegisteredAbilities',
+    auth: { ability: ADMIN_PERMISSIONS_ABILITIES.read },
+    schemas: {
+        input: listRegisteredAbilitiesRequestSchema,
+        output: listRegisteredAbilitiesResponseSchema,
+    },
+    handler: ({ deps }) => serviceOf(deps).listRegisteredAbilities(),
+});
+export const whoHasAbilityCommand = createCommand({
+    method: 'whoHasAbility',
+    auth: { ability: ADMIN_PERMISSIONS_ABILITIES.read },
+    schemas: { input: whoHasAbilityRequestSchema, output: whoHasAbilityResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).whoHasAbility(input),
+});
+export const getRoleAbilitiesCommand = createCommand({
+    method: 'getRoleAbilities',
+    auth: { ability: ADMIN_PERMISSIONS_ABILITIES.read },
+    schemas: { input: getRoleAbilitiesRequestSchema, output: getRoleAbilitiesResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).getRoleAbilities(input),
+});
+export const setRoleAbilitiesCommand = createCommand({
+    method: 'setRoleAbilities',
+    auth: { ability: ADMIN_PERMISSIONS_ABILITIES.update },
+    schemas: { input: setRoleAbilitiesRequestSchema, output: setRoleAbilitiesResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).setRoleAbilities(input),
+});

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

@@ -5,19 +5,15 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { RequestContext } from '@byline/auth';
+import { type Command } from '../../lib/create-command.js';
 import type { AdminStore } from '../../store.js';
-import type { AdminRoleListResponse, AdminRoleResponse, OkResponse, UserRolesResponse } from './schemas.js';
+import type { AdminRoleListResponse, AdminRoleResponse, CreateAdminRoleRequest, DeleteAdminRoleRequest, GetAdminRoleRequest, GetRolesForUserRequest, ListAdminRolesRequest, OkResponse, ReorderAdminRolesRequest, SetRolesForUserRequest, UpdateAdminRoleRequest, UserRolesResponse } from './schemas.js';
 /**
  * Transport-agnostic commands for the admin-roles module.
  *
- * Every command follows the same four steps as `admin-users`:
- *   1. `schema.parse(input)` — Zod-validate.
- *   2. `assertAdminActor(context, ability)` — require an `AdminAuth`
- *      actor holding the specific ability.
- *   3. Call the `AdminRolesService` method with the validated input.
- *   4. Parse the response through its output schema (catches
- *      schema/DTO drift in tests).
+ * Every command goes through `createCommand`, which folds the four
+ * standard steps (validate → assert admin actor + ability → invoke
+ * service → validate output) into one declaration.
  *
  * Reorder uses the `update` ability — see `abilities.ts` for the
  * rationale (same trust level as content updates; splitting it would
@@ -26,11 +22,11 @@ import type { AdminRoleListResponse, AdminRoleResponse, OkResponse, UserRolesRes
 export interface AdminRolesCommandDeps {
     store: AdminStore;
 }
-export declare function listAdminRolesCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<AdminRoleListResponse>;
-export declare function getAdminRoleCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<AdminRoleResponse>;
-export declare function createAdminRoleCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<AdminRoleResponse>;
-export declare function updateAdminRoleCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<AdminRoleResponse>;
-export declare function deleteAdminRoleCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<OkResponse>;
-export declare function reorderAdminRolesCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<OkResponse>;
-export declare function getRolesForUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<UserRolesResponse>;
-export declare function setRolesForUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminRolesCommandDeps): Promise<UserRolesResponse>;
+export declare const listAdminRolesCommand: Command<ListAdminRolesRequest, AdminRoleListResponse, AdminRolesCommandDeps>;
+export declare const getAdminRoleCommand: Command<GetAdminRoleRequest, AdminRoleResponse, AdminRolesCommandDeps>;
+export declare const createAdminRoleCommand: Command<CreateAdminRoleRequest, AdminRoleResponse, AdminRolesCommandDeps>;
+export declare const updateAdminRoleCommand: Command<UpdateAdminRoleRequest, AdminRoleResponse, AdminRolesCommandDeps>;
+export declare const deleteAdminRoleCommand: Command<DeleteAdminRoleRequest, OkResponse, AdminRolesCommandDeps>;
+export declare const reorderAdminRolesCommand: Command<ReorderAdminRolesRequest, OkResponse, AdminRolesCommandDeps>;
+export declare const getRolesForUserCommand: Command<GetRolesForUserRequest, UserRolesResponse, AdminRolesCommandDeps>;
+export declare const setRolesForUserCommand: Command<SetRolesForUserRequest, UserRolesResponse, AdminRolesCommandDeps>;

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

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertAdminActor } from '../../lib/assert-admin-actor.js';
+import { createCommand } from '../../lib/create-command.js';
 import { ADMIN_USERS_ABILITIES } from '../admin-users/abilities.js';
 import { ADMIN_ROLES_ABILITIES } from './abilities.js';
 import { adminRoleListResponseSchema, adminRoleResponseSchema, createAdminRoleRequestSchema, deleteAdminRoleRequestSchema, getAdminRoleRequestSchema, getRolesForUserRequestSchema, listAdminRolesRequestSchema, okResponseSchema, reorderAdminRolesRequestSchema, setRolesForUserRequestSchema, updateAdminRoleRequestSchema, userRolesResponseSchema, } from './schemas.js';
@@ -13,57 +13,63 @@ import { AdminRolesService } from './service.js';
 function serviceOf(deps) {
     return new AdminRolesService({ store: deps.store });
 }
-export async function listAdminRolesCommand(context, input, deps) {
-    listAdminRolesRequestSchema.parse(input ?? {});
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.read);
-    const result = await serviceOf(deps).listRoles();
-    return adminRoleListResponseSchema.parse(result);
-}
-export async function getAdminRoleCommand(context, input, deps) {
-    const parsed = getAdminRoleRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.read);
-    const result = await serviceOf(deps).getRole(parsed);
-    return adminRoleResponseSchema.parse(result);
-}
-export async function createAdminRoleCommand(context, input, deps) {
-    const parsed = createAdminRoleRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.create);
-    const result = await serviceOf(deps).createRole(parsed);
-    return adminRoleResponseSchema.parse(result);
-}
-export async function updateAdminRoleCommand(context, input, deps) {
-    const parsed = updateAdminRoleRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.update);
-    const result = await serviceOf(deps).updateRole(parsed);
-    return adminRoleResponseSchema.parse(result);
-}
-export async function deleteAdminRoleCommand(context, input, deps) {
-    const parsed = deleteAdminRoleRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.delete);
-    await serviceOf(deps).deleteRole(parsed);
-    return okResponseSchema.parse({ ok: true });
-}
-export async function reorderAdminRolesCommand(context, input, deps) {
-    const parsed = reorderAdminRolesRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_ROLES_ABILITIES.update);
-    await serviceOf(deps).reorderRoles(parsed);
-    return okResponseSchema.parse({ ok: true });
-}
-export async function getRolesForUserCommand(context, input, deps) {
-    const parsed = getRolesForUserRequestSchema.parse(input);
+export const listAdminRolesCommand = createCommand({
+    method: 'listAdminRoles',
+    auth: { ability: ADMIN_ROLES_ABILITIES.read },
+    schemas: { input: listAdminRolesRequestSchema, output: adminRoleListResponseSchema },
+    handler: ({ deps }) => serviceOf(deps).listRoles(),
+});
+export const getAdminRoleCommand = createCommand({
+    method: 'getAdminRole',
+    auth: { ability: ADMIN_ROLES_ABILITIES.read },
+    schemas: { input: getAdminRoleRequestSchema, output: adminRoleResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).getRole(input),
+});
+export const createAdminRoleCommand = createCommand({
+    method: 'createAdminRole',
+    auth: { ability: ADMIN_ROLES_ABILITIES.create },
+    schemas: { input: createAdminRoleRequestSchema, output: adminRoleResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).createRole(input),
+});
+export const updateAdminRoleCommand = createCommand({
+    method: 'updateAdminRole',
+    auth: { ability: ADMIN_ROLES_ABILITIES.update },
+    schemas: { input: updateAdminRoleRequestSchema, output: adminRoleResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).updateRole(input),
+});
+export const deleteAdminRoleCommand = createCommand({
+    method: 'deleteAdminRole',
+    auth: { ability: ADMIN_ROLES_ABILITIES.delete },
+    schemas: { input: deleteAdminRoleRequestSchema, output: okResponseSchema },
+    handler: async ({ input, deps }) => {
+        await serviceOf(deps).deleteRole(input);
+        return { ok: true };
+    },
+});
+export const reorderAdminRolesCommand = createCommand({
+    method: 'reorderAdminRoles',
+    auth: { ability: ADMIN_ROLES_ABILITIES.update },
+    schemas: { input: reorderAdminRolesRequestSchema, output: okResponseSchema },
+    handler: async ({ input, deps }) => {
+        await serviceOf(deps).reorderRoles(input);
+        return { ok: true };
+    },
+});
+export const getRolesForUserCommand = createCommand({
+    method: 'getRolesForUser',
     // Reading a user's role assignments requires read access to admin
     // users — the data is fundamentally about that user.
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.read);
-    const result = await serviceOf(deps).getRolesForUser(parsed);
-    return userRolesResponseSchema.parse(result);
-}
-export async function setRolesForUserCommand(context, input, deps) {
-    const parsed = setRolesForUserRequestSchema.parse(input);
+    auth: { ability: ADMIN_USERS_ABILITIES.read },
+    schemas: { input: getRolesForUserRequestSchema, output: userRolesResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).getRolesForUser(input),
+});
+export const setRolesForUserCommand = createCommand({
+    method: 'setRolesForUser',
     // Editing a user's role-set is at the same trust level as updating
     // their other admin fields. Roll into `admin.users.update` rather
     // than minting a separate `admin.users.assignRoles` key — the role
     // editor's checkbox tree would otherwise need both.
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.update);
-    const result = await serviceOf(deps).setRolesForUser(parsed);
-    return userRolesResponseSchema.parse(result);
-}
+    auth: { ability: ADMIN_USERS_ABILITIES.update },
+    schemas: { input: setRolesForUserRequestSchema, output: userRolesResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).setRolesForUser(input),
+});

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

@@ -5,27 +5,17 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { RequestContext } from '@byline/auth';
+import { type Command } from '../../lib/create-command.js';
 import type { AdminStore } from '../../store.js';
-import type { AdminUserListResponse, AdminUserResponse, OkResponse } from './schemas.js';
+import type { AdminUserListResponse, AdminUserResponse, CreateAdminUserRequest, DeleteAdminUserRequest, DisableAdminUserRequest, EnableAdminUserRequest, GetAdminUserRequest, ListAdminUsersRequest, OkResponse, SetAdminUserPasswordRequest, UpdateAdminUserRequest } from './schemas.js';
 /**
  * Transport-agnostic commands for the admin-users module.
  *
- * Each command is a plain exported function — not a class method — to
- * match Byline's existing `document-lifecycle` shape. Every command
- * follows the same four steps in the same order:
- *
- *   1. `schema.parse(input)` — Zod-validate and normalise the raw input.
- *      Throws `ZodError` on invalid shape; transport adapters translate
- *      that into a 400-ish response.
- *   2. `assertAdminActor(context, ability)` — require an `AdminAuth`
- *      actor holding the specific ability. Throws `ERR_UNAUTHENTICATED`
- *      or `ERR_FORBIDDEN`.
- *   3. Call the `AdminUsersService` method with the validated input
- *      (plus the actor where an invariant needs it).
- *   4. Parse the response through its output schema. In production the
- *      check is redundant with the DTO's type; in tests it catches
- *      drift between schema and DTO early.
+ * Each command is built through `createCommand`, which folds the four
+ * standard steps (Zod-validate input → assert admin actor + ability →
+ * call the service → Zod-validate output) into a single declaration.
+ * The wrapper preserves the historical `(context, input, deps)` call
+ * signature so server fns keep working without change.
  *
  * The `deps` argument holds the `AdminStore`. The webapp wraps these in
  * server fns that supply `deps` from the application's singleton store;
@@ -34,11 +24,11 @@ import type { AdminUserListResponse, AdminUserResponse, OkResponse } from './sch
 export interface AdminUsersCommandDeps {
     store: AdminStore;
 }
-export declare function listAdminUsersCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<AdminUserListResponse>;
-export declare function getAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<AdminUserResponse>;
-export declare function createAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<AdminUserResponse>;
-export declare function updateAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<AdminUserResponse>;
-export declare function setAdminUserPasswordCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<AdminUserResponse>;
-export declare function enableAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<OkResponse>;
-export declare function disableAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<OkResponse>;
-export declare function deleteAdminUserCommand(context: RequestContext | undefined, input: unknown, deps: AdminUsersCommandDeps): Promise<OkResponse>;
+export declare const listAdminUsersCommand: Command<ListAdminUsersRequest, AdminUserListResponse, AdminUsersCommandDeps>;
+export declare const getAdminUserCommand: Command<GetAdminUserRequest, AdminUserResponse, AdminUsersCommandDeps>;
+export declare const createAdminUserCommand: Command<CreateAdminUserRequest, AdminUserResponse, AdminUsersCommandDeps>;
+export declare const updateAdminUserCommand: Command<UpdateAdminUserRequest, AdminUserResponse, AdminUsersCommandDeps>;
+export declare const setAdminUserPasswordCommand: Command<SetAdminUserPasswordRequest, AdminUserResponse, AdminUsersCommandDeps>;
+export declare const enableAdminUserCommand: Command<EnableAdminUserRequest, OkResponse, AdminUsersCommandDeps>;
+export declare const disableAdminUserCommand: Command<DisableAdminUserRequest, OkResponse, AdminUsersCommandDeps>;
+export declare const deleteAdminUserCommand: Command<DeleteAdminUserRequest, OkResponse, AdminUsersCommandDeps>;

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

@@ -5,58 +5,67 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertAdminActor } from '../../lib/assert-admin-actor.js';
+import { createCommand } from '../../lib/create-command.js';
 import { ADMIN_USERS_ABILITIES } from './abilities.js';
 import { adminUserListResponseSchema, adminUserResponseSchema, createAdminUserRequestSchema, deleteAdminUserRequestSchema, disableAdminUserRequestSchema, enableAdminUserRequestSchema, getAdminUserRequestSchema, listAdminUsersRequestSchema, okResponseSchema, setAdminUserPasswordRequestSchema, updateAdminUserRequestSchema, } from './schemas.js';
 import { AdminUsersService } from './service.js';
 function serviceOf(deps) {
     return new AdminUsersService({ repo: deps.store.adminUsers });
 }
-export async function listAdminUsersCommand(context, input, deps) {
-    const parsed = listAdminUsersRequestSchema.parse(input ?? {});
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.read);
-    const result = await serviceOf(deps).listUsers(parsed);
-    return adminUserListResponseSchema.parse(result);
-}
-export async function getAdminUserCommand(context, input, deps) {
-    const parsed = getAdminUserRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.read);
-    const result = await serviceOf(deps).getUser(parsed);
-    return adminUserResponseSchema.parse(result);
-}
-export async function createAdminUserCommand(context, input, deps) {
-    const parsed = createAdminUserRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.create);
-    const result = await serviceOf(deps).createUser(parsed);
-    return adminUserResponseSchema.parse(result);
-}
-export async function updateAdminUserCommand(context, input, deps) {
-    const parsed = updateAdminUserRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.update);
-    const result = await serviceOf(deps).updateUser(parsed);
-    return adminUserResponseSchema.parse(result);
-}
-export async function setAdminUserPasswordCommand(context, input, deps) {
-    const parsed = setAdminUserPasswordRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.changePassword);
-    const result = await serviceOf(deps).setPassword(parsed);
-    return adminUserResponseSchema.parse(result);
-}
-export async function enableAdminUserCommand(context, input, deps) {
-    const parsed = enableAdminUserRequestSchema.parse(input);
-    assertAdminActor(context, ADMIN_USERS_ABILITIES.update);
-    await serviceOf(deps).enableUser(parsed);
-    return okResponseSchema.parse({ ok: true });
-}
-export async function disableAdminUserCommand(context, input, deps) {
-    const parsed = disableAdminUserRequestSchema.parse(input);
-    const actor = assertAdminActor(context, ADMIN_USERS_ABILITIES.update);
-    await serviceOf(deps).disableUser(actor, parsed);
-    return okResponseSchema.parse({ ok: true });
-}
-export async function deleteAdminUserCommand(context, input, deps) {
-    const parsed = deleteAdminUserRequestSchema.parse(input);
-    const actor = assertAdminActor(context, ADMIN_USERS_ABILITIES.delete);
-    await serviceOf(deps).deleteUser(actor, parsed);
-    return okResponseSchema.parse({ ok: true });
-}
+export const listAdminUsersCommand = createCommand({
+    method: 'listAdminUsers',
+    auth: { ability: ADMIN_USERS_ABILITIES.read },
+    schemas: { input: listAdminUsersRequestSchema, output: adminUserListResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).listUsers(input),
+});
+export const getAdminUserCommand = createCommand({
+    method: 'getAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.read },
+    schemas: { input: getAdminUserRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).getUser(input),
+});
+export const createAdminUserCommand = createCommand({
+    method: 'createAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.create },
+    schemas: { input: createAdminUserRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).createUser(input),
+});
+export const updateAdminUserCommand = createCommand({
+    method: 'updateAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.update },
+    schemas: { input: updateAdminUserRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).updateUser(input),
+});
+export const setAdminUserPasswordCommand = createCommand({
+    method: 'setAdminUserPassword',
+    auth: { ability: ADMIN_USERS_ABILITIES.changePassword },
+    schemas: { input: setAdminUserPasswordRequestSchema, output: adminUserResponseSchema },
+    handler: ({ input, deps }) => serviceOf(deps).setPassword(input),
+});
+export const enableAdminUserCommand = createCommand({
+    method: 'enableAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.update },
+    schemas: { input: enableAdminUserRequestSchema, output: okResponseSchema },
+    handler: async ({ input, deps }) => {
+        await serviceOf(deps).enableUser(input);
+        return { ok: true };
+    },
+});
+export const disableAdminUserCommand = createCommand({
+    method: 'disableAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.update },
+    schemas: { input: disableAdminUserRequestSchema, output: okResponseSchema },
+    handler: async ({ input, deps, actor }) => {
+        await serviceOf(deps).disableUser(actor, input);
+        return { ok: true };
+    },
+});
+export const deleteAdminUserCommand = createCommand({
+    method: 'deleteAdminUser',
+    auth: { ability: ADMIN_USERS_ABILITIES.delete },
+    schemas: { input: deleteAdminUserRequestSchema, output: okResponseSchema },
+    handler: async ({ input, deps, actor }) => {
+        await serviceOf(deps).deleteUser(actor, input);
+        return { ok: true };
+    },
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -68,8 +68,8 @@
     "jose": "^6.2.3",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.9.1",
-    "@byline/core": "1.9.1"
+    "@byline/auth": "1.10.0",
+    "@byline/core": "1.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",