@jskit-ai/users-core 0.1.55 → 0.1.57

package/src/server/registerUsersCore.js

@@ -8,8 +8,8 @@ function registerUsersCore(app) {
 
   app.singleton("users.profile.sync.service", (scope) => {
     return createAuthProfileSyncService({
-      usersRepository: scope.make("usersRepository"),
-      userSettingsRepository: scope.make("userSettingsRepository"),
+      userProfilesRepository: scope.make("internal.repository.user-profiles"),
+      userSettingsRepository: scope.make("internal.repository.user-settings"),
       lifecycleContributors: resolveProfileSyncLifecycleContributors(scope)
     });
   });

package/src/server/usersBootstrapContributor.js

@@ -97,7 +97,7 @@ function mapUserSettingsBootstrap(settings = {}) {
 }
 
 function createUsersBootstrapContributor({
-  usersRepository,
+  userProfilesRepository,
   userSettingsRepository,
   appConfig = {},
   authService
@@ -105,11 +105,11 @@ function createUsersBootstrapContributor({
   const contributorId = "users.bootstrap";
   const appState = resolveAppState(appConfig);
 
-  requireServiceMethod(usersRepository, "findById", contributorId, {
-    serviceLabel: "usersRepository"
+  requireServiceMethod(userProfilesRepository, "findById", contributorId, {
+    serviceLabel: "internal.repository.user-profiles"
   });
   requireServiceMethod(userSettingsRepository, "ensureForUserId", contributorId, {
-    serviceLabel: "userSettingsRepository"
+    serviceLabel: "internal.repository.user-settings"
   });
 
   return Object.freeze({
@@ -138,7 +138,7 @@ function createUsersBootstrapContributor({
       });
 
       if (normalizedUser) {
-        const latestProfile = (await usersRepository.findById(normalizedUser.id)) || normalizedUser;
+        const latestProfile = (await userProfilesRepository.findById(normalizedUser.id)) || normalizedUser;
         const userSettings = await userSettingsRepository.ensureForUserId(latestProfile.id);
 
         payload = {

package/src/shared/resources/userProfileResource.js

@@ -91,7 +91,7 @@ const avatarOperationOutputValidator = Object.freeze({
 const USER_PROFILE_OPERATION_MESSAGES = createOperationMessages();
 
 const userProfileResource = Object.freeze({
-  resource: "userProfile",
+  namespace: "userProfile",
   operations: Object.freeze({
     view: Object.freeze({
       method: "GET",

package/src/shared/resources/userSettingsFields.js

@@ -24,9 +24,13 @@ function defineField(field = {}) {
   if (!field.outputSchema || typeof field.outputSchema !== "object") {
     throw new TypeError(`userSettingsFields.defineField("${key}") requires outputSchema.`);
   }
-  const dbColumn = normalizeText(field.dbColumn);
-  if (!dbColumn) {
-    throw new TypeError(`userSettingsFields.defineField("${key}") requires dbColumn.`);
+  const repository = field?.repository;
+  if (!repository || typeof repository !== "object" || Array.isArray(repository)) {
+    throw new TypeError(`userSettingsFields.defineField("${key}") requires repository.column.`);
+  }
+  const repositoryColumn = normalizeText(repository.column);
+  if (!repositoryColumn) {
+    throw new TypeError(`userSettingsFields.defineField("${key}") requires repository.column.`);
   }
   const section = normalizeLowerText(field.section);
   if (!USER_SETTINGS_SECTION_VALUES.includes(section)) {
@@ -47,7 +51,9 @@ function defineField(field = {}) {
   userSettingsFields.push({
     key,
     section,
-    dbColumn,
+    repository: Object.freeze({
+      column: repositoryColumn
+    }),
     required: field.required !== false,
     includeInBootstrap: field.includeInBootstrap !== false,
     inputSchema: field.inputSchema,

package/src/shared/resources/userSettingsResource.js

@@ -311,7 +311,7 @@ const emptyBodyValidator = Object.freeze({
 const USER_SETTINGS_OPERATION_MESSAGES = createOperationMessages();
 
 const userSettingsResource = Object.freeze({
-  resource: "userSettings",
+  namespace: "userSettings",
   operations: Object.freeze({
     view: Object.freeze({
       method: "GET",

package/templates/packages/main/src/shared/resources/userSettingsFields.js

@@ -20,7 +20,7 @@ resetUserSettingsFields();
 defineField({
   key: "theme",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "theme",
+  repository: { column: "theme" },
   required: true,
   inputSchema: Type.String({ minLength: 1, maxLength: 32 }),
   outputSchema: Type.String({ minLength: 1, maxLength: 32 }),
@@ -32,7 +32,7 @@ defineField({
 defineField({
   key: "locale",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "locale",
+  repository: { column: "locale" },
   required: true,
   inputSchema: Type.String({ minLength: 1, maxLength: 24 }),
   outputSchema: Type.String({ minLength: 1, maxLength: 24 }),
@@ -44,7 +44,7 @@ defineField({
 defineField({
   key: "timeZone",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "time_zone",
+  repository: { column: "time_zone" },
   required: true,
   inputSchema: Type.String({ minLength: 1, maxLength: 64 }),
   outputSchema: Type.String({ minLength: 1, maxLength: 64 }),
@@ -56,7 +56,7 @@ defineField({
 defineField({
   key: "dateFormat",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "date_format",
+  repository: { column: "date_format" },
   required: true,
   inputSchema: Type.String({ minLength: 1, maxLength: 32 }),
   outputSchema: Type.String({ minLength: 1, maxLength: 32 }),
@@ -68,7 +68,7 @@ defineField({
 defineField({
   key: "numberFormat",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "number_format",
+  repository: { column: "number_format" },
   required: true,
   inputSchema: Type.String({ minLength: 1, maxLength: 32 }),
   outputSchema: Type.String({ minLength: 1, maxLength: 32 }),
@@ -80,7 +80,7 @@ defineField({
 defineField({
   key: "currencyCode",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "currency_code",
+  repository: { column: "currency_code" },
   required: true,
   inputSchema: Type.String({ minLength: 3, maxLength: 3, pattern: "^[A-Za-z]{3}$" }),
   outputSchema: Type.String({ minLength: 3, maxLength: 3, pattern: "^[A-Z]{3}$" }),
@@ -92,7 +92,7 @@ defineField({
 defineField({
   key: "avatarSize",
   section: USER_SETTINGS_SECTIONS.PREFERENCES,
-  dbColumn: "avatar_size",
+  repository: { column: "avatar_size" },
   required: true,
   inputSchema: Type.Integer({ minimum: 1 }),
   outputSchema: Type.Integer({ minimum: 1 }),
@@ -104,7 +104,7 @@ defineField({
 defineField({
   key: "productUpdates",
   section: USER_SETTINGS_SECTIONS.NOTIFICATIONS,
-  dbColumn: "notify_product_updates",
+  repository: { column: "notify_product_updates" },
   required: true,
   inputSchema: Type.Boolean(),
   outputSchema: Type.Boolean(),
@@ -116,7 +116,7 @@ defineField({
 defineField({
   key: "accountActivity",
   section: USER_SETTINGS_SECTIONS.NOTIFICATIONS,
-  dbColumn: "notify_account_activity",
+  repository: { column: "notify_account_activity" },
   required: true,
   inputSchema: Type.Boolean(),
   outputSchema: Type.Boolean(),
@@ -128,7 +128,7 @@ defineField({
 defineField({
   key: "securityAlerts",
   section: USER_SETTINGS_SECTIONS.NOTIFICATIONS,
-  dbColumn: "notify_security_alerts",
+  repository: { column: "notify_security_alerts" },
   required: true,
   inputSchema: Type.Boolean(),
   outputSchema: Type.Boolean(),

package/templates/packages/users/package.descriptor.mjs

@@ -0,0 +1,65 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/users",
+  version: "0.1.0",
+  kind: "runtime",
+  description: "App-local CRUD package (users).",
+  dependsOn: [
+    "@jskit-ai/auth-core",
+    "@jskit-ai/crud-core",
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/users-core"
+  ],
+  capabilities: {
+    provides: [
+      "crud.users"
+    ],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "auth.policy"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/UsersProvider.js",
+          export: "UsersProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/actionIds",
+          summary: "App-local CRUD public action identifiers."
+        },
+        {
+          subpath: "./shared",
+          summary: "App-local CRUD shared resource."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "repository.users",
+          "crud.users"
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {},
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: []
+  }
+});

package/templates/packages/users/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@local/users",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/actionIds": "./src/server/actionIds.js",
+    "./shared": "./src/shared/index.js"
+  }
+}

package/templates/packages/users/src/server/UsersProvider.js

@@ -0,0 +1,91 @@
+import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
+import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
+import {
+  createCrudLookupResolver,
+  createCrudLookup
+} from "@jskit-ai/crud-core/server/lookups";
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { createRepository } from "./repository.js";
+import {
+  createService,
+  serviceEvents
+} from "./service.js";
+import { createActions } from "./actions.js";
+import { registerRoutes } from "./registerRoutes.js";
+
+const CRUD_MODULE_CONFIG = Object.freeze({
+  namespace: "users",
+  surface: "home",
+  ownershipFilter: "public",
+  relativePath: "/users"
+});
+
+function resolveCrudPolicyFromApp(app) {
+  return resolveCrudSurfacePolicyFromAppConfig(CRUD_MODULE_CONFIG, resolveAppConfig(app), {
+    context: "UsersProvider"
+  });
+}
+
+class UsersProvider {
+  static id = "crud.users";
+
+  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main"];
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
+      throw new Error("UsersProvider requires application singleton()/service()/actions().");
+    }
+
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+
+    app.singleton("repository.users", (scope) => {
+      const knex = scope.make("jskit.database.knex");
+      return createRepository(knex, {
+        resolveLookup: createCrudLookupResolver(scope)
+      });
+    });
+
+    app.singleton("lookup.users", (scope) => {
+      return createCrudLookup(scope.make("repository.users"), {
+        ownershipFilter: crudPolicy.ownershipFilter
+      });
+    });
+
+    app.service(
+      "crud.users",
+      (scope) => {
+        return createService({
+          usersRepository: scope.make("repository.users")
+        });
+      },
+      {
+        events: serviceEvents
+      }
+    );
+
+    app.actions(
+      withActionDefaults(
+        createActions({
+          surface: crudPolicy.surfaceId
+        }),
+        {
+          domain: "crud",
+          dependencies: {
+            usersService: "crud.users"
+          }
+        }
+      )
+    );
+  }
+
+  boot(app) {
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+    registerRoutes(app, {
+      routeOwnershipFilter: crudPolicy.ownershipFilter,
+      routeSurface: crudPolicy.surfaceId,
+      routeRelativePath: crudPolicy.relativePath
+    });
+  }
+}
+
+export { UsersProvider };

package/templates/packages/users/src/server/actionIds.js

@@ -0,0 +1,6 @@
+const actionIds = Object.freeze({
+  list: "crud.users.list",
+  view: "crud.users.view"
+});
+
+export { actionIds };

package/templates/packages/users/src/server/actions.js

@@ -0,0 +1,73 @@
+import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
+import {
+  createCrudCursorPaginationQueryValidator,
+  listSearchQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
+import { resource } from "../shared/userResource.js";
+import { actionIds } from "./actionIds.js";
+import { LIST_CONFIG } from "./listConfig.js";
+
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+const authenticatedPermission = Object.freeze({
+  require: "authenticated"
+});
+
+function requireActionSurface(surface = "") {
+  const normalizedSurface = String(surface || "").trim().toLowerCase();
+  if (!normalizedSurface) {
+    throw new TypeError("createActions requires a non-empty surface.");
+  }
+
+  return normalizedSurface;
+}
+
+function createActions({ surface = "" } = {}) {
+  const actionSurface = requireActionSurface(surface);
+
+  return Object.freeze([
+    {
+      id: actionIds.list,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: authenticatedPermission,
+      inputValidator: [listCursorPaginationQueryValidator, listSearchQueryValidator],
+      outputValidator: resource.operations.list.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.list
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.usersService.listRecords(input, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.view,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: authenticatedPermission,
+      inputValidator: recordIdParamsValidator,
+      outputValidator: resource.operations.view.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.view
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.usersService.getRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    }
+  ]);
+}
+
+export { createActions };

package/templates/packages/users/src/server/listConfig.js

@@ -0,0 +1,16 @@
+const LIST_CONFIG = Object.freeze({
+  searchColumns: ["display_name", "email", "username"],
+  orderBy: [
+    {
+      column: "display_name",
+      direction: "asc",
+      nulls: "last"
+    },
+    {
+      column: "email",
+      direction: "asc"
+    }
+  ]
+});
+
+export { LIST_CONFIG };

package/templates/packages/users/src/server/registerRoutes.js

@@ -0,0 +1,87 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  createCrudCursorPaginationQueryValidator,
+  listSearchQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
+import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
+import { checkRouteVisibility } from "@jskit-ai/kernel/shared/support/visibility";
+import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
+import { actionIds } from "./actionIds.js";
+import { LIST_CONFIG } from "./listConfig.js";
+import { resource } from "../shared/userResource.js";
+
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+
+function registerRoutes(
+  app,
+  {
+    routeOwnershipFilter = "public",
+    routeSurface = "",
+    routeRelativePath = ""
+  } = {}
+) {
+  const router = app.make("jskit.http.router");
+  const normalizedRouteSurface = normalizeSurfaceId(routeSurface);
+  const routeBase = resolveScopedApiBasePath({
+    routeBase: "/",
+    relativePath: routeRelativePath,
+    strictParams: false
+  });
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
+      meta: {
+        tags: ["crud"],
+        summary: "List users."
+      },
+      queryValidator: [listCursorPaginationQueryValidator, listSearchQueryValidator],
+      responseValidators: withStandardErrorResponses({
+        200: resource.operations.list.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.list,
+        input: {
+          ...(request.input.query || {})
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
+      meta: {
+        tags: ["crud"],
+        summary: "View a user."
+      },
+      paramsValidator: recordIdParamsValidator,
+      responseValidators: withStandardErrorResponses({
+        200: resource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.view,
+        input: {
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

package/templates/packages/users/src/server/repository.js

@@ -0,0 +1,41 @@
+import { createCrudResourceRuntime } from "@jskit-ai/crud-core/server/resourceRuntime";
+import { resource } from "../shared/userResource.js";
+import { LIST_CONFIG } from "./listConfig.js";
+
+const REPOSITORY_CONFIG = Object.freeze({
+  context: "users repository",
+  list: LIST_CONFIG
+});
+
+function createRepository(knex, options = {}) {
+  const resourceRuntime = createCrudResourceRuntime(resource, knex, {
+    ...options,
+    ...REPOSITORY_CONFIG
+  });
+
+  async function list(query = {}, callOptions = {}) {
+    return resourceRuntime.list(query, callOptions);
+  }
+
+  async function findById(recordId, callOptions = {}) {
+    return resourceRuntime.findById(recordId, callOptions);
+  }
+
+  async function listByIds(ids = [], callOptions = {}) {
+    return resourceRuntime.listByIds(ids, callOptions);
+  }
+
+  async function listByForeignIds(ids = [], foreignKey = "", callOptions = {}) {
+    return resourceRuntime.listByForeignIds(ids, foreignKey, callOptions);
+  }
+
+  return Object.freeze({
+    withTransaction: resourceRuntime.withTransaction,
+    list,
+    findById,
+    listByIds,
+    listByForeignIds
+  });
+}
+
+export { createRepository };

package/templates/packages/users/src/server/service.js

@@ -0,0 +1,28 @@
+import {
+  createCrudServiceRuntime,
+  crudServiceListRecords,
+  crudServiceGetRecord
+} from "@jskit-ai/crud-core/server/serviceMethods";
+import { resource } from "../shared/userResource.js";
+
+const serviceRuntime = createCrudServiceRuntime(resource, {
+  context: "usersService"
+});
+const serviceEvents = Object.freeze({});
+
+function createService({ usersRepository } = {}) {
+  if (!usersRepository) {
+    throw new TypeError("createService requires usersRepository.");
+  }
+
+  return Object.freeze({
+    listRecords(query = {}, options = {}) {
+      return crudServiceListRecords(serviceRuntime, usersRepository, {}, query, options);
+    },
+    getRecord(recordId, options = {}) {
+      return crudServiceGetRecord(serviceRuntime, usersRepository, {}, recordId, options);
+    }
+  });
+}
+
+export { createService, serviceEvents };

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

@@ -0,0 +1 @@
+export { resource } from "./userResource.js";

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

@@ -0,0 +1,74 @@
+import { Type } from "typebox";
+import { toIsoString } from "@jskit-ai/database-runtime/shared";
+import {
+  createCursorListValidator,
+  normalizeObjectInput,
+  recordIdSchema
+} from "@jskit-ai/kernel/shared/validators";
+import {
+  normalizeIfPresent,
+  normalizeRecordId,
+  normalizeText
+} from "@jskit-ai/kernel/shared/support/normalize";
+
+const recordOutputSchema = Type.Object(
+  {
+    id: recordIdSchema,
+    name: Type.String({ minLength: 1 }),
+    email: Type.String(),
+    username: Type.String(),
+    createdAt: Type.String({ format: "date-time", minLength: 1 })
+  },
+  { additionalProperties: false }
+);
+
+const createBodySchema = Type.Object({}, { additionalProperties: false });
+
+const recordOutputValidator = Object.freeze({
+  schema: recordOutputSchema,
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+
+    return {
+      id: normalizeIfPresent(source.id, normalizeRecordId),
+      name: normalizeText(source.name || source.email || source.username || source.id),
+      email: normalizeText(source.email),
+      username: normalizeText(source.username),
+      createdAt: normalizeIfPresent(source.createdAt, toIsoString)
+    };
+  }
+});
+
+const createBodyValidator = Object.freeze({
+  schema: createBodySchema,
+  normalize: normalizeObjectInput
+});
+
+const resource = Object.freeze({
+  namespace: "users",
+  tableName: "users",
+  idColumn: "id",
+  operations: Object.freeze({
+    list: Object.freeze({
+      method: "GET",
+      outputValidator: createCursorListValidator(recordOutputValidator)
+    }),
+    view: Object.freeze({
+      method: "GET",
+      outputValidator: recordOutputValidator
+    }),
+    create: Object.freeze({
+      method: "POST",
+      bodyValidator: createBodyValidator,
+      outputValidator: recordOutputValidator
+    })
+  }),
+  fieldMeta: Object.freeze([
+    Object.freeze({
+      key: "name",
+      repository: { column: "display_name" }
+    })
+  ])
+});
+
+export { resource };