@internetderdinge/api 1.229.39 → 1.229.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internetderdinge/api",
-  "version": "1.229.39",
+  "version": "1.229.41",
   "description": "Shared OpenIoT API modules",
   "main": "dist/src/index.js",
   "type": "module",
@@ -14,7 +14,7 @@
     "yalc:publish": "yalc publish --push",
     "deps:versions": "node --input-type=module -e \"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url); const out = (name) => { const pkgPath = require.resolve(name + '/package.json'); const version = require(pkgPath).version; console.log(name + '@' + version + ' -> ' + pkgPath); }; out('zod'); out('@asteasolutions/zod-to-openapi');\"",
     "deploy:version": "node ./scripts/release-version.mjs",
-    "release:paperless": "node ./scripts/release-and-sync-paperless.mjs",
+    "release": "node ./scripts/release-and-sync-paperless.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },

package/src/accounts/accounts.schemas.ts

@@ -1,15 +1,45 @@
-import { z } from 'zod';
+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
+  id: z
+    .string()
+    .openapi({
+      example: "auth0|60452f4c0dc85b0062326",
+      description: "Authentication provider account ID",
+    }),
+  email: z.string().email().openapi({ example: "jane.doe@example.com" }),
+  firstName: z.string().optional().openapi({ example: "Jane" }),
+  lastName: z.string().optional().openapi({ example: "Doe" }),
+  organizationId: z
+    .string()
+    .openapi({
+      example: "682fd0d7d4a6325d9d45b86e",
+      description: "Organization ObjectId",
+    }),
+  roles: z
+    .array(z.string())
+    .openapi({ example: ["admin", "user"], description: "Account roles" }),
+  isMfaEnabled: z.boolean().openapi({ example: true }),
+  createdAt: z
+    .string()
+    .datetime()
+    .openapi({ example: "2026-05-21T09:30:00.000Z" }),
+  updatedAt: z
+    .string()
+    .datetime()
+    .openapi({ example: "2026-05-21T10:15:00.000Z" }),
+}).openapi({
+  example: {
+    id: "auth0|60452f4c0dc85b0062326",
+    email: "jane.doe@example.com",
+    firstName: "Jane",
+    lastName: "Doe",
+    organizationId: "682fd0d7d4a6325d9d45b86e",
+    roles: ["admin", "user"],
+    isMfaEnabled: true,
+    createdAt: "2026-05-21T09:30:00.000Z",
+    updatedAt: "2026-05-21T10:15:00.000Z",
+  },
 });
 
 // If you ever need the TS type:

package/src/accounts/accounts.validation.ts

@@ -13,22 +13,36 @@ import {
 extendZodWithOpenApi(z);
 
 export const createAccountSchema = {
-  body: z.object({
-    name: z
-      .string()
-      .openapi({ example: "Sample Entry", description: "Name of the entry" })
-      .optional(),
-    medication: zObjectId.openapi({ description: "Medication ObjectId" }),
-    organization: zObjectId.openapi({ description: "Organization ObjectId" }),
-    patient: zObjectId.openapi({ description: "Patient ObjectId" }),
-    meta: z
-      .record(z.string(), z.any())
-      .openapi({
-        example: { key: "value" },
-        description: "Additional metadata for the entry",
-      })
-      .optional(),
-  }),
+  body: z
+    .object({
+      name: z
+        .string()
+        .openapi({ example: "Sample Entry", description: "Name of the entry" })
+        .optional(),
+      medication: zObjectId.openapi({ description: "Medication ObjectId" }),
+      organization: zObjectId.openapi({ description: "Organization ObjectId" }),
+      patient: zObjectId.openapi({ description: "Patient ObjectId" }),
+      meta: z
+        .record(z.string(), z.any())
+        .openapi({
+          example: { key: "value" },
+          description: "Additional metadata for the entry",
+        })
+        .optional(),
+    })
+    .openapi({
+      example: {
+        name: "Sample Entry",
+        medication: "682fd0d7d4a6325d9d45b871",
+        organization:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+        patient: process.env.SCHEMA_EXAMPLE_USER_ID || "682fd0d7d4a6325d9d45b86d",
+        meta: {
+          source: "manual",
+        },
+      },
+    }),
 };
 
 export const getUsersSchema = zPagination;
@@ -67,21 +81,38 @@ export const updateAccountSchema = {
         (value) => (value === "" ? undefined : value),
         z.string().email().optional(),
       )
-      .openapi({ description: "User email address" }),
+      .openapi({
+        example: "jane.doe@example.com",
+        description: "User email address",
+      }),
     given_name: z
       .string()
       .optional()
-      .openapi({ example: "John", description: "Given name" }),
+      .openapi({ example: "Jane", description: "Given name" }),
     family_name: z
       .string()
       .optional()
       .openapi({ example: "Doe", description: "Family name" }),
-    debug: z.boolean().optional(),
-    demo: z.boolean().optional(),
+    debug: z.boolean().optional().openapi({ example: false }),
+    demo: z.boolean().optional().openapi({ example: false }),
     notification: z
       .record(z.string(), z.any())
       .optional()
-      .openapi({ description: "Notification settings object" }),
+      .openapi({
+        example: { email: true, push: false },
+        description: "Notification settings object",
+      }),
+  }).openapi({
+    example: {
+      language: "en",
+      email: "jane.doe@example.com",
+      given_name: "Jane",
+      family_name: "Doe",
+      notification: {
+        email: true,
+        push: false,
+      },
+    },
   }),
 };
 
@@ -104,11 +135,18 @@ export const currentAccountMfaEnrollSchema = {
 };
 
 export const setDeviceTokenSchema = {
-  body: z.object({
-    token: z
-      .string()
-      .openapi({ example: "device-token", description: "Device token to set" }),
-  }),
+  body: z
+    .object({
+      token: z.string().openapi({
+        example: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
+        description: "Device token to set",
+      }),
+    })
+    .openapi({
+      example: {
+        token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
+      },
+    }),
 };
 
 export const getAvatarSchema = {};

package/src/admin/adminSearch.route.ts

@@ -31,6 +31,7 @@ export const adminSearchRouteSpecs: RouteSpec[] = [
     requestSchema: adminStatsSchema,
     responseSchema: adminStatsResponseSchema,
     handler: getStats,
+    privateDocs: true,
     summary: "Get admin stats",
     description: "Returns total counts for organizations, users, and devices.",
   },
@@ -42,6 +43,7 @@ export const adminSearchRouteSpecs: RouteSpec[] = [
     responseSchema: adminSearchResponseSchema,
     handler: searchAdmin,
     summary: "Search organizations, users, and devices",
+    privateDocs: true,
     description:
       "Performs an admin-only global search over organizations, users, and devices.",
   },
@@ -52,6 +54,7 @@ export const adminSearchRouteSpecs: RouteSpec[] = [
     requestSchema: adminIotDevicesSchema,
     responseSchema: adminIotDevicesResponseSchema,
     handler: getIotDevices,
+    privateDocs: true,
     summary: "List IoT devices",
     description:
       "Returns the IoT device status list used for admin device/order sync workflows.",
@@ -63,6 +66,7 @@ export const adminSearchRouteSpecs: RouteSpec[] = [
     requestSchema: adminDevicesSchema,
     responseSchema: adminDevicesResponseSchema,
     handler: getDevices,
+    privateDocs: true,
     summary: "List MongoDB devices",
     description:
       "Returns all device documents from MongoDB for admin sync workflows.",

package/src/devices/devices.route.ts

@@ -34,6 +34,7 @@ import {
   validateOrganizationDelete,
   validateOrganizationUpdate,
 } from "../middlewares/validateAction.js";
+import type { BuildRouterAndDocsOptions } from "../utils/buildRouterAndDocs.js";
 
 export const devicesRouteSpecs: RouteSpec[] = [
   {
@@ -166,7 +167,14 @@ export const devicesRouteSpecs: RouteSpec[] = [
   },
 ];
 
-const router: Router = Router();
-buildRouterAndDocs(router, devicesRouteSpecs, "/devices", ["Devices"]);
+export function createDevicesRoute(
+  options: BuildRouterAndDocsOptions = {},
+): Router {
+  const router: Router = Router();
+  buildRouterAndDocs(router, devicesRouteSpecs, "/devices", ["Devices"], options);
+  return router;
+}
+
+const router = createDevicesRoute();
 
 export default router;

package/src/devices/devices.schemas.ts

@@ -2,29 +2,64 @@ import { z } from "zod";
 import { zObjectId } from "../utils/zValidations.js";
 
 export const deviceResponseSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  serialNumber: z.string().optional(),
-  status: z.enum(["online", "offline", "error"]),
-  createdAt: z.string(), // ISO timestamp
-  updatedAt: z.string(), // ISO timestamp
-  // ...other device fields...
+  id: z.string().openapi({ example: "682fd0d7d4a6325d9d45b86f" }),
+  name: z.string().openapi({ example: "Kitchen Display" }),
+  serialNumber: z.string().optional().openapi({ example: "nrf-352656106701140" }),
+  status: z.enum(["online", "offline", "error"]).openapi({ example: "online" }),
+  createdAt: z
+    .string()
+    .datetime()
+    .openapi({ example: "2026-05-21T09:30:00.000Z" }),
+  updatedAt: z
+    .string()
+    .datetime()
+    .openapi({ example: "2026-05-21T10:15:00.000Z" }),
+}).openapi({
+  example: {
+    id: "682fd0d7d4a6325d9d45b86f",
+    name: "Kitchen Display",
+    serialNumber: "nrf-352656106701140",
+    status: "online",
+    createdAt: "2026-05-21T09:30:00.000Z",
+    updatedAt: "2026-05-21T10:15:00.000Z",
+  },
 });
 
 export const devicesResponseSchema = deviceResponseSchema.array();
 
 export const eventResponseSchema = z.object({
-  id: z.string(),
-  deviceId: z.string(),
-  type: z.string(),
-  payload: z.record(z.string(), z.any()),
-  timestamp: z.string(), // ISO timestamp
-  // ...other event fields...
+  id: z.string().openapi({ example: "evt_01HX0000000000000000000000" }),
+  deviceId: z.string().openapi({ example: "682fd0d7d4a6325d9d45b86f" }),
+  type: z.string().openapi({ example: "state" }),
+  payload: z
+    .record(z.string(), z.any())
+    .openapi({ example: { battery: 87, online: true } }),
+  timestamp: z
+    .string()
+    .datetime()
+    .openapi({ example: "2026-05-21T10:15:00.000Z" }),
+}).openapi({
+  example: {
+    id: "evt_01HX0000000000000000000000",
+    deviceId: "682fd0d7d4a6325d9d45b86f",
+    type: "state",
+    payload: {
+      battery: 87,
+      online: true,
+    },
+    timestamp: "2026-05-21T10:15:00.000Z",
+  },
 });
 
 export const genericResponseSchema = z
   .record(z.string(), z.any())
-  .openapi({ description: "Generic response payload" });
+  .openapi({
+    description: "Generic response payload",
+    example: {
+      success: true,
+      message: "Operation completed successfully",
+    },
+  });
 
 export const imageResponseSchema = z.object({
   uuid: z.string(),
@@ -93,4 +128,10 @@ export const resetResponseSchema = z.object({
     example: true,
     description: "Indicates if the reset operation was successful",
   }),
+}).openapi({
+  example: {
+    message:
+      "Reset all Variables and Memory and reboot Device: nrf-352656106701140",
+    success: true,
+  },
 });

package/src/devices/devices.validation.ts

@@ -26,7 +26,23 @@ export const createEntrySchema = {
       paper: zObjectId.optional().nullable(),
       date: z.string().datetime().optional(),
     })
-    .openapi({ description: "Create a new device entry" }),
+    .openapi({
+      description: "Create a new device entry",
+      example: {
+        name: "Kitchen Display",
+        deviceId: "nrf-352656106701140",
+        kind: "paper-display",
+        organization:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+        patient: process.env.SCHEMA_EXAMPLE_USER_ID || "682fd0d7d4a6325d9d45b86d",
+        paper: process.env.SCHEMA_EXAMPLE_PAPER_ID || null,
+        date: "2026-05-21T09:30:00.000Z",
+        meta: {
+          room: "kitchen",
+        },
+      },
+    }),
 };
 
 export const getUsersSchema = {
@@ -63,7 +79,19 @@ export const updateEntrySchema = {
     lut: z.string().optional(),
     sleepTime: z.string().optional(),
     clearScreen: z.boolean().optional(),
-  }).openapi({ description: "Fields to update on a device entry" }),
+  }).openapi({
+    description: "Fields to update on a device entry",
+    example: {
+      name: "Kitchen Display",
+      kind: "paper-display",
+      meta: {
+        room: "kitchen",
+      },
+      alarmEnable: 1,
+      takeOffsetTime: 15,
+      clearScreen: false,
+    },
+  }),
 };
 
 export const getEventsSchema = {
@@ -88,28 +116,45 @@ export const createCustomerPortalSessionSchema = {
   params: z.object({
     deviceId: zObjectId.openapi({ description: "Device ObjectId" }),
   }),
-  body: z.object({
-    domain: z.string().url().openapi({
-      description: "Domain for return URL",
-      example: "https://web.wirewire.de",
+  body: z
+    .object({
+      domain: z.string().url().openapi({
+        description: "Domain for return URL",
+        example: "https://web.wirewire.de",
+      }),
+    })
+    .openapi({
+      example: {
+        domain: "https://web.wirewire.de",
+      },
     }),
-  }),
 };
 export const createDeviceSchema = {
-  body: z.object({
-    kind: z.string().optional(),
-    patient: zObjectIdFor("patient")
-      .optional()
-      .nullable()
-      .openapi({ description: "Patient ObjectId", example: null }),
-    paper: zObjectIdFor("paper")
-      .optional()
-      .nullable()
-      .openapi({ description: "Paper ObjectId", example: null }),
-    organization: zObjectIdFor("organization").openapi({
-      description: "Organization ObjectId",
+  body: z
+    .object({
+      kind: z.string().optional().openapi({ example: "paper-display" }),
+      patient: zObjectIdFor("patient")
+        .optional()
+        .nullable()
+        .openapi({ description: "Patient ObjectId", example: null }),
+      paper: zObjectIdFor("paper")
+        .optional()
+        .nullable()
+        .openapi({ description: "Paper ObjectId", example: null }),
+      organization: zObjectIdFor("organization").openapi({
+        description: "Organization ObjectId",
+      }),
+    })
+    .openapi({
+      example: {
+        kind: "paper-display",
+        patient: process.env.SCHEMA_EXAMPLE_USER_ID || "682fd0d7d4a6325d9d45b86d",
+        paper: process.env.SCHEMA_EXAMPLE_PAPER_ID || null,
+        organization:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+      },
     }),
-  }),
 };
 export const deleteDeviceSchema = zDelete("deviceId");
 export const getDeviceSchema = zGet("deviceId");
@@ -195,16 +240,40 @@ export const uploadSingleImageFromWebsiteSchema = {};
 export const updateDeviceSchema = {
   ...zUpdate("deviceId"),
   body: zPatchBody({
-    intake: z.record(z.string(), z.any()).optional(),
-    meta: z.record(z.string(), z.any()).optional(),
+    intake: z
+      .record(z.string(), z.any())
+      .optional()
+      .openapi({ example: { morning: "08:00", evening: "20:00" } }),
+    meta: z
+      .record(z.string(), z.any())
+      .optional()
+      .openapi({ example: { room: "kitchen" } }),
     organization: zObjectId.optional(),
     patient: zObjectId.optional().nullable(),
     paper: zObjectId.optional().nullable(),
-    kind: z.string().optional(),
-    deviceId: z.string().optional(),
-    alarmEnable: z.number().int().optional(),
-    takeOffsetTime: z.number().int().optional(),
-    iotDevice: z.record(z.string(), z.any()).optional(),
-    payment: z.record(z.string(), z.any()).optional(),
+    kind: z.string().optional().openapi({ example: "paper-display" }),
+    deviceId: z.string().optional().openapi({ example: "nrf-352656106701140" }),
+    alarmEnable: z.number().int().optional().openapi({ example: 1 }),
+    takeOffsetTime: z.number().int().optional().openapi({ example: 15 }),
+    iotDevice: z
+      .record(z.string(), z.any())
+      .optional()
+      .openapi({ example: { firmwareVersion: "1.2.3" } }),
+    payment: z
+      .record(z.string(), z.any())
+      .optional()
+      .openapi({ example: { status: "active" } }),
+  }).openapi({
+    example: {
+      kind: "paper-display",
+      deviceId: "nrf-352656106701140",
+      patient: process.env.SCHEMA_EXAMPLE_USER_ID || "682fd0d7d4a6325d9d45b86d",
+      paper: process.env.SCHEMA_EXAMPLE_PAPER_ID || null,
+      meta: {
+        room: "kitchen",
+      },
+      alarmEnable: 1,
+      takeOffsetTime: 15,
+    },
   }),
 };

package/src/index.ts

@@ -26,6 +26,10 @@ export * from "../src/organizations/organizations.controller";
 export { default as organizationsService } from "../src/organizations/organizations.service";
 export { default as Organization } from "../src/organizations/organizations.model";
 export { default as devicesRoute } from "../src/devices/devices.route";
+export {
+  createDevicesRoute,
+  devicesRouteSpecs,
+} from "../src/devices/devices.route";
 export { default as devicesService } from "../src/devices/devices.service";
 export { default as Device } from "../src/devices/devices.model";
 export * from "../src/devices/devices.validation";