@internetderdinge/api 1.229.40 → 1.229.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internetderdinge/api",
-  "version": "1.229.40",
+  "version": "1.229.42",
   "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/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";

package/src/iotdevice/iotdevice.schemas.ts

@@ -5,67 +5,151 @@ extendZodWithOpenApi(z);
 
 // Represents a device in the system
 export const iotDeviceResponseSchema = z.object({
-  deviceId: z.string(),
-  name: z.string(),
-  model: z.string().optional(),
-  firmwareVersion: z.string().optional(),
-  registeredAt: z.string(), // ISO timestamp
-  lastSeenAt: z.string().optional(), // ISO timestamp
+  deviceId: z.string().openapi({ example: 'nrf-352656106701140' }),
+  name: z.string().openapi({ example: 'Kitchen Display' }),
+  model: z.string().optional().openapi({ example: 'OpenPaper 7' }),
+  firmwareVersion: z.string().optional().openapi({ example: '1.2.3' }),
+  registeredAt: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T09:30:00.000Z' }),
+  lastSeenAt: z
+    .string()
+    .datetime()
+    .optional()
+    .openapi({ example: '2026-05-21T10:15:00.000Z' }),
+}).openapi({
+  example: {
+    deviceId: 'nrf-352656106701140',
+    name: 'Kitchen Display',
+    model: 'OpenPaper 7',
+    firmwareVersion: '1.2.3',
+    registeredAt: '2026-05-21T09:30:00.000Z',
+    lastSeenAt: '2026-05-21T10:15:00.000Z',
+  },
 });
 
 // An event generated by a device
 export const eventResponseSchema = z.object({
-  eventId: z.string(),
-  deviceId: z.string(),
-  timestamp: z.string(), // ISO timestamp
-  type: z.string(),
-  payload: z.any(),
+  eventId: z.string().openapi({ example: 'evt_01HX0000000000000000000000' }),
+  deviceId: z.string().openapi({ example: 'nrf-352656106701140' }),
+  timestamp: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T10:15:00.000Z' }),
+  type: z.string().openapi({ example: 'state' }),
+  payload: z.any().openapi({ example: { battery: 87, online: true } }),
+}).openapi({
+  example: {
+    eventId: 'evt_01HX0000000000000000000000',
+    deviceId: 'nrf-352656106701140',
+    timestamp: '2026-05-21T10:15:00.000Z',
+    type: 'state',
+    payload: {
+      battery: 87,
+      online: true,
+    },
+  },
 });
 
 // A single device fetched by criteria
 export const deviceResponseSchema = z.object({
-  deviceId: z.string(),
-  serialNumber: z.string(),
-  type: z.string(),
-  owner: z.string(),
-  registeredAt: z.string(),
+  deviceId: z.string().openapi({ example: 'nrf-352656106701140' }),
+  serialNumber: z.string().openapi({ example: 'nrf-352656106701140' }),
+  type: z.string().openapi({ example: 'paper-display' }),
+  owner: z.string().openapi({ example: '682fd0d7d4a6325d9d45b86e' }),
+  registeredAt: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T09:30:00.000Z' }),
+}).openapi({
+  example: {
+    deviceId: 'nrf-352656106701140',
+    serialNumber: 'nrf-352656106701140',
+    type: 'paper-display',
+    owner: '682fd0d7d4a6325d9d45b86e',
+    registeredAt: '2026-05-21T09:30:00.000Z',
+  },
 });
 
 // Shadow alarm settings
 export const shadowAlarmSchema = z.object({
-  enabled: z.boolean(),
-  threshold: z.number(),
-  mode: z.enum(['auto', 'manual']).optional(),
+  enabled: z.boolean().openapi({ example: true }),
+  threshold: z.number().openapi({ example: 80 }),
+  mode: z.enum(['auto', 'manual']).optional().openapi({ example: 'auto' }),
+}).openapi({
+  example: {
+    enabled: true,
+    threshold: 80,
+    mode: 'auto',
+  },
 });
 
 // Ping / LED light response
 export const pingResponseSchema = z.object({
-  success: z.boolean(),
-  message: z.string().optional(),
-  timestamp: z.string(),
+  success: z.boolean().openapi({ example: true }),
+  message: z.string().optional().openapi({ example: 'Device responded' }),
+  timestamp: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T10:15:00.000Z' }),
+}).openapi({
+  example: {
+    success: true,
+    message: 'Device responded',
+    timestamp: '2026-05-21T10:15:00.000Z',
+  },
 });
 
 // Current status of a device
 export const deviceStatusSchema = z.object({
-  deviceId: z.string(),
-  online: z.boolean(),
-  batteryLevel: z.number().min(0).max(100).optional(),
-  lastSeenAt: z.string(),
+  deviceId: z.string().openapi({ example: 'nrf-352656106701140' }),
+  online: z.boolean().openapi({ example: true }),
+  batteryLevel: z.number().min(0).max(100).optional().openapi({ example: 87 }),
+  lastSeenAt: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T10:15:00.000Z' }),
+}).openapi({
+  example: {
+    deviceId: 'nrf-352656106701140',
+    online: true,
+    batteryLevel: 87,
+    lastSeenAt: '2026-05-21T10:15:00.000Z',
+  },
 });
 
 // API status by kind
 export const apiStatusSchema = z.object({
-  kind: z.string(),
-  status: z.enum(['ok', 'degraded', 'down']),
-  uptimeSeconds: z.number(),
+  kind: z.string().openapi({ example: 'iot' }),
+  status: z.enum(['ok', 'degraded', 'down']).openapi({ example: 'ok' }),
+  uptimeSeconds: z.number().openapi({ example: 86400 }),
+}).openapi({
+  example: {
+    kind: 'iot',
+    status: 'ok',
+    uptimeSeconds: 86400,
+  },
 });
 
 // Single entry for a device
 export const entryResponseSchema = z.object({
-  entryId: z.string(),
-  deviceId: z.string(),
-  timestamp: z.string(),
-  data: z.any(),
+  entryId: z.string().openapi({ example: 'entry_01HX0000000000000000000000' }),
+  deviceId: z.string().openapi({ example: 'nrf-352656106701140' }),
+  timestamp: z
+    .string()
+    .datetime()
+    .openapi({ example: '2026-05-21T10:15:00.000Z' }),
+  data: z.any().openapi({ example: { state: 'active' } }),
+}).openapi({
+  example: {
+    entryId: 'entry_01HX0000000000000000000000',
+    deviceId: 'nrf-352656106701140',
+    timestamp: '2026-05-21T10:15:00.000Z',
+    data: {
+      state: 'active',
+    },
+  },
 });
 
 // Optionally infer TS types