@internetderdinge/api 1.224.2

package/.github/copilot-instructions.md

@@ -0,0 +1,77 @@
+# GitHub Copilot Instructions
+
+## Project Overview
+
+This is a NodeJS/Express API codebase (part of a monorepo workspace) using TypeScript (ESM). It serves as a shared library of API modules (`@internetderdinge/api`) used by other applications.
+
+## Architecture & Code Organization
+
+- **Pattern**: Modular, feature-based architecture. Each domain entity (Users, Devices, etc.) has its own folder containing:
+  - `*.route.ts`: Router definition and OpenAPI/Swagger configuration.
+  - `*.controller.ts`: Request parsing and response handling.
+  - `*.service.ts`: Business logic and database interactions.
+  - `*.model.ts`: Mongoose schema and interface definitions.
+  - `*.validation.ts`: Zod schemas for request validation (`body`, `query`, `params`).
+  - `*.schemas.ts`: Zod schemas for response objects (OpenAPI definitions).
+
+- **Data Access**: MongoDB with Mongoose.
+- **Validation**: Zod (preferred) for both runtime validation and OpenAPI generation. Joi is present but legacy.
+
+## Key Development Patterns
+
+### 1. Route Definitions
+
+Routes are defined declaratively using a `RouteSpec` array and `buildRouterAndDocs`. **Do not** simply write `router.get(...)`.
+
+- Define an array of `RouteSpec` objects.
+- Include `method`, `path`, `validate` (middleware), `requestSchema` (validation), `responseSchema` (docs), and `handler`.
+- Bind the router at the end of the file: `buildRouterAndDocs(router, routeSpecs, ...)`
+
+```typescript
+// Example from users.route.ts
+export const userRouteSpecs: RouteSpec[] = [
+  {
+    method: "post",
+    path: "/",
+    validate: [auth("manageUsers"), validateBodyOrganization],
+    requestSchema: createUserSchema,
+    responseSchema: createUserResponseSchema,
+    handler: userController.createUser,
+    summary: "...",
+  },
+];
+```
+
+### 2. Request Validation
+
+Use the `validateZod` middleware. Define schemas in `*.validation.ts`.
+
+- Export an object matching `{ body: z.object(...), query: ..., params: ... }`.
+- Use custom Zod helpers from `../utils/zValidations.js` (e.g., `zObjectId`, `zPagination`).
+
+### 3. Database & Models
+
+- Interfaces: Define `I[Entity]`, `I[Entity]Document` (extends `I[Entity], Document`), and `I[Entity]Model` (extends `Model<I[Entity]Document>`).
+- Plugins: Always apply `toJSON` and `paginate` plugins in the schema.
+- Reference: `src/users/users.model.ts` is the canonical example.
+
+### 4. Controllers & Async
+
+- Always wrap controller functions with `catchAsync`.
+- Do not use `try/catch` blocks inside controllers unless handling specific non-fatal errors; let global error handler catch exceptions.
+- Throw `ApiError` for known application errors: `throw new ApiError(httpStatus.NOT_FOUND, 'User not found');`.
+
+## Tech Stack & Libraries
+
+- **Runtime**: Node.js >= 24
+- **Framework**: Express v5
+- **ORM**: Mongoose
+- **Validation**: Zod (with `@asteasolutions/zod-to-openapi`)
+- **Main Dependencies**: `http-status`, `winston`, `auth0`, `googleapis`.
+- **Testing**: `vitest`.
+
+## Specific Conventions
+
+- **Naming**: camelCase for files and functions.
+- **Imports**: Use `.js` extension for local imports (ESM requirement in TypeScript).
+- **Environment**: Configuration via `dotenv` and `checkJwt` for Auth0.

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [1.224.2](https://dev.azure.com/wirewire/memo/_git/memo-mono/compare/v1.224.1...v1.224.2) (2026-02-07)
+
+
+### Bug Fixes
+
+* **iot:** updated private ([560732f](https://dev.azure.com/wirewire/memo/_git/memo-mono/commits/560732fe697e55ff5496801cff4d3d7aff0df4b0))

package/README.md

@@ -0,0 +1,52 @@
+# @wirewire/openiot-api
+
+Shared OpenIoT API modules used by IoT hardware. This package provides prebuilt Express routers and shared middleware/models for OpenIoT-related features.
+
+## Requirements
+
+- Node.js >= 24
+- Yarn (workspace dependency management)
+
+## Install (workspace)
+
+From the repo root:
+
+- `yarn install`
+
+## Build
+
+From the repo root:
+
+- `yarn --cwd packages/openiot-api build`
+
+## Lint
+
+From the repo root:
+
+- `yarn --cwd packages/openiot-api lint`
+
+## Usage
+
+This package is ESM (`"type": "module"`). Import the routers and mount them in an Express app:
+
+- `usersRoute`
+- `accountsRoute`
+- `organizationsRoute`
+- `devicesRoute`
+- `devicesNotificationsRoute`
+- `pdfRoute`
+- `tokensRoute`
+
+Example:
+
+- `import { usersRoute } from "@wirewire/openiot-api";`
+- `app.use("/users", usersRoute);`
+
+## Source layout
+
+- `src/*`: Routers, middleware, models, validation, utils
+- `src/index.ts`: Public exports
+
+## Notes
+
+- This is a private workspace package and is not published publicly.

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@internetderdinge/api",
+  "version": "1.224.2",
+  "description": "Shared OpenIoT API modules",
+  "main": "src/index.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^7.3.2",
+    "@aws-sdk/client-cloudwatch-events": "^3.216.0",
+    "@aws-sdk/client-s3": "^3.216.0",
+    "@aws-sdk/client-sesv2": "^3.328.0",
+    "@aws-sdk/credential-provider-node": "^3.830.0",
+    "@aws-sdk/lib-storage": "^3.216.0",
+    "@aws-sdk/s3-request-presigner": "^3.216.0",
+    "@aws-sdk/util-endpoints": "^3.216.0",
+    "@sentry/node": "^10.25.0",
+    "@sentry/profiling-node": "^10.25.0",
+    "@wirewire/fhir": "^1.212.0",
+    "@wirewire/fhir-helpers": "^1.212.0",
+    "@wirewire/helpers": "^1.223.0",
+    "agenda": "^5.0.0",
+    "agendash": "^4.0.0",
+    "auth0": "^4.23.1",
+    "aws-crt": "^1.27.3",
+    "aws-iot-device-sdk-v2": "^1.22.0",
+    "aws-sdk": "^2.1261.0",
+    "aws4": "^1.11.0",
+    "axios": "^1.9.0",
+    "body-parser": "~1.15.0",
+    "body-parser-xml": "~1.1.0",
+    "canvas": "^3.1.0",
+    "compression": "^1.8.0",
+    "config": "^4.0.0",
+    "cors": "^2.8.5",
+    "cron": "^4.3.1",
+    "date-fns": "^2.28.0",
+    "date-fns-tz": "2.0.0",
+    "dotenv": "^10.0.0",
+    "elevenlabs": "^0.5.0",
+    "express": "^5.1.0",
+    "express-jwt": "^8.5.1",
+    "express-mongo-sanitize": "^2.2.0",
+    "express-rate-limit": "^7.5.0",
+    "express-ws": "^5.0.2",
+    "firebase-admin": "^11.0.0",
+    "googleapis": "^144.0.0",
+    "he": "^1.2.0",
+    "helmet": "^4.1.0",
+    "http-status": "^1.4.0",
+    "https": "^1.0.0",
+    "i18next": "^23.10.1",
+    "joi": "^17.3.0",
+    "js-yaml": "^3.8.4",
+    "jsonwebtoken": "^8.5.1",
+    "jwks-rsa": "^2.0.3",
+    "moment": "^2.24.0",
+    "moment-timezone": "^0.5.34",
+    "mongoose": "^8.15.1",
+    "morgan": "^1.9.1",
+    "multer": "^1.4.5-lts.1",
+    "multer-s3": "^3.0.1",
+    "multiparty": "~4.1.2",
+    "node-uuid": "~1.4.7",
+    "nodemailer": "^6.3.1",
+    "openai": "^5.0.1",
+    "passport": "^0.4.0",
+    "passport-jwt": "^4.0.0",
+    "path": "~0.12.7",
+    "pixelmatch": "^7.1.0",
+    "promise": "~8.3.0",
+    "puppeteer": "^24.9.0",
+    "qs": "^6.14.0",
+    "request": "^2.81.0",
+    "rrule": "^2.7.1",
+    "sharp": "^0.33.5",
+    "stripe": "^12.6.0",
+    "swagger-ui-express": "^5.0.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "validator": "^13.0.0",
+    "winston": "^3.2.1",
+    "xss-clean": "^0.1.4",
+    "zod": "^3.20.2"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9",
+    "coveralls": "^3.1.1",
+    "eslint": "^7.0.0",
+    "eslint-config-airbnb-base": "^14.0.0",
+    "eslint-config-prettier": "^8.1.0",
+    "eslint-plugin-import": "^2.18.2",
+    "eslint-plugin-prettier": "^3.1.1",
+    "eslint-plugin-security": "^1.4.0",
+    "faker": "^5.1.0",
+    "husky": "^5.1.2",
+    "lint-staged": "^10.0.7",
+    "node-mocks-http": "^1.8.0",
+    "nodemon": "^3.1.10",
+    "prettier": "^3.5.3",
+    "supertest": "^7.1.1",
+    "vitest": "^2.1.9"
+  },
+  "gitHead": "9556e8e376045c1e532aded7ec7132818190fa91"
+}

package/src/accounts/accounts.controller.ts

@@ -0,0 +1,166 @@
+import type { Request, Response } from "express";
+import httpStatus from "http-status";
+import deviceNotifications from "../devicesNotifications/devicesNotifications.service";
+import ApiError from "../utils/ApiError.js";
+import catchAsync from "../utils/catchAsync.js";
+import * as accountsService from "./accounts.service.js";
+
+interface AuthenticatedRequest extends Request {
+  auth: {
+    sub: string;
+  };
+}
+
+interface Device {
+  fck: string;
+}
+
+interface UpdateBody {
+  given_name?: string;
+  family_name?: string;
+  email?: string;
+  notification?: any;
+  [key: string]: any;
+}
+
+const getAccountById = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const account = await accountsService.getAccountById(req.auth.sub);
+
+    const entryDeviceNotifications = await deviceNotifications.getByUser(
+      req.auth.sub,
+    );
+
+    if (!account) {
+      throw new ApiError(httpStatus.NOT_FOUND, "Account not found");
+    }
+    res.send({
+      ...account.data,
+      notification: entryDeviceNotifications?.settings,
+    });
+  },
+);
+
+const setDeviceToken = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const account = await accountsService.getAccountById(req.auth.sub);
+
+    const devices: Device[] = account.data.app_metadata.devices || [];
+    const alreadyExisting = devices.find((d) => d.fck === req.body.token);
+    if (!alreadyExisting) {
+      devices.push({ fck: req.body.token });
+    }
+    const update = {
+      ...account.app_metadata,
+      devices: devices.slice(Math.max(devices.length - 3, 1)),
+    };
+    const entry = await accountsService.updateMetaDataById(
+      req.auth.sub,
+      update,
+    );
+    res.send(entry);
+  },
+);
+
+const avatar = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const avatarImage = await auth0.avatar(req.auth.sub);
+    res.send(avatarImage);
+  },
+);
+
+const updateEntry = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const account = await accountsService.getAccountById(req.auth.sub);
+
+    const { isSocial } = account?.data.identities[0];
+
+    const {
+      given_name,
+      family_name,
+      email,
+      notification,
+      ...updateBody
+    }: UpdateBody = req.body;
+
+    const trimmedGivenName =
+      typeof given_name === "string" ? given_name.trim() : undefined;
+    const trimmedFamilyName =
+      typeof family_name === "string" ? family_name.trim() : undefined;
+    const hasGivenName = !!trimmedGivenName;
+    const hasFamilyName = !!trimmedFamilyName;
+
+    const update = isSocial
+      ? {
+          ...account.data.app_metadata,
+          ...updateBody,
+          ...(hasGivenName ? { first_name: trimmedGivenName } : {}),
+          ...(hasFamilyName ? { last_name: trimmedFamilyName } : {}),
+        }
+      : updateBody;
+    const entry = await accountsService.updateMetaDataById(
+      req.auth.sub,
+      update,
+    );
+
+    if (notification) {
+      await deviceNotifications.updateByUserId(req.auth.sub, {
+        settings: notification,
+      });
+    }
+
+    if (!isSocial && (hasGivenName || hasFamilyName || email)) {
+      try {
+        await accountsService.updateUserById(req.auth.sub, {
+          ...(hasGivenName ? { given_name: trimmedGivenName } : {}),
+          ...(hasFamilyName ? { family_name: trimmedFamilyName } : {}),
+          ...(email ? { email } : {}),
+        });
+      } catch (error: any) {
+        console.error("error", error.message);
+        throw new ApiError(httpStatus.CONFLICT, error.message);
+      }
+    }
+    res.send(entry);
+  },
+);
+
+const deleteCurrent = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const entry = await accountsService.deleteById(req.auth.sub);
+    res.send(entry);
+  },
+);
+
+const current = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const user = await accountsService.getAccountById(req.auth.sub);
+    res.send(user.data);
+  },
+);
+
+const mfaEnroll = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const { mfaEnroll } = req.body;
+    const user = await accountsService.mfaEnroll(req.auth.sub, mfaEnroll);
+    res.send(user);
+  },
+);
+
+const mfaDisable = catchAsync(
+  async (req: AuthenticatedRequest, res: Response): Promise<void> => {
+    const user = await accountsService.mfaDisable(req.auth.sub);
+    res.send(user);
+  },
+);
+
+export {
+  avatar,
+  getAccountById,
+  current,
+  setDeviceToken,
+  mfaEnroll,
+  updateEntry,
+  deleteCurrent,
+  mfaDisable,
+};

package/src/accounts/accounts.route.ts

@@ -0,0 +1,107 @@
+import { Router } from "express";
+import buildRouterAndDocs from "../utils/buildRouterAndDocs.js";
+import auth from "../middlewares/auth.js";
+import { validateOrganization } from "../middlewares/validateOrganization.js";
+import validateCurrentUser from "../middlewares/validateCurrentUser.js";
+import type { RouteSpec } from "../types/routeSpec";
+import * as accountsValidation from "./accounts.validation.js";
+import * as accountsController from "./accounts.controller.js";
+import { accountResponseSchema } from "./accounts.schemas.js";
+import { validateParamsAccount } from "../middlewares/validateCurrentAuthUser.js";
+
+export const accountsRouteSpecs: RouteSpec[] = [
+  {
+    method: "get",
+    path: "/current",
+    validate: [auth("manageUsers")],
+    requestSchema: accountsValidation.currentAccountSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.current,
+    summary: "Get the current account",
+  },
+  {
+    method: "post",
+    path: "/current/mfa/enroll",
+    validate: [auth("manageUsers")],
+    requestSchema: accountsValidation.currentAccountMfaEnrollSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.mfaEnroll,
+    summary: "Enroll current account in MFA",
+  },
+  {
+    method: "post",
+    path: "/current/mfa/disable",
+    validate: [auth("manageUsers")],
+    requestSchema: accountsValidation.currentAccountMfaEnrollSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.mfaDisable,
+    summary: "Disable current account MFA",
+  },
+  {
+    method: "post",
+    path: "/:accountId/setDeviceToken",
+    validate: [auth("manageUsers"), validateParamsAccount],
+    requestSchema: accountsValidation.setDeviceTokenSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.setDeviceToken,
+    summary: "Set a device token for an account",
+  },
+  {
+    method: "get",
+    path: "/:accountId/avatar.jpg",
+    validate: [auth("manageUsers")],
+    requestSchema: accountsValidation.getAvatarSchema,
+    responseSchema: accountResponseSchema, // or a binary/blob schema if you have one
+    privateDocs: true,
+    handler: accountsController.avatar,
+    summary: "Fetch account avatar",
+  },
+  {
+    method: "delete",
+    path: "/deleteCurrent",
+    validate: [auth("manageUsers")],
+    requestSchema: accountsValidation.deleteCurrentSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.deleteCurrent,
+    summary: "Delete the current account",
+  },
+  {
+    method: "get",
+    path: "/:accountId",
+    validate: [auth("getUsers"), validateParamsAccount],
+    requestSchema: accountsValidation.getAccountSchema,
+    responseSchema: accountResponseSchema,
+    handler: accountsController.getAccountById,
+    summary: "Get an account by ID",
+  },
+  {
+    method: "post",
+    path: "/:accountId",
+    validate: [auth("manageUsers"), validateParamsAccount],
+    requestSchema: accountsValidation.updateAccountSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.updateEntry,
+    summary: "Create or replace an account by ID",
+  },
+  {
+    method: "patch",
+    path: "/:accountId",
+    validate: [auth("manageUsers"), validateParamsAccount],
+    requestSchema: accountsValidation.updateAccountSchema,
+    responseSchema: accountResponseSchema,
+    privateDocs: true,
+    handler: accountsController.updateEntry,
+    summary: "Update fields on an account by ID",
+  },
+];
+
+const router: Router = Router();
+buildRouterAndDocs(router, accountsRouteSpecs, "/accounts", ["Accounts"]);
+
+export default router;

package/src/accounts/accounts.schemas.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+export const accountResponseSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  organizationId: z.string().uuid(),
+  roles: z.array(z.string()), // e.g. ['admin','user']
+  isMfaEnabled: z.boolean(),
+  createdAt: z.string(), // ISO timestamp
+  updatedAt: z.string(), // ISO timestamp
+});
+
+// If you ever need the TS type:
+export type AccountResponse = z.infer<typeof accountResponseSchema>;

package/src/accounts/accounts.service.ts

@@ -0,0 +1,85 @@
+import { auth0, mfaDisableAccount, mfaEnrollAccount } from "./auth0.service.js";
+
+type ObjectId = string; // Replace with the actual ObjectId type if available
+type Stock = any; // Replace with the actual Stock type if available
+
+/**
+ * Get user by id
+ * @param {ObjectId} id
+ * @returns {Promise<Stock>}
+ */
+export const getAccountById = async (id: ObjectId): Promise<Stock> => {
+  return auth0.users.get({ id });
+};
+
+/**
+ * Get user by email
+ * @param {string} email
+ * @returns {Promise<Stock>}
+ */
+/* 
+export const getAccountByEmail = async (email: string): Promise<Stock> => {
+  return auth0.getUsersByEmail(email); // Fixed incorrect variable `postID` to `email`
+}; */
+
+/**
+ * Enroll user in MFA
+ * @param {ObjectId} userId
+ * @param {string} mfaToken
+ * @returns {Promise<Stock>}
+ */
+export const mfaEnroll = async (
+  userId: ObjectId,
+  mfaToken: string,
+): Promise<Stock> => {
+  const params = { id: userId };
+  const body = {
+    mfa_token: mfaToken,
+  };
+
+  return mfaEnrollAccount(userId, body);
+};
+
+export const mfaDisable = async (userId: ObjectId): Promise<Stock> => {
+  await mfaDisableAccount(userId);
+  return { success: true };
+};
+
+/**
+ * Update user metadata by id
+ */
+export const updateMetaDataById = async (
+  id: ObjectId,
+  updateBody: Record<string, any>,
+): Promise<Stock> => {
+  // now use the generic update and pass app_metadata
+  return auth0.users.update({ id }, { app_metadata: updateBody });
+};
+
+/**
+ * Update user by id
+ */
+export const updateUserById = async (
+  id: ObjectId,
+  updateBody: Record<string, any>,
+): Promise<Stock> => {
+  // switch to the v3 ManagementClient users.update
+  return auth0.users.update({ id }, updateBody);
+};
+
+/**
+ * Delete user by id
+ */
+export const deleteById = async (userId: ObjectId): Promise<Stock> => {
+  return auth0.users.delete({ id: userId });
+};
+
+export default {
+  getAccountById,
+  // getAccountByEmail,
+  mfaEnroll,
+  mfaDisable,
+  updateMetaDataById,
+  updateUserById,
+  deleteById,
+};