@jskit-ai/users-core 0.1.115 → 0.1.117

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-core",
-  version: "0.1.115",
+  version: "0.1.117",
   kind: "runtime",
   description: "Users/account runtime plus HTTP routes for account features.",
   dependsOn: [
@@ -146,16 +146,16 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/auth-core": "0.1.104",
-        "@jskit-ai/crud-core": "0.1.113",
-        "@jskit-ai/database-runtime": "0.1.105",
-        "@jskit-ai/http-runtime": "0.1.104",
-        "@jskit-ai/json-rest-api-core": "0.1.50",
-        "@jskit-ai/kernel": "0.1.106",
-        "@jskit-ai/resource-core": "0.1.50",
-        "@jskit-ai/resource-crud-core": "0.1.50",
+        "@jskit-ai/auth-core": "0.1.106",
+        "@jskit-ai/crud-core": "0.1.115",
+        "@jskit-ai/database-runtime": "0.1.107",
+        "@jskit-ai/http-runtime": "0.1.106",
+        "@jskit-ai/json-rest-api-core": "0.1.52",
+        "@jskit-ai/kernel": "0.1.108",
+        "@jskit-ai/resource-core": "0.1.52",
+        "@jskit-ai/resource-crud-core": "0.1.52",
         "@local/users": "file:packages/users",
-        "@jskit-ai/uploads-runtime": "0.1.83"
+        "@jskit-ai/uploads-runtime": "0.1.85"
       },
       dev: {}
     },
@@ -182,6 +182,15 @@ export default Object.freeze({
         category: "migration",
         id: "users-core-profile-username-schema"
       },
+      {
+        op: "install-migration",
+        from: "templates/migrations/users_core_profile_updated_at.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install users profile updated-at migration.",
+        category: "migration",
+        id: "users-core-profile-updated-at-schema"
+      },
       {
         from: "templates/packages/users/package.json",
         to: "packages/users/package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-core",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -12,14 +12,14 @@
     "./shared/resources/userSettingsResource": "./src/shared/resources/userSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.1.104",
-    "@jskit-ai/database-runtime": "0.1.105",
-    "@jskit-ai/http-runtime": "0.1.104",
-    "@jskit-ai/json-rest-api-core": "0.1.50",
-    "@jskit-ai/kernel": "0.1.106",
-    "@jskit-ai/resource-crud-core": "0.1.50",
-    "@jskit-ai/resource-core": "0.1.50",
-    "@jskit-ai/uploads-runtime": "0.1.83",
+    "@jskit-ai/auth-core": "0.1.106",
+    "@jskit-ai/database-runtime": "0.1.107",
+    "@jskit-ai/http-runtime": "0.1.106",
+    "@jskit-ai/json-rest-api-core": "0.1.52",
+    "@jskit-ai/kernel": "0.1.108",
+    "@jskit-ai/resource-crud-core": "0.1.52",
+    "@jskit-ai/resource-core": "0.1.52",
+    "@jskit-ai/uploads-runtime": "0.1.85",
     "json-rest-schema": "1.x.x"
   }
 }

package/src/server/common/repositories/userProfilesRepository.js

@@ -58,7 +58,8 @@ function normalizeProfileRecord(payload = null) {
     avatarStorageKey: normalizeNullableString(payload.avatarStorageKey),
     avatarVersion: normalizeNullableVersion(payload.avatarVersion),
     avatarUpdatedAt: payload.avatarUpdatedAt ? toIsoString(payload.avatarUpdatedAt) : null,
-    createdAt: payload.createdAt ? toIsoString(payload.createdAt) : null
+    createdAt: payload.createdAt ? toIsoString(payload.createdAt) : null,
+    updatedAt: payload.updatedAt ? toIsoString(payload.updatedAt) : null
   };
 }
 

package/src/shared/resources/userProfileResource.js

@@ -150,6 +150,14 @@ const userProfileResource = defineCrudResource({
         column: "created_at",
         writeSerializer: "datetime-utc"
       }
+    },
+    updatedAt: {
+      type: "dateTime",
+      default: "now()",
+      storage: {
+        column: "updated_at",
+        writeSerializer: "datetime-utc"
+      }
     }
   },
   messages: USER_PROFILE_OPERATION_MESSAGES,

package/templates/migrations/users_core_generic_initial.cjs

@@ -15,6 +15,7 @@ exports.up = async function up(knex) {
       table.string("avatar_version", 64).nullable();
       table.timestamp("avatar_updated_at", { useTz: false }).nullable();
       table.timestamp("created_at", { useTz: false }).notNullable().defaultTo(knex.fn.now());
+      table.timestamp("updated_at", { useTz: false }).notNullable().defaultTo(knex.fn.now());
       table.unique(["auth_provider", "auth_provider_user_sid"], "uq_users_identity");
       table.unique(["email"], "uq_users_email");
       table.unique(["username"], "uq_users_username");

package/templates/migrations/users_core_profile_updated_at.cjs

@@ -0,0 +1,48 @@
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.up = async function up(knex) {
+  const hasUsersTable = await knex.schema.hasTable("users");
+  if (!hasUsersTable) {
+    return;
+  }
+
+  const hasUpdatedAt = await knex.schema.hasColumn("users", "updated_at");
+  if (hasUpdatedAt) {
+    return;
+  }
+
+  await knex.schema.alterTable("users", (table) => {
+    table.timestamp("updated_at", { useTz: false }).nullable();
+  });
+
+  const hasCreatedAt = await knex.schema.hasColumn("users", "created_at");
+  await knex("users").whereNull("updated_at").update({
+    updated_at: hasCreatedAt
+      ? knex.raw("COALESCE(??, CURRENT_TIMESTAMP)", ["created_at"])
+      : knex.raw("CURRENT_TIMESTAMP")
+  });
+
+  await knex.schema.alterTable("users", (table) => {
+    table.timestamp("updated_at", { useTz: false }).notNullable().defaultTo(knex.fn.now()).alter();
+  });
+};
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.down = async function down(knex) {
+  const hasUsersTable = await knex.schema.hasTable("users");
+  if (!hasUsersTable) {
+    return;
+  }
+
+  const hasUpdatedAt = await knex.schema.hasColumn("users", "updated_at");
+  if (!hasUpdatedAt) {
+    return;
+  }
+
+  await knex.schema.alterTable("users", (table) => {
+    table.dropColumn("updated_at");
+  });
+};

package/templates/packages/users/src/shared/userResource.js

@@ -39,6 +39,14 @@ const resource = defineCrudResource({
       operations: {
         output: { required: true }
       }
+    },
+    updatedAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: {
+        output: { required: true }
+      }
     }
   },
   searchSchema: {

package/test/repositoryContracts.test.js

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { DEFAULT_USER_SETTINGS } from "../src/shared/settings.js";
+import { userProfileResource } from "../src/shared/resources/userProfileResource.js";
 import { createRepository as createUserProfilesRepository } from "../src/server/common/repositories/userProfilesRepository.js";
 import { createRepository as createUserSettingsRepository } from "../src/server/common/repositories/userSettingsRepository.js";
 
@@ -174,6 +175,133 @@ test("userProfilesRepository.upsert sends native JSON:API write documents with t
   assert.equal(record?.id, "11");
 });
 
+test("userProfilesRepository.upsert patches existing profiles with resource-backed updatedAt", async () => {
+  const trx = { trxId: "trx-1" };
+  const existingRecord = {
+    id: "7",
+    authProvider: "local",
+    authProviderUserSid: "local-user-7",
+    email: "ada@example.com",
+    username: "ada",
+    displayName: "Ada Example",
+    avatarStorageKey: null,
+    avatarVersion: null,
+    avatarUpdatedAt: null,
+    createdAt: "2026-04-20T00:00:00.000Z",
+    updatedAt: "2026-04-20T00:00:00.000Z"
+  };
+  let patchParams = null;
+  const repository = createUserProfilesRepository({
+    knex: createKnexStub(),
+    api: {
+      resources: {
+        userProfiles: {
+          async query({ queryParams }) {
+            const filters = queryParams?.filters || {};
+            if (Object.hasOwn(filters, "authProvider") || Object.hasOwn(filters, "authProviderUserSid")) {
+              return asCollectionDocument([existingRecord]);
+            }
+            if (Object.hasOwn(filters, "username")) {
+              return asCollectionDocument([]);
+            }
+            return asCollectionDocument([]);
+          },
+          async patch(params) {
+            patchParams = params;
+            const attributes = params.inputRecord?.data?.attributes || {};
+            return {
+              ...existingRecord,
+              ...attributes
+            };
+          }
+        }
+      }
+    }
+  });
+
+  const record = await repository.upsert({
+    authProvider: "local",
+    authProviderUserSid: "local-user-7",
+    email: " ADA.RENAMED@EXAMPLE.COM ",
+    displayName: "Ada Renamed"
+  }, { trx });
+
+  const attributes = patchParams?.inputRecord?.data?.attributes || {};
+  assert.equal(userProfileResource.schema.updatedAt?.type, "dateTime");
+  assert.equal(userProfileResource.schema.updatedAt?.storage?.column, "updated_at");
+  assert.equal(userProfileResource.schema.updatedAt?.storage?.writeSerializer, "datetime-utc");
+  assert.equal(patchParams?.transaction, trx);
+  assert.deepEqual(Object.keys(attributes).sort(), ["displayName", "email", "updatedAt", "username"]);
+  assert.equal(attributes.email, "ada.renamed@example.com");
+  assert.equal(attributes.displayName, "Ada Renamed");
+  assert.equal(attributes.username, "ada");
+  assert.ok(attributes.updatedAt instanceof Date);
+  assert.equal(record?.id, "7");
+  assert.equal(record?.updatedAt, attributes.updatedAt.toISOString());
+});
+
+test("userProfilesRepository profile patch helpers stamp updatedAt through the resource contract", async () => {
+  const trx = { trxId: "trx-1" };
+  const calls = [];
+  const repository = createUserProfilesRepository({
+    knex: createKnexStub(),
+    api: {
+      resources: {
+        userProfiles: {
+          async query() {
+            return asCollectionDocument([]);
+          },
+          async patch(params) {
+            calls.push(params);
+            const attributes = params.inputRecord?.data?.attributes || {};
+            return {
+              id: params.inputRecord?.data?.id || "7",
+              authProvider: "local",
+              authProviderUserSid: "local-user-7",
+              email: "ada@example.com",
+              username: "ada",
+              displayName: attributes.displayName || "Ada Example",
+              avatarStorageKey: attributes.avatarStorageKey ?? null,
+              avatarVersion: attributes.avatarVersion ?? null,
+              avatarUpdatedAt: attributes.avatarUpdatedAt ?? null,
+              createdAt: "2026-04-20T00:00:00.000Z",
+              updatedAt: attributes.updatedAt
+            };
+          }
+        }
+      }
+    }
+  });
+  const avatarUpdatedAt = new Date("2026-04-21T12:00:00.000Z");
+
+  await repository.updateDisplayNameById("7", "Ada Updated", { trx });
+  await repository.updateAvatarById("7", {
+    avatarStorageKey: "avatars/7.png",
+    avatarVersion: "v1",
+    avatarUpdatedAt
+  }, { trx });
+  await repository.clearAvatarById("7", { trx });
+
+  assert.equal(calls.length, 3);
+  for (const call of calls) {
+    assert.equal(call.transaction, trx);
+    assert.ok(call.inputRecord?.data?.attributes?.updatedAt instanceof Date);
+  }
+  assert.deepEqual(Object.keys(calls[0].inputRecord.data.attributes).sort(), ["displayName", "updatedAt"]);
+  assert.deepEqual(Object.keys(calls[1].inputRecord.data.attributes).sort(), [
+    "avatarStorageKey",
+    "avatarUpdatedAt",
+    "avatarVersion",
+    "updatedAt"
+  ]);
+  assert.equal(calls[1].inputRecord.data.attributes.avatarStorageKey, "avatars/7.png");
+  assert.equal(calls[1].inputRecord.data.attributes.avatarVersion, "v1");
+  assert.equal(calls[1].inputRecord.data.attributes.avatarUpdatedAt, avatarUpdatedAt);
+  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarStorageKey, null);
+  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarVersion, null);
+  assert.deepEqual(calls[2].inputRecord.data.attributes.avatarUpdatedAt, null);
+});
+
 test("userProfilesRepository.findByEmail normalizes email lookup", async () => {
   const { api, calls } = createUserProfilesApiStub({
     id: 7,

package/test/resourcesCanonical.test.js

@@ -38,6 +38,15 @@ test("users-core resources expose messages for all operations", () => {
   }
 });
 
+test("user profile resource exposes managed timestamps used by JSON REST writes", () => {
+  assert.equal(userProfileResource.schema.createdAt?.type, "dateTime");
+  assert.equal(userProfileResource.schema.createdAt?.storage?.column, "created_at");
+  assert.equal(userProfileResource.schema.createdAt?.storage?.writeSerializer, "datetime-utc");
+  assert.equal(userProfileResource.schema.updatedAt?.type, "dateTime");
+  assert.equal(userProfileResource.schema.updatedAt?.storage?.column, "updated_at");
+  assert.equal(userProfileResource.schema.updatedAt?.storage?.writeSerializer, "datetime-utc");
+});
+
 test("users-core specialized resource operations expose messages and validators", () => {
   const operationSpecs = [
     { label: "userProfile.avatarUpload", operation: userProfileResource.operations.avatarUpload },

package/test/usersPackageScaffoldContract.test.js

@@ -49,6 +49,37 @@ test("users-core installs the app-local users package scaffold", () => {
   }
 });
 
+test("users-core installs all users profile schema migrations", async () => {
+  const expectedMigrationIds = [
+    "users-core-generic-initial-schema",
+    "users-core-profile-username-schema",
+    "users-core-profile-updated-at-schema"
+  ];
+
+  for (const migrationId of expectedMigrationIds) {
+    const mutation = readFileMutationById(migrationId);
+    assert.ok(mutation, `Missing users-core migration mutation ${migrationId}.`);
+    assert.equal(mutation.op, "install-migration", `${migrationId} must install a migration.`);
+    assert.equal(mutation.toDir, "migrations", `${migrationId} must target app migrations.`);
+    assert.equal(mutation.category, "migration", `${migrationId} must be categorized as a migration.`);
+    assert.ok(mutation.from, `${migrationId} must define a migration template source.`);
+    assert.ok(mutation.reason, `${migrationId} must document why it exists.`);
+  }
+
+  const initialMigrationSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/migrations/users_core_generic_initial.cjs"),
+    "utf8"
+  );
+  const updatedAtMigrationSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/migrations/users_core_profile_updated_at.cjs"),
+    "utf8"
+  );
+
+  assert.match(initialMigrationSource, /table\.timestamp\("updated_at"/);
+  assert.match(updatedAtMigrationSource, /hasColumn\("users", "updated_at"\)/);
+  assert.match(updatedAtMigrationSource, /COALESCE\(\?\?, CURRENT_TIMESTAMP\)/);
+});
+
 test("users-core base users package templates stay aligned with non-workspace apps", async () => {
   const packageDescriptorSource = await readFile(
     path.join(PACKAGE_ROOT, "templates/packages/users/package.descriptor.mjs"),
@@ -181,4 +212,6 @@ test("users-core local users resource scaffold stays read-only and canonical", a
   assert.equal(typeof resource, "object");
   assert.deepEqual(Object.keys(resource.operations), ["list", "view"]);
   assert.equal(Object.hasOwn(resource.operations, "create"), false);
+  assert.equal(resource.schema.updatedAt?.type, "dateTime");
+  assert.equal(resource.schema.updatedAt?.storage?.writeSerializer, "datetime-utc");
 });