@hotmeshio/long-tail 0.16.4 → 0.17.1

package/build/api/users.d.ts

@@ -63,7 +63,8 @@ export declare function createUser(input: {
  * @param input.email — new email address
  * @param input.display_name — new display name
  * @param input.status — new user status
- * @param input.metadata — replacement metadata object
+ * @param input.metadata — REPLACES the whole properties dictionary; for
+ *   per-key edits use patchUserProperties (never clobbers siblings)
  * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
  */
 export declare function updateUser(input: {
@@ -74,6 +75,35 @@ export declare function updateUser(input: {
     status?: string;
     metadata?: Record<string, any>;
 }): Promise<LTApiResult>;
+/**
+ * Atomically patch the user's properties dictionary (lt_users.metadata) —
+ * one statement, never read-merge-write. Deleting a key is explicit
+ * (`remove`); a key absent from the patch is kept. `rename` preserves the
+ * value with no key-absent window. Identity-binding keys (badge scan
+ * scheme target facets) assert uniqueness among active users in the same
+ * statement.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.set — properties to set (typed JSON values)
+ * @param input.remove — property keys to delete
+ * @param input.rename — `{ oldKey: newKey }` renames, values preserved
+ * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ *   user; 409 when an identity value already belongs to another active user
+ */
+export declare function patchUserProperties(input: {
+    id: string;
+    set?: Record<string, unknown>;
+    remove?: string[];
+    rename?: Record<string, string>;
+}): Promise<LTApiResult>;
+/**
+ * The property keys the platform itself resolves identities against — every
+ * enabled identity scan scheme's target facet. The dashboard marks these as
+ * system properties.
+ *
+ * @returns `{ status: 200, data: { keys: string[] } }`
+ */
+export declare function getSystemPropertyKeys(): Promise<LTApiResult>;
 /**
  * Delete a user by ID. Requires admin privileges.
  *

package/build/api/users.js

@@ -37,6 +37,8 @@ exports.listUsers = listUsers;
 exports.getUser = getUser;
 exports.createUser = createUser;
 exports.updateUser = updateUser;
+exports.patchUserProperties = patchUserProperties;
+exports.getSystemPropertyKeys = getSystemPropertyKeys;
 exports.deleteUser = deleteUser;
 exports.getUserRoles = getUserRoles;
 exports.addUserRole = addUserRole;
@@ -145,7 +147,8 @@ async function createUser(input) {
  * @param input.email — new email address
  * @param input.display_name — new display name
  * @param input.status — new user status
- * @param input.metadata — replacement metadata object
+ * @param input.metadata — REPLACES the whole properties dictionary; for
+ *   per-key edits use patchUserProperties (never clobbers siblings)
  * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
  */
 async function updateUser(input) {
@@ -161,6 +164,56 @@ async function updateUser(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Atomically patch the user's properties dictionary (lt_users.metadata) —
+ * one statement, never read-merge-write. Deleting a key is explicit
+ * (`remove`); a key absent from the patch is kept. `rename` preserves the
+ * value with no key-absent window. Identity-binding keys (badge scan
+ * scheme target facets) assert uniqueness among active users in the same
+ * statement.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.set — properties to set (typed JSON values)
+ * @param input.remove — property keys to delete
+ * @param input.rename — `{ oldKey: newKey }` renames, values preserved
+ * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ *   user; 409 when an identity value already belongs to another active user
+ */
+async function patchUserProperties(input) {
+    try {
+        const user = await userService.patchUserProperties(input.id, {
+            set: input.set,
+            remove: input.remove,
+            rename: input.rename,
+        });
+        if (!user) {
+            return { status: 404, error: 'User not found' };
+        }
+        return { status: 200, data: user };
+    }
+    catch (err) {
+        if (err.status === 400 || err.status === 409) {
+            return { status: err.status, error: err.message };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * The property keys the platform itself resolves identities against — every
+ * enabled identity scan scheme's target facet. The dashboard marks these as
+ * system properties.
+ *
+ * @returns `{ status: 200, data: { keys: string[] } }`
+ */
+async function getSystemPropertyKeys() {
+    try {
+        const keys = await userService.getIdentityPropertyKeys();
+        return { status: 200, data: { keys } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Delete a user by ID. Requires admin privileges.
  *

package/build/bin/ltc.js

@@ -335,6 +335,13 @@ usrCmd.command('list')
 usrCmd.command('get <id>')
     .option('--json', 'JSON output')
     .action(wrap(usr.getUser));
+usrCmd.command('props <id>')
+    .description('View or atomically patch the user\'s properties dictionary')
+    .option('--set <key=value...>', 'Set a property (repeatable; value JSON-parsed, string fallback)')
+    .option('--remove <key...>', 'Delete a property (repeatable)')
+    .option('--rename <old=new...>', 'Rename a property, value preserved (repeatable)')
+    .option('--json', 'JSON output')
+    .action(wrap(usr.userProps));
 // ── Roles ────────────────────────────────────────────────────────────────
 const rolesCmd = commander_1.program.command('roles').description('Roles — the queue-backed work surfaces where workflows hand off to people');
 rolesCmd.command('list')

package/build/lib/cli/commands/users.d.ts

@@ -5,3 +5,14 @@ export declare function listUsers(opts: {
 export declare function getUser(id: string, opts: {
     json?: boolean;
 }): Promise<void>;
+/**
+ * View or atomically patch a user's properties dictionary. With no flags,
+ * prints the dictionary; with --set/--remove/--rename, applies ONE atomic
+ * patch (never read-merge-write) and prints the result.
+ */
+export declare function userProps(id: string, opts: {
+    set?: string[];
+    remove?: string[];
+    rename?: string[];
+    json?: boolean;
+}): Promise<void>;

package/build/lib/cli/commands/users.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listUsers = listUsers;
 exports.getUser = getUser;
+exports.userProps = userProps;
+const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
 const COLUMNS = [
@@ -23,3 +28,57 @@ async function getUser(id, opts) {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/** Parse a repeatable `key=value` flag; values JSON-parse with string fallback. */
+function parsePairs(pairs) {
+    if (!pairs?.length)
+        return undefined;
+    const out = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`Expected key=value, got "${pair}"`);
+        const key = pair.slice(0, eq);
+        const raw = pair.slice(eq + 1);
+        try {
+            out[key] = JSON.parse(raw);
+        }
+        catch {
+            out[key] = raw;
+        }
+    }
+    return out;
+}
+/**
+ * View or atomically patch a user's properties dictionary. With no flags,
+ * prints the dictionary; with --set/--remove/--rename, applies ONE atomic
+ * patch (never read-merge-write) and prints the result.
+ */
+async function userProps(id, opts) {
+    const set = parsePairs(opts.set);
+    const rename = parsePairs(opts.rename);
+    const remove = opts.remove?.length ? opts.remove : undefined;
+    let user;
+    if (set || remove || rename) {
+        user = await (0, client_1.apiFetch)(`/users/${id}/properties`, {
+            method: 'PATCH',
+            body: JSON.stringify({ set, remove, rename }),
+        });
+    }
+    else {
+        user = await (0, client_1.apiFetch)(`/users/${id}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(user.metadata ?? {}, null, 2));
+        return;
+    }
+    const props = Object.entries(user.metadata ?? {});
+    console.log(`\n  ${picocolors_1.default.bold(user.display_name ?? user.external_id ?? id)} ${picocolors_1.default.dim(user.id ?? id)}`);
+    if (props.length === 0) {
+        console.log(picocolors_1.default.dim('  (no properties)\n'));
+        return;
+    }
+    for (const [key, value] of props) {
+        console.log(`  ${picocolors_1.default.bold(key)} = ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    }
+    console.log();
+}

package/build/routes/users.js

@@ -55,6 +55,16 @@ router.get('/', async (req, res) => {
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/users/system-property-keys
+ * The property keys the platform resolves identities against (enabled
+ * identity scan schemes' target facets) — marked as system properties in
+ * the dashboard editor. Registered before /:id so the literal wins.
+ */
+router.get('/system-property-keys', async (_req, res) => {
+    const result = await api.getSystemPropertyKeys();
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/users/:id
  * Get a single user by ID.
@@ -81,6 +91,22 @@ router.put('/:id', auth_1.requireBuilder, async (req, res) => {
     const result = await api.updateUser({ id: req.params.id, ...(req.body || {}) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * PATCH /api/users/:id/properties
+ * Atomically patch the user's properties dictionary. Builder only — the
+ * same gate as every other user write.
+ * Body: { set?: { key: value }, remove?: [key], rename?: { old: new } }
+ */
+router.patch('/:id/properties', auth_1.requireBuilder, async (req, res) => {
+    const { set, remove, rename } = req.body || {};
+    const result = await api.patchUserProperties({
+        id: req.params.id,
+        set,
+        remove,
+        rename,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * DELETE /api/users/:id
  * Delete a user. Builder only.

package/build/sdk/index.d.ts

@@ -290,6 +290,8 @@ export declare function createClient(options?: LTClientOptions): {
         get: typeof usersApi.getUser;
         create: typeof usersApi.createUser;
         update: typeof usersApi.updateUser;
+        patchProperties: typeof usersApi.patchUserProperties;
+        getSystemPropertyKeys: typeof usersApi.getSystemPropertyKeys;
         delete: typeof usersApi.deleteUser;
         getRoles: typeof usersApi.getUserRoles;
         addRole: typeof usersApi.addUserRole;

package/build/sdk/index.js

@@ -194,6 +194,8 @@ function createClient(options = {}) {
             get: usersApi.getUser,
             create: usersApi.createUser,
             update: usersApi.updateUser,
+            patchProperties: usersApi.patchUserProperties,
+            getSystemPropertyKeys: usersApi.getSystemPropertyKeys,
             delete: usersApi.deleteUser,
             getRoles: usersApi.getUserRoles,
             addRole: usersApi.addUserRole,

package/build/services/user/crud.d.ts

@@ -1,5 +1,5 @@
 import type { LTUserRecord, LTRoleType, LTUserStatus } from '../../types';
-import type { CreateUserInput, UpdateUserInput } from './types';
+import type { CreateUserInput, UpdateUserInput, UserPropertyOps } from './types';
 export declare function attachRoles(user: any): Promise<LTUserRecord>;
 export declare function createUser(input: CreateUserInput): Promise<LTUserRecord>;
 export declare function getUser(id: string): Promise<LTUserRecord | null>;
@@ -12,6 +12,37 @@ export declare function getUserByEmail(email: string): Promise<LTUserRecord | nu
  */
 export declare function getUserByMetadataValue(key: string, value: string): Promise<LTUserRecord | null>;
 export declare function updateUser(id: string, input: UpdateUserInput): Promise<LTUserRecord | null>;
+/** A property write that would create an ambiguous identity binding. */
+export declare class UserPropertyConflictError extends Error {
+    status: number;
+    constructor(key: string);
+}
+/** A malformed property patch — rejected before any write. */
+export declare class UserPropertyValidationError extends Error {
+    status: number;
+    constructor(message: string);
+}
+/**
+ * The lt_users.metadata keys the platform itself resolves identities against:
+ * every enabled identity scan scheme's target_facet (e.g. badge_id). Writes
+ * to these keys carry a uniqueness guard; the dashboard marks them as system
+ * properties.
+ */
+export declare function getIdentityPropertyKeys(): Promise<string[]>;
+/**
+ * Atomic per-key patch of the user's properties dictionary (lt_users.metadata).
+ * One statement — never read-merge-write: concurrent patches of different
+ * keys both land, a rename never opens a key-absent window, and deleting is
+ * explicit (`remove`) — an absent key means keep. Precedence on collision:
+ * set > rename > existing. Values are raw JSON, so numbers/booleans/objects
+ * round-trip typed.
+ *
+ * Identity-binding keys (getIdentityPropertyKeys) additionally assert, in the
+ * same statement, that no OTHER active user carries the value — the
+ * write-side counterpart of getUserByMetadataValue's ambiguity throw.
+ * A tripped guard raises UserPropertyConflictError (409).
+ */
+export declare function patchUserProperties(id: string, ops: UserPropertyOps): Promise<LTUserRecord | null>;
 export declare function deleteUser(id: string): Promise<boolean>;
 export declare function listUsers(filters: {
     role?: string;

package/build/services/user/crud.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPropertyValidationError = exports.UserPropertyConflictError = void 0;
 exports.attachRoles = attachRoles;
 exports.createUser = createUser;
 exports.getUser = getUser;
@@ -10,11 +11,15 @@ exports.getUserByExternalId = getUserByExternalId;
 exports.getUserByEmail = getUserByEmail;
 exports.getUserByMetadataValue = getUserByMetadataValue;
 exports.updateUser = updateUser;
+exports.getIdentityPropertyKeys = getIdentityPropertyKeys;
+exports.patchUserProperties = patchUserProperties;
 exports.deleteUser = deleteUser;
 exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scan_code_1 = require("../scan-code");
+const scan_code_2 = require("../../types/scan-code");
 const scope_1 = require("./scope");
 // ─── Private helpers (exported for internal use by auth.ts) ──────────────────
 async function attachRoles(user) {
@@ -143,6 +148,109 @@ async function updateUser(id, input) {
         return null;
     return attachRoles(rows[0]);
 }
+/** A property write that would create an ambiguous identity binding. */
+class UserPropertyConflictError extends Error {
+    constructor(key) {
+        super(`"${key}" value is already bound to another active user`);
+        this.status = 409;
+        this.name = 'UserPropertyConflictError';
+    }
+}
+exports.UserPropertyConflictError = UserPropertyConflictError;
+/** A malformed property patch — rejected before any write. */
+class UserPropertyValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.status = 400;
+        this.name = 'UserPropertyValidationError';
+    }
+}
+exports.UserPropertyValidationError = UserPropertyValidationError;
+/**
+ * The lt_users.metadata keys the platform itself resolves identities against:
+ * every enabled identity scan scheme's target_facet (e.g. badge_id). Writes
+ * to these keys carry a uniqueness guard; the dashboard marks them as system
+ * properties.
+ */
+async function getIdentityPropertyKeys() {
+    const schemes = await (0, scan_code_1.listScanSchemes)();
+    return [...new Set(schemes
+            .filter((s) => s.enabled && s.kind === scan_code_2.SCAN_SCHEME_KINDS.IDENTITY)
+            .map((s) => s.target_facet))];
+}
+/**
+ * Atomic per-key patch of the user's properties dictionary (lt_users.metadata).
+ * One statement — never read-merge-write: concurrent patches of different
+ * keys both land, a rename never opens a key-absent window, and deleting is
+ * explicit (`remove`) — an absent key means keep. Precedence on collision:
+ * set > rename > existing. Values are raw JSON, so numbers/booleans/objects
+ * round-trip typed.
+ *
+ * Identity-binding keys (getIdentityPropertyKeys) additionally assert, in the
+ * same statement, that no OTHER active user carries the value — the
+ * write-side counterpart of getUserByMetadataValue's ambiguity throw.
+ * A tripped guard raises UserPropertyConflictError (409).
+ */
+async function patchUserProperties(id, ops) {
+    const set = ops.set ?? {};
+    const remove = ops.remove ?? [];
+    const rename = ops.rename ?? {};
+    const setKeys = Object.keys(set);
+    const renameEntries = Object.entries(rename);
+    if (setKeys.length === 0 && remove.length === 0 && renameEntries.length === 0) {
+        throw new UserPropertyValidationError('A property patch requires at least one set, remove, or rename');
+    }
+    for (const key of [...setKeys, ...remove, ...renameEntries.flat()]) {
+        if (typeof key !== 'string' || key.trim().length === 0) {
+            throw new UserPropertyValidationError('Property keys must be non-empty strings');
+        }
+    }
+    for (const key of setKeys) {
+        if (remove.includes(key)) {
+            throw new UserPropertyValidationError(`"${key}" cannot be both set and removed in one patch`);
+        }
+    }
+    for (const [prev, next] of renameEntries) {
+        if (prev === next) {
+            throw new UserPropertyValidationError(`Renaming "${prev}" to itself is not a change`);
+        }
+    }
+    const renameTargets = renameEntries.map(([, next]) => next);
+    if (new Set(renameTargets).size !== renameTargets.length) {
+        throw new UserPropertyValidationError('Two properties cannot be renamed to the same key');
+    }
+    // Identity bindings resolve people — their values must be scalar and, for
+    // ACTIVE users, unique. The guard rides the same statement.
+    const identityKeys = await getIdentityPropertyKeys();
+    const guard = {};
+    for (const key of identityKeys) {
+        if (key in set) {
+            const value = set[key];
+            if (typeof value !== 'string' && typeof value !== 'number') {
+                throw new UserPropertyValidationError(`"${key}" is an identity binding — its value must be a string or number`);
+            }
+            guard[key] = String(value);
+        }
+    }
+    const removeAll = [...new Set([...remove, ...renameEntries.map(([prev]) => prev)])];
+    const renamePairs = renameEntries.map(([prev, next]) => ({ prev, next }));
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.PATCH_USER_PROPERTIES, [
+        id,
+        removeAll,
+        JSON.stringify(renamePairs),
+        JSON.stringify(set),
+        JSON.stringify(guard),
+    ]);
+    if (rows[0])
+        return attachRoles(rows[0]);
+    const exists = await pool.query(sql_1.VERIFY_USER_BY_ID, [id]);
+    if (!exists.rows[0])
+        return null;
+    // The user exists, so the identity guard is what blocked the write. Name
+    // the first guarded key for the caller; the row was not touched.
+    throw new UserPropertyConflictError(Object.keys(guard)[0] ?? 'identity binding');
+}
 async function deleteUser(id) {
     const pool = (0, db_1.getPool)();
     const { rowCount } = await pool.query(sql_1.DELETE_USER_BY_ID, [id]);

package/build/services/user/index.d.ts

@@ -1,5 +1,5 @@
-export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
-export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, deleteUser, listUsers, } from './crud';
+export { CreateUserInput, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
+export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, grantRoleIfAbsent, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -10,6 +10,10 @@ Object.defineProperty(exports, "getUserByExternalId", { enumerable: true, get: f
 Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: function () { return crud_1.getUserByEmail; } });
 Object.defineProperty(exports, "getUserByMetadataValue", { enumerable: true, get: function () { return crud_1.getUserByMetadataValue; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
+Object.defineProperty(exports, "patchUserProperties", { enumerable: true, get: function () { return crud_1.patchUserProperties; } });
+Object.defineProperty(exports, "getIdentityPropertyKeys", { enumerable: true, get: function () { return crud_1.getIdentityPropertyKeys; } });
+Object.defineProperty(exports, "UserPropertyConflictError", { enumerable: true, get: function () { return crud_1.UserPropertyConflictError; } });
+Object.defineProperty(exports, "UserPropertyValidationError", { enumerable: true, get: function () { return crud_1.UserPropertyValidationError; } });
 Object.defineProperty(exports, "deleteUser", { enumerable: true, get: function () { return crud_1.deleteUser; } });
 Object.defineProperty(exports, "listUsers", { enumerable: true, get: function () { return crud_1.listUsers; } });
 var roles_1 = require("./roles");

package/build/services/user/sql.d.ts

@@ -28,6 +28,22 @@ export declare const GET_USER_BY_ID = "SELECT * FROM lt_users WHERE id = $1";
 export declare const GET_USERS_BY_METADATA_VALUE = "SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2";
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
+/**
+ * Atomic per-key patch of the user's properties dictionary — ONE statement,
+ * never read-merge-write. Composition (later wins on key collision):
+ *
+ *   base minus ($2: removed keys ∪ rename old-names)
+ *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
+ *      the source key is absent)
+ *   || sets ($4: typed JSON values)
+ *
+ * $5 is the identity-binding guard: {key: value} pairs that must not already
+ * belong to ANOTHER active user (the write-side counterpart of the
+ * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
+ * back means the user is missing OR the guard tripped — the caller
+ * distinguishes with VERIFY_USER_BY_ID.
+ */
+export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";

package/build/services/user/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 /** Fetch roles for a single user, ordered by creation time. granted_by_persona
@@ -50,6 +50,38 @@ exports.GET_USER_BY_ID = 'SELECT * FROM lt_users WHERE id = $1';
 exports.GET_USERS_BY_METADATA_VALUE = `SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2`;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
+/**
+ * Atomic per-key patch of the user's properties dictionary — ONE statement,
+ * never read-merge-write. Composition (later wins on key collision):
+ *
+ *   base minus ($2: removed keys ∪ rename old-names)
+ *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
+ *      the source key is absent)
+ *   || sets ($4: typed JSON values)
+ *
+ * $5 is the identity-binding guard: {key: value} pairs that must not already
+ * belong to ANOTHER active user (the write-side counterpart of the
+ * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
+ * back means the user is missing OR the guard tripped — the caller
+ * distinguishes with VERIFY_USER_BY_ID.
+ */
+exports.PATCH_USER_PROPERTIES = `
+  UPDATE lt_users SET metadata = (
+    (COALESCE(metadata, '{}'::jsonb) - $2::text[])
+    || COALESCE((
+      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)
+      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)
+      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev
+    ), '{}'::jsonb)
+    || $4::jsonb
+  )
+  WHERE id = $1
+    AND NOT EXISTS (
+      SELECT 1
+      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)
+      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v
+    )
+  RETURNING *`;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
           r.role, r.type AS role_type, r.read_scope, r.write_scope

package/build/services/user/types.d.ts

@@ -24,5 +24,16 @@ export interface UpdateUserInput {
     display_name?: string;
     password?: string;
     status?: LTUserStatus;
+    /** Wholesale REPLACE of the properties dictionary — for per-key edits use patchUserProperties. */
     metadata?: Record<string, any>;
 }
+/**
+ * One atomic patch of the user's properties dictionary. Deleting is explicit
+ * (`remove`) — a key absent from the patch is kept. `rename` preserves the
+ * value. Precedence on collision: set > rename > existing.
+ */
+export interface UserPropertyOps {
+    set?: Record<string, unknown>;
+    remove?: string[];
+    rename?: Record<string, string>;
+}