@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/src/modules/devices/AGENTS.md

@@ -0,0 +1,101 @@
+# Devices Module — Agent Guidelines
+
+Generic device registry keyed on `(tenant, org, user, device)` plus app/OS metadata and
+push-token storage. Channel-agnostic — it owns device identity and the token *field*, but **no push
+delivery logic** (sender, providers, delivery rows, workers live in the `push_notifications` module).
+
+> **Spec note (resolves a wording inconsistency):** Spec §"Module 1" line 78 says "push-token storage
+> does not live here," but the authoritative sections override that — the `UserDevice` entity lists
+> `push_token`/`push_provider`/`push_token_updated_at` (Data Models: *"UserDevice carries push-token
+> fields directly"*), and `push_notifications` ships **no** token API, relying on `PUT /api/devices/:id`
+> to set/clear tokens. "Channel-agnostic" means no delivery machinery, not "no token column."
+
+## Always
+
+- Scope every query by `tenant_id`. `organization_id` is **nullable**, but scoping follows the standard
+  org-scoped pattern like every other module: the list routes keep `orm.orgField: 'organizationId'` and
+  let the factory auto-filter by the caller's org scope. The query engine's org scope is null-aware —
+  callers with no org restriction (or whose scope includes null) also see null-org rows; a caller pinned
+  to a specific org does not.
+- Route all writes through the device commands (`commands/register.ts`, `commands/update.ts`,
+  `commands/deactivate.ts` → `devices.user_devices.register`, `devices.user_devices.update`,
+  `devices.user_devices.deactivate`; shared helpers in `commands/shared.ts`, registered via `commands/index.ts`)
+  — they carry undo snapshots, query-index side effects, and domain events.
+- Treat `push_token` as a secret: **never** include it in list/response field sets. Only
+  `push_provider` and `push_token_updated_at` are exposed.
+- Honor the `pushToken` tri-state on `PUT`: absent key = leave unchanged; explicit `null` = clear
+  (revoked OS permission) and bump `push_token_updated_at`. The command uses own-property presence.
+- Keep the list route's CRUD cache tag aligned with the command's `resourceKind`. The list reads
+  through `makeCrudRoute` (org-nullable, custom POST/PUT/DELETE + command bus), so it passes
+  `events: { module: 'devices', entity: 'user_device' }` purely to set the cache resource tag to
+  `devices.user_device` — matching the `resourceKind` the commands invalidate. Without it the factory
+  falls back to the ORM entity name and writes never bust the list cache (stale list under
+  `ENABLE_CRUD_API_CACHE`). No events are emitted on GET.
+
+## Never
+
+- Never add push delivery, provider adapters, FCM/APNs SDKs, or send workers here — those belong to the `push_notifications` module.
+- Never expose another user's devices unless the caller has `devices.admin` (wildcard-aware RBAC check).
+- Never route `PUT`/`DELETE :id` through `makeCrudRoute` — the factory resolves the id from the body/
+  query, not the path param. The `[id]` route is a thin guard + command-bus wrapper by design.
+
+## Self-serve vs admin split
+
+Endpoints are split the same way other modules split them (e.g. `customer_accounts/api/admin`,
+`staff/api/.../self`): the base path is **self-serve** (always scoped to the acting user) and a
+separate `api/admin/devices` tree holds the **cross-user** operations gated by `devices.admin`.
+
+- **Self-serve** (`devices.view` / `devices.manage`):
+  - `POST /api/devices` — register/upsert the **caller's own** device. Idempotent on `(tenant, org,
+    user, device_id)`; a soft-deleted row is **revived** (`deleted_at = null`); response `{ id, deviceId,
+    revived }`. Uniqueness of active rows enforced by the partial unique index
+    `user_devices_tenant_org_user_device_active_unique ... nulls not distinct where deleted_at is null`
+    (declared `NULLS NOT DISTINCT` so null-org rows still dedupe per tenant/user/device).
+  - `GET /api/devices` — the caller's own devices, scoped to the active organization. It does **not**
+    honor `?userId`.
+  - `PUT` / `DELETE /api/devices/:id` — **owner only** (403 otherwise) and scoped to the active org
+    (a device outside the current org reads as 404), mirroring the list + the user-owned-resource
+    convention. Update advances `last_seen_at` only when the client explicitly sends `lastSeenAt`
+    (metadata-only edits do not touch presence).
+- **Admin** (`devices.admin`) under `api/admin/devices`:
+  - `GET /api/devices/admin/devices` — tenant-wide list; optional `?userId=` / `?platform=`.
+  - `POST /api/devices/admin/devices` — register on behalf of any user (`userId` in body,
+    `registerDeviceAdminSchema`). `actorUserId` (the admin) is recorded for the mutation guard/audit.
+  - `GET` / `PUT` / `DELETE /api/devices/admin/devices/:id` — read/update/deactivate any device.
+
+Shared write boilerplate (guard → command bus → undo header) lives in `api/deviceOps.ts`
+(`executeRegister`/`executeUpdate`/`executeDeactivate`); the list schema/fields/openapi item live in
+`api/deviceList.ts`. Both list routes pass `events: { module:'devices', entity:'user_device' }` so any
+write busts both caches (see cache-tag note above).
+
+- Never route `PUT`/`DELETE :id` through `makeCrudRoute` — the factory resolves the id from the body/
+  query, not the path param. The `[id]` routes are thin guard + command-bus wrappers by design.
+
+## Backend pages (`/backend/devices`, gated by `devices.admin`, settings → Auth)
+
+- `backend/devices/page.tsx` — cross-user list via `GET /api/devices/admin/devices`, with a Register
+  button and per-row Edit (`/backend/devices/:id`) + Deactivate (`DELETE …/admin/devices/:id`).
+- `backend/devices/create/page.tsx` — `CrudForm` → `POST /api/devices/admin/devices` (admin registers
+  for a user; `userId` is a required field).
+- `backend/devices/[id]/page.tsx` — `CrudForm` edit (app/OS version, push provider) via
+  `PUT /api/devices/admin/devices/:id`, loaded from the admin `GET :id`. Never renders `push_token`.
+
+## Events
+
+- `devices.user_device.registered` — emitted on register/revive.
+- `devices.user_device.deactivated` — emitted on soft-delete.
+- `devices.user_device.created|updated|deleted` — CRUD lifecycle events from `emitCrudSideEffects`.
+
+## ACL
+
+`devices.view`, `devices.manage` (self-serve), `devices.admin` (cross-user). Defaults in `setup.ts`:
+`superadmin`/`admin` get `devices.*`; `employee` gets `view` + `manage`. Run
+`yarn mercato auth sync-role-acls` after changing `acl.ts`/`setup.ts` to backfill existing tenants.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn db:generate          # schema-diff probe — partial unique index is hand-authored in the migration
+yarn workspace @open-mercato/core build
+```

package/src/modules/devices/acl.ts

@@ -0,0 +1,7 @@
+export const features = [
+  { id: 'devices.view', title: 'View own devices', module: 'devices' },
+  { id: 'devices.manage', title: 'Manage own devices', module: 'devices' },
+  { id: 'devices.admin', title: 'Manage devices across users', module: 'devices' },
+]
+
+export default features

package/src/modules/devices/api/[id]/route.ts

@@ -0,0 +1,180 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { UserDevice } from '../../data/entities'
+import { updateDeviceSchema } from '../../data/validators'
+import { resolveDeviceActorUserId } from '../auth'
+import { executeUpdate, executeDeactivate, type DeviceMutationContext } from '../deviceOps'
+
+const logger = createLogger('devices')
+
+// Self-serve: the caller may only mutate their OWN device. Cross-user device administration lives in
+// api/admin/devices/[id] (gated by devices.admin).
+export const metadata = {
+  PUT: { requireAuth: true, requireFeatures: ['devices.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['devices.manage'] },
+}
+
+const paramsSchema = z.object({ id: z.string().uuid() })
+
+export async function PUT(req: Request, { params }: { params: { id: string } }) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+    const parsedParams = paramsSchema.safeParse({ id: params.id })
+    if (!parsedParams.success) {
+      return NextResponse.json({ error: translate('devices.errors.invalid_id', 'Invalid device id') }, { status: 400 })
+    }
+
+    const body = updateDeviceSchema.parse(await readJsonSafe(req, {}))
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    // Self devices are scoped to the caller's active organization, mirroring the list route and the
+    // user-owned-resource convention (e.g. progress jobs): a device outside the current org context
+    // reads as not-found. When there is no active org, scope by tenant only.
+    const currentOrganizationId = scope?.selectedId ?? auth.orgId ?? null
+    const em = container.resolve('em') as EntityManager
+    const device = await findOneWithDecryption(
+      em,
+      UserDevice,
+      {
+        id: parsedParams.data.id,
+        tenantId: auth.tenantId,
+        ...(currentOrganizationId ? { organizationId: currentOrganizationId } : {}),
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId: auth.tenantId, organizationId: currentOrganizationId },
+    )
+    if (!device) {
+      return NextResponse.json({ error: translate('devices.errors.not_found', 'Device not found') }, { status: 404 })
+    }
+    if (device.userId !== actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+
+    const mctx: DeviceMutationContext = {
+      container,
+      auth,
+      scope,
+      organizationId: device.organizationId ?? null,
+      actorUserId,
+      request: req,
+    }
+    return await executeUpdate(mctx, device, body)
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('devices.errors.invalid_payload', 'Invalid device payload'), details: err.flatten() },
+        { status: 400 },
+      )
+    }
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.PUT failed', { err })
+    return NextResponse.json({ error: translate('devices.errors.update_failed', 'Failed to update device') }, { status: 500 })
+  }
+}
+
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+    const parsedParams = paramsSchema.safeParse({ id: params.id })
+    if (!parsedParams.success) {
+      return NextResponse.json({ error: translate('devices.errors.invalid_id', 'Invalid device id') }, { status: 400 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    // Same active-org scoping as PUT/the list route: a device outside the current org reads as not-found.
+    const currentOrganizationId = scope?.selectedId ?? auth.orgId ?? null
+    const em = container.resolve('em') as EntityManager
+    const device = await findOneWithDecryption(
+      em,
+      UserDevice,
+      {
+        id: parsedParams.data.id,
+        tenantId: auth.tenantId,
+        ...(currentOrganizationId ? { organizationId: currentOrganizationId } : {}),
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId: auth.tenantId, organizationId: currentOrganizationId },
+    )
+    if (!device) {
+      return NextResponse.json({ error: translate('devices.errors.not_found', 'Device not found') }, { status: 404 })
+    }
+    if (device.userId !== actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+
+    const mctx: DeviceMutationContext = {
+      container,
+      auth,
+      scope,
+      organizationId: device.organizationId ?? null,
+      actorUserId,
+      request: req,
+    }
+    return await executeDeactivate(mctx, device)
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.DELETE failed', { err })
+    return NextResponse.json({ error: translate('devices.errors.delete_failed', 'Failed to delete device') }, { status: 500 })
+  }
+}
+
+const okResponseSchema = z.object({ ok: z.literal(true), id: z.string().uuid().optional() })
+const errorResponseSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Devices',
+  summary: 'Update or deactivate one of your registered devices',
+  methods: {
+    PUT: {
+      summary: 'Update your device',
+      description:
+        'Updates last-seen, app/OS metadata, and push token for a device owned by the current user. Set pushToken to null to clear a revoked OS permission.',
+      requestBody: { schema: updateDeviceSchema },
+      responses: [{ status: 200, description: 'Device updated', schema: okResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid payload or id', schema: errorResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
+        { status: 403, description: 'Not the device owner', schema: errorResponseSchema },
+        { status: 404, description: 'Device not found', schema: errorResponseSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Deactivate your device',
+      description: 'Soft-deletes a device owned by the current user.',
+      responses: [{ status: 200, description: 'Device deactivated', schema: okResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid id', schema: errorResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
+        { status: 403, description: 'Not the device owner', schema: errorResponseSchema },
+        { status: 404, description: 'Device not found', schema: errorResponseSchema },
+      ],
+    },
+  },
+}

package/src/modules/devices/api/admin/devices/[id]/route.ts

@@ -0,0 +1,235 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { UserDevice } from '../../../../data/entities'
+import { updateDeviceSchema } from '../../../../data/validators'
+import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
+import { resolveDeviceActorUserId } from '../../../auth'
+import { executeUpdate, executeDeactivate, type DeviceMutationContext } from '../../../deviceOps'
+
+const logger = createLogger('devices')
+
+// Admin: read/update/deactivate ANY device in the tenant. Gated by devices.admin (no owner check).
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['devices.admin'] },
+  PUT: { requireAuth: true, requireFeatures: ['devices.admin'] },
+  DELETE: { requireAuth: true, requireFeatures: ['devices.admin'] },
+}
+
+const paramsSchema = z.object({ id: z.string().uuid() })
+
+async function loadDevice(
+  container: Awaited<ReturnType<typeof createRequestContainer>>,
+  id: string,
+  tenantId: string,
+): Promise<UserDevice | null> {
+  const em = container.resolve('em') as EntityManager
+  // push_token is encrypted at rest; the org is not known until the row loads, so pass tenant only —
+  // the helper prefers each record's own tenant/org and treats this scope as a fallback.
+  return findOneWithDecryption(em, UserDevice, { id, tenantId, deletedAt: null }, undefined, { tenantId })
+}
+
+// push_token is a secret and is never returned.
+function serializeDevice(device: UserDevice) {
+  return {
+    id: device.id,
+    user_id: device.userId,
+    device_id: device.deviceId,
+    platform: device.platform,
+    client_app_version: device.clientAppVersion ?? null,
+    os_version: device.osVersion ?? null,
+    push_provider: device.pushProvider ?? null,
+    push_token_updated_at: device.pushTokenUpdatedAt ? device.pushTokenUpdatedAt.toISOString() : null,
+    last_seen_at: device.lastSeenAt ? device.lastSeenAt.toISOString() : null,
+    created_at: device.createdAt ? device.createdAt.toISOString() : null,
+    updated_at: device.updatedAt ? device.updatedAt.toISOString() : null,
+  }
+}
+
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+    const parsedParams = paramsSchema.safeParse({ id: params.id })
+    if (!parsedParams.success) {
+      return NextResponse.json({ error: translate('devices.errors.invalid_id', 'Invalid device id') }, { status: 400 })
+    }
+    const device = await loadDevice(container, parsedParams.data.id, auth.tenantId)
+    if (!device) {
+      return NextResponse.json({ error: translate('devices.errors.not_found', 'Device not found') }, { status: 404 })
+    }
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: device.organizationId ?? null })) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+    return NextResponse.json({ item: serializeDevice(device) })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.admin.GET failed', { err })
+    return NextResponse.json({ error: translate('devices.errors.load_failed', 'Failed to load device') }, { status: 500 })
+  }
+}
+
+export async function PUT(req: Request, { params }: { params: { id: string } }) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+    const parsedParams = paramsSchema.safeParse({ id: params.id })
+    if (!parsedParams.success) {
+      return NextResponse.json({ error: translate('devices.errors.invalid_id', 'Invalid device id') }, { status: 400 })
+    }
+
+    const body = updateDeviceSchema.parse(await readJsonSafe(req, {}))
+    const device = await loadDevice(container, parsedParams.data.id, auth.tenantId)
+    if (!device) {
+      return NextResponse.json({ error: translate('devices.errors.not_found', 'Device not found') }, { status: 404 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: device.organizationId ?? null })) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+    const mctx: DeviceMutationContext = {
+      container,
+      auth,
+      scope,
+      organizationId: device.organizationId ?? null,
+      actorUserId,
+      request: req,
+    }
+    return await executeUpdate(mctx, device, body)
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('devices.errors.invalid_payload', 'Invalid device payload'), details: err.flatten() },
+        { status: 400 },
+      )
+    }
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.admin.PUT failed', { err })
+    return NextResponse.json({ error: translate('devices.errors.update_failed', 'Failed to update device') }, { status: 500 })
+  }
+}
+
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+    const parsedParams = paramsSchema.safeParse({ id: params.id })
+    if (!parsedParams.success) {
+      return NextResponse.json({ error: translate('devices.errors.invalid_id', 'Invalid device id') }, { status: 400 })
+    }
+
+    const device = await loadDevice(container, parsedParams.data.id, auth.tenantId)
+    if (!device) {
+      return NextResponse.json({ error: translate('devices.errors.not_found', 'Device not found') }, { status: 404 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: device.organizationId ?? null })) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+    const mctx: DeviceMutationContext = {
+      container,
+      auth,
+      scope,
+      organizationId: device.organizationId ?? null,
+      actorUserId,
+      request: req,
+    }
+    return await executeDeactivate(mctx, device)
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.admin.DELETE failed', { err })
+    return NextResponse.json({ error: translate('devices.errors.delete_failed', 'Failed to delete device') }, { status: 500 })
+  }
+}
+
+const okResponseSchema = z.object({ ok: z.literal(true), id: z.string().uuid().optional() })
+const errorResponseSchema = z.object({ error: z.string() })
+const detailResponseSchema = z.object({
+  item: z.object({
+    id: z.string().uuid(),
+    user_id: z.string().uuid(),
+    device_id: z.string(),
+    platform: z.enum(['ios', 'android', 'web']),
+    client_app_version: z.string().nullable(),
+    os_version: z.string().nullable(),
+    push_provider: z.string().nullable(),
+    push_token_updated_at: z.string().nullable(),
+    last_seen_at: z.string().nullable(),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+  }),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Devices (admin)',
+  summary: 'Admin: read, update or deactivate any device in the tenant',
+  methods: {
+    GET: {
+      summary: 'Get any device',
+      description: 'Admin: fetch a single device by id (push_token is never returned).',
+      responses: [{ status: 200, description: 'Device', schema: detailResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid id', schema: errorResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
+        { status: 403, description: 'Missing devices.admin', schema: errorResponseSchema },
+        { status: 404, description: 'Device not found', schema: errorResponseSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Update any device',
+      description: 'Admin: update last-seen, app/OS metadata, and push token for any device. Set pushToken to null to clear it.',
+      requestBody: { schema: updateDeviceSchema },
+      responses: [{ status: 200, description: 'Device updated', schema: okResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid payload or id', schema: errorResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
+        { status: 403, description: 'Missing devices.admin', schema: errorResponseSchema },
+        { status: 404, description: 'Device not found', schema: errorResponseSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Deactivate any device',
+      description: 'Admin: soft-delete any device in the tenant.',
+      responses: [{ status: 200, description: 'Device deactivated', schema: okResponseSchema }],
+      errors: [
+        { status: 400, description: 'Invalid id', schema: errorResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
+        { status: 403, description: 'Missing devices.admin', schema: errorResponseSchema },
+        { status: 404, description: 'Device not found', schema: errorResponseSchema },
+      ],
+    },
+  },
+}