@internetderdinge/api 1.229.39 → 1.229.41

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

package/src/iotdevice/iotdevice.validation.ts

@@ -9,9 +9,17 @@ export const getDevice = {
   params: z.object({
     deviceId: zObjectId.openapi({ description: 'Device ObjectId' }),
   }),
-  body: z.object({
-    deviceId: z.array(zObjectId).openapi({ description: 'Array of device IDs' }),
-  }),
+  body: z
+    .object({
+      deviceId: z
+        .array(zObjectId)
+        .openapi({ description: 'Array of device IDs' }),
+    })
+    .openapi({
+      example: {
+        deviceId: ['682fd0d7d4a6325d9d45b86f'],
+      },
+    }),
 };
 export const iotDevicesSchema = {
   ...zPagination,
@@ -30,19 +38,33 @@ export const getEventsSchema = {
   params: z.object({
     deviceId: zObjectId.openapi({ description: 'Device ObjectId' }),
   }),
-  query: z.object({
-    DateStart: z
-      .string()
-      .datetime()
-      .openapi({ description: 'Start date (ISO‐string)', example: '2025-05-01T00:00:00Z' })
-      .optional(),
-    DateEnd: z
-      .string()
-      .datetime()
-      .openapi({ description: 'End date (ISO‐string)', example: '2025-05-31T23:59:59Z' })
-      .optional(),
-    TypeFilter: zTypeFilter.default(''),
-  }),
+  query: z
+    .object({
+      DateStart: z
+        .string()
+        .datetime()
+        .openapi({
+          description: 'Start date (ISO‐string)',
+          example: '2026-05-01T00:00:00Z',
+        })
+        .optional(),
+      DateEnd: z
+        .string()
+        .datetime()
+        .openapi({
+          description: 'End date (ISO‐string)',
+          example: '2026-05-21T23:59:59Z',
+        })
+        .optional(),
+      TypeFilter: zTypeFilter.default(''),
+    })
+    .openapi({
+      example: {
+        DateStart: '2026-05-01T00:00:00Z',
+        DateEnd: '2026-05-21T23:59:59Z',
+        TypeFilter: 'state',
+      },
+    }),
 };
 export const updateEntrySchema = {};
 

package/src/organizations/organizations.schemas.ts

@@ -1,8 +1,31 @@
-import { z } from 'zod';
+import { z } from "zod";
 
 export const organizationResponseSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  kind: z.string().optional(),
+  id: z
+    .string()
+    .openapi({ example: "682fd0d7d4a6325d9d45b86e" }),
+  name: z
+    .string()
+    .openapi({ example: "Acme Inc.", description: "Organization name" }),
+  email: z
+    .string()
+    .email()
+    .openapi({
+      example: "contact@acme.example",
+      description: "Primary contact email",
+    }),
+  kind: z
+    .string()
+    .optional()
+    .openapi({
+      example: "private",
+      description: "The type or category of the organization",
+    }),
+}).openapi({
+  example: {
+    id: "682fd0d7d4a6325d9d45b86e",
+    name: "Acme Inc.",
+    email: "contact@acme.example",
+    kind: "private",
+  },
 });

package/src/organizations/organizations.validation.ts

@@ -13,20 +13,18 @@ import {
 extendZodWithOpenApi(z);
 
 export const createOrganizationSchema = {
-  body: z.object({
-    /*  name: z.string().openapi({
-      example: 'Acme Inc.',
-      description: 'The name of the organization',
-    }),
-    email: z.string().email().openapi({
-      example: 'contact@acme.com',
-      description: 'Contact email for the organization',
-    }), */
-    kind: z.string().openapi({
-      example: "private",
-      description: "The type or category of the organization",
+  body: z
+    .object({
+      kind: z.string().openapi({
+        example: "private",
+        description: "The type or category of the organization",
+      }),
+    })
+    .openapi({
+      example: {
+        kind: "private",
+      },
     }),
-  }),
 };
 
 export const queryOrganizationsSchema = zPagination;
@@ -35,30 +33,44 @@ export const getOrganizationByIdSchema = zGet("organizationId");
 
 export const updateOrganizationSchema = {
   ...zUpdate("organizationId"),
-  body: z.object({
-    name: z
-      .string()
-      .openapi({
-        example: "Acme Inc.",
-        description: "The name of the organization",
-      })
-      .optional(),
-    organization: zObjectId, // Legacy field, to be removed later
-    kind: z
-      .string()
-      .openapi({
-        example: "private",
-        description: "The type or category of the organization",
-      })
-      .optional(),
-    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: "Acme Inc.",
+          description: "The name of the organization",
+        })
+        .optional(),
+      organization: zObjectId, // Legacy field, to be removed later
+      kind: z
+        .string()
+        .openapi({
+          example: "private",
+          description: "The type or category of the organization",
+        })
+        .optional(),
+      meta: z
+        .record(z.string(), z.any())
+        .openapi({
+          example: { billingId: "cus_123", region: "eu" },
+          description: "Additional metadata for the entry",
+        })
+        .optional(),
+    })
+    .openapi({
+      example: {
+        name: "Acme Inc.",
+        organization:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86d",
+        kind: "private",
+        meta: {
+          billingId: "cus_123",
+          region: "eu",
+        },
+      },
+    }),
   //...zUpdate('organizationId'),
   /* body: z.object({
     meta: z.any,

package/src/tokens/tokens.schemas.ts

@@ -1,15 +1,38 @@
-import { z } from 'zod';
+import { z } from "zod";
 
 export const tokenResponseSchema = z.object({
-  // unique identifier of the token
-  tokenId: z.string().uuid(),
-  // the owning user
-  userId: z.string().uuid(),
-  // optional name or description
-  name: z.string().optional(),
-  // the token value (never returned after creation in real-world apps)
-  token: z.string(),
-  // timestamps
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
+  tokenId: z
+    .string()
+    .openapi({
+      example: "682fd0d7d4a6325d9d45b872",
+      description: "Token ObjectId",
+    }),
+  userId: z
+    .string()
+    .openapi({
+      example: "682fd0d7d4a6325d9d45b86d",
+      description: "Owning user ObjectId",
+    }),
+  name: z.string().optional().openapi({ example: "Admin integration token" }),
+  token: z.string().openapi({
+    example: "idt_live_1234567890abcdef",
+    description: "Token secret. Usually only returned immediately after creation.",
+  }),
+  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: {
+    tokenId: "682fd0d7d4a6325d9d45b872",
+    userId: "682fd0d7d4a6325d9d45b86d",
+    name: "Admin integration token",
+    token: "idt_live_1234567890abcdef",
+    createdAt: "2026-05-21T09:30:00.000Z",
+    updatedAt: "2026-05-21T10:15:00.000Z",
+  },
 });

package/src/tokens/tokens.validation.ts

@@ -3,9 +3,15 @@ import { z } from "zod";
 import { zGet, zDelete } from "../utils/zValidations.js";
 
 export const createTokenSchema = {
-  body: z.object({
-    name: z.string().openapi({ example: "my sample token" }),
-  }),
+  body: z
+    .object({
+      name: z.string().openapi({ example: "Admin integration token" }),
+    })
+    .openapi({
+      example: {
+        name: "Admin integration token",
+      },
+    }),
 };
 
 export const getTokenSchema = zGet("tokenId");

package/src/users/users.schemas.ts

@@ -3,18 +3,37 @@ import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
 extendZodWithOpenApi(z);
 
 export const createUserResponseSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
+  id: z.string().openapi({ example: "682fd0d7d4a6325d9d45b86d" }),
+  name: z.string().openapi({ example: "Jane Doe" }),
+  email: z.string().email().openapi({ example: "jane.doe@example.com" }),
+}).openapi({
+  example: {
+    id: "682fd0d7d4a6325d9d45b86d",
+    name: "Jane Doe",
+    email: "jane.doe@example.com",
+  },
 });
 
 export const getUsersResponseSchema = z.array(
   z.object({
-    id: z.string(),
-    name: z.string(),
-    email: z.string(),
+    id: z.string().openapi({ example: "682fd0d7d4a6325d9d45b86d" }),
+    name: z.string().openapi({ example: "Jane Doe" }),
+    email: z.string().email().openapi({ example: "jane.doe@example.com" }),
   }),
-);
+).openapi({
+  example: [
+    {
+      id: "682fd0d7d4a6325d9d45b86d",
+      name: "Jane Doe",
+      email: "jane.doe@example.com",
+    },
+    {
+      id: "682fd0d7d4a6325d9d45b86f",
+      name: "John Smith",
+      email: "john.smith@example.com",
+    },
+  ],
+});
 
 export const updateUserSchema = z.object({
   name: z.string().optional(),
@@ -22,11 +41,21 @@ export const updateUserSchema = z.object({
 });
 
 export const updateUserResponseSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
+  id: z.string().openapi({ example: "682fd0d7d4a6325d9d45b86d" }),
+  name: z.string().openapi({ example: "Jane Doe" }),
+  email: z.string().email().openapi({ example: "jane.doe@example.com" }),
+}).openapi({
+  example: {
+    id: "682fd0d7d4a6325d9d45b86d",
+    name: "Jane Doe",
+    email: "jane.doe@example.com",
+  },
 });
 
 export const deleteUserResponseSchema = z.object({
-  success: z.boolean(),
+  success: z.boolean().openapi({ example: true }),
+}).openapi({
+  example: {
+    success: true,
+  },
 });

package/src/users/users.validation.ts

@@ -36,6 +36,10 @@ export const createUserBodyShape = {
     example: "user@example.com",
     description: "User email address",
   }),
+  category: z.string().optional().openapi({
+    example: "random",
+    description: "LEGACY: User category",
+  }),
   timezone: z.string().optional().openapi({
     example: "Europe/Berlin",
     description: "IANA timezone string",
@@ -46,7 +50,19 @@ export const createUserBodyShape = {
 };
 
 export const createUserSchema = {
-  body: z.object(createUserBodyShape),
+  body: z.object(createUserBodyShape).openapi({
+    example: {
+      organization:
+        process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+        "682fd0d7d4a6325d9d45b86e",
+      email: "user@example.com",
+      timezone: "Europe/Berlin",
+      role: "user",
+      meta: {
+        externalId: "crm-123",
+      },
+    },
+  }),
 };
 
 export const createCurrentUserSchema = createUserSchema;
@@ -67,7 +83,10 @@ export const getUserSchema = zGet("userId");
 
 export const getCurrentUserSchema = {
   query: z.object({
-    organization: zObjectId,
+    organization: zObjectId.openapi({
+      description: "Organization ObjectId",
+      param: { name: "organization", in: "query" },
+    }),
   }),
 };
 
@@ -75,6 +94,10 @@ export const updateUserBodyShape = {
   name: z.string().optional().openapi({ description: "User full name" }),
   timezone: z.string().optional().openapi({ description: "IANA timezone" }),
   avatar: z.string().optional().openapi({ description: "Avatar URL" }),
+  category: z.string().optional().openapi({
+    example: "random",
+    description: "LEGACY: User category",
+  }),
   meta: z
     .object({})
     .passthrough()
@@ -103,36 +126,80 @@ export const updateUserBodyShape = {
 
 export const updateUserSchema = {
   ...zUpdate("userId"),
-  body: zPatchBody(updateUserBodyShape),
+  body: zPatchBody(updateUserBodyShape).openapi({
+    example: {
+      name: "Jane Doe",
+      timezone: "Europe/Berlin",
+      email: "jane.doe@example.com",
+      role: "patient",
+      meta: {
+        carePlan: "standard",
+      },
+    },
+  }),
 };
 
 export const deleteUserSchema = zDelete("userId");
 
 export const organizationInviteSchema = {
-  body: z.object({
-    organizationId: zObjectId.openapi({ description: "Organization ObjectId" }),
-    action: z.string().optional().openapi({ description: "Invite action" }),
-    role: z.string().optional().openapi({ description: "Role on invite" }),
-  }),
+  body: z
+    .object({
+      organizationId: zObjectId.openapi({
+        description: "Organization ObjectId",
+      }),
+      action: z.string().optional().openapi({ description: "Invite action" }),
+      role: z.string().optional().openapi({ description: "Role on invite" }),
+    })
+    .openapi({
+      example: {
+        organizationId:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+        action: "accept",
+        role: "user",
+      },
+    }),
 };
 
 export const updateInviteSchema = {
-  body: z.object({
-    organization: zObjectId.openapi({ description: "Organization ObjectId" }),
-    status: z.enum(["accepted"]).openapi({ description: "Invite status" }),
-    inviteCode: z
-      .string()
-      .nullable()
-      .optional()
-      .openapi({ description: "Invite code" }),
-  }),
+  body: z
+    .object({
+      organization: zObjectId.openapi({ description: "Organization ObjectId" }),
+      status: z.enum(["accepted"]).openapi({ description: "Invite status" }),
+      inviteCode: z
+        .string()
+        .nullable()
+        .optional()
+        .openapi({ description: "Invite code" }),
+    })
+    .openapi({
+      example: {
+        organization:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+        status: "accepted",
+        inviteCode: "INVITE-123",
+      },
+    }),
 };
 
 export const organizationRemoveSchema = {
-  body: z.object({
-    userId: zObjectId.openapi({ description: "User ObjectId" }),
-    organizationId: zObjectId.openapi({ description: "Organization ObjectId" }),
-  }),
+  body: z
+    .object({
+      userId: zObjectId.openapi({ description: "User ObjectId" }),
+      organizationId: zObjectId.openapi({
+        description: "Organization ObjectId",
+      }),
+    })
+    .openapi({
+      example: {
+        userId:
+          process.env.SCHEMA_EXAMPLE_USER_ID || "682fd0d7d4a6325d9d45b86d",
+        organizationId:
+          process.env.SCHEMA_EXAMPLE_ORGANIZATION_ID ||
+          "682fd0d7d4a6325d9d45b86e",
+      },
+    }),
 };
 
 export const updateTimesByIdSchema = {