@molecule/api-resource-firmware 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-resource-firmware` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-resource-firmware is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `@molecule/api-resource-firmware` — owner-scoped firmware versions
+ * and OTA rollouts.
+ *
+ * - Versions follow a draft → published → deprecated lifecycle.
+ * - Rollouts target an explicit `device_ids[]` list, a `fleet_id`, or
+ *   both. The intersection with owner-scoped devices is what actually
+ *   gets enrolled.
+ * - Per-device `firmware_update_tasks` rows are materialized and a
+ *   matching `device_commands` row with `firmware_update` payload is
+ *   created. Best-effort realtime broadcasts go out on
+ *   `firmware:{deviceId}` and `commands:{deviceId}`.
+ * - The device reports back via a token-authenticated status endpoint;
+ *   the resource updates the rollout's completed/failed counters and
+ *   bumps the device's `firmware_version` on success.
+ *
+ * Extracted from the iot-device-manager flagship.
+ *
+ * @example
+ * ```ts
+ * import express from 'express'
+ * import {
+ *   createFirmwareRouter,
+ *   type DeviceTokenMiddleware,
+ * } from '@molecule/api-resource-firmware'
+ *
+ * // Device-auth implementations vary per deployment (token, mTLS, JWT, …),
+ * // so the status-report endpoint takes a caller-supplied authorizer. On
+ * // success it MUST set `res.locals.deviceAuth = { deviceId, ownerId }`;
+ * // on failure it responds 401.
+ * const requireDeviceToken: DeviceTokenMiddleware = async (req, res, next) => {
+ *   const device = await verifyDeviceToken(req.header('authorization'))
+ *   if (!device) {
+ *     res.sendStatus(401)
+ *     return
+ *   }
+ *   res.locals.deviceAuth = { deviceId: device.id, ownerId: device.ownerId }
+ *   next()
+ * }
+ *
+ * const app = express()
+ * app.use('/api/firmware', createFirmwareRouter({ requireDeviceToken }))
+ * ```
+ *
+ * @remarks
+ * The schema in `__setup__/firmware.sql` creates `firmware_versions`,
+ * `firmware_rollouts`, and `firmware_update_tasks`. The resource also
+ * reads/writes `iot_devices`, `fleets`, `fleet_memberships`,
+ * `device_commands`, and `device_alerts` — those tables are owned by
+ * the iot-device-manager template.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * `@molecule/api-resource-firmware` — owner-scoped firmware versions
+ * and OTA rollouts.
+ *
+ * - Versions follow a draft → published → deprecated lifecycle.
+ * - Rollouts target an explicit `device_ids[]` list, a `fleet_id`, or
+ *   both. The intersection with owner-scoped devices is what actually
+ *   gets enrolled.
+ * - Per-device `firmware_update_tasks` rows are materialized and a
+ *   matching `device_commands` row with `firmware_update` payload is
+ *   created. Best-effort realtime broadcasts go out on
+ *   `firmware:{deviceId}` and `commands:{deviceId}`.
+ * - The device reports back via a token-authenticated status endpoint;
+ *   the resource updates the rollout's completed/failed counters and
+ *   bumps the device's `firmware_version` on success.
+ *
+ * Extracted from the iot-device-manager flagship.
+ *
+ * @example
+ * ```ts
+ * import express from 'express'
+ * import {
+ *   createFirmwareRouter,
+ *   type DeviceTokenMiddleware,
+ * } from '@molecule/api-resource-firmware'
+ *
+ * // Device-auth implementations vary per deployment (token, mTLS, JWT, …),
+ * // so the status-report endpoint takes a caller-supplied authorizer. On
+ * // success it MUST set `res.locals.deviceAuth = { deviceId, ownerId }`;
+ * // on failure it responds 401.
+ * const requireDeviceToken: DeviceTokenMiddleware = async (req, res, next) => {
+ *   const device = await verifyDeviceToken(req.header('authorization'))
+ *   if (!device) {
+ *     res.sendStatus(401)
+ *     return
+ *   }
+ *   res.locals.deviceAuth = { deviceId: device.id, ownerId: device.ownerId }
+ *   next()
+ * }
+ *
+ * const app = express()
+ * app.use('/api/firmware', createFirmwareRouter({ requireDeviceToken }))
+ * ```
+ *
+ * @remarks
+ * The schema in `__setup__/firmware.sql` creates `firmware_versions`,
+ * `firmware_rollouts`, and `firmware_update_tasks`. The resource also
+ * reads/writes `iot_devices`, `fleets`, `fleet_memberships`,
+ * `device_commands`, and `device_alerts` — those tables are owned by
+ * the iot-device-manager template.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Express router factory for the firmware resource. Mount at any base
+ * path (e.g. `/api/firmware`).
+ *
+ * The per-device status-report endpoint requires a caller-supplied
+ * device-token authorizer middleware (since device-auth implementations
+ * vary across deployments — token, mTLS, JWT, etc.).
+ *
+ * @module
+ */
+import { type RequestHandler, Router } from 'express';
+/**
+ * Caller-supplied device-token authorization. Should set
+ * `res.locals.deviceAuth = { deviceId, ownerId }` on success or 401 on
+ * failure.
+ */
+export type DeviceTokenMiddleware = RequestHandler;
+/** Build the firmware router. */
+export declare function createFirmwareRouter(opts: {
+    requireDeviceToken: DeviceTokenMiddleware;
+}): Router;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAgB,KAAK,cAAc,EAAiB,MAAM,EAAE,MAAM,SAAS,CAAA;AAiClF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAA;AA4BlD,iCAAiC;AACjC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,kBAAkB,EAAE,qBAAqB,CAAA;CAAE,GAAG,MAAM,CAyKhG"}

package/dist/routes.js

@@ -0,0 +1,199 @@
+/**
+ * Express router factory for the firmware resource. Mount at any base
+ * path (e.g. `/api/firmware`).
+ *
+ * The per-device status-report endpoint requires a caller-supplied
+ * device-token authorizer middleware (since device-auth implementations
+ * vary across deployments — token, mTLS, JWT, etc.).
+ *
+ * @module
+ */
+import { Router } from 'express';
+import { getParamId, getUserId } from '@molecule/api-bonds-default-express';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { validateBody as validateBodyRaw, validateQuery as validateQueryRaw, } from '@molecule/api-middleware-validation';
+import { createFirmwareForOwner, createRolloutForOwner, getFirmwareForOwner, listFirmwareForOwner, listRolloutsForOwner, publishFirmwareForOwner, recordRolloutDeviceStatus, updateFirmwareForOwner, } from './service.js';
+import { createFirmwareSchema, createRolloutSchema, listFirmwareQuerySchema, listRolloutsQuerySchema, rolloutDeviceStatusSchema, updateFirmwareSchema, } from './validation.js';
+const validateBody = validateBodyRaw;
+const validateQuery = validateQueryRaw;
+/** Responds with a 401 Unauthorized JSON error. */
+function unauthorized(res) {
+    return res.status(401).json({
+        error: t('auth.unauthorized', undefined, { defaultValue: 'Authentication required.' }),
+    });
+}
+/** Responds with a 404 Not Found JSON error for a missing firmware version. */
+function firmwareNotFound(res) {
+    return res.status(404).json({
+        error: t('firmware.notFound', undefined, { defaultValue: 'Firmware version not found.' }),
+    });
+}
+/** Responds with a 500 Internal Server Error JSON error. */
+function internalError(res) {
+    return res.status(500).json({
+        error: t('errors.internalServer', undefined, { defaultValue: 'Internal server error.' }),
+    });
+}
+/** Build the firmware router. */
+export function createFirmwareRouter(opts) {
+    const router = Router();
+    router.get('/', validateQuery(listFirmwareQuerySchema), async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const q = req.query;
+            res.json(await listFirmwareForOwner(userId, q));
+        }
+        catch (error) {
+            logger.error('listFirmwareForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.get('/rollouts/list', validateQuery(listRolloutsQuerySchema), async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const q = req.query;
+            res.json(await listRolloutsForOwner(userId, q));
+        }
+        catch (error) {
+            logger.error('listRolloutsForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.get('/:id', async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const row = await getFirmwareForOwner(userId, getParamId(req));
+            if (!row)
+                return firmwareNotFound(res);
+            res.json(row);
+        }
+        catch (error) {
+            logger.error('getFirmwareForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.post('/', validateBody(createFirmwareSchema), async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const created = await createFirmwareForOwner(userId, req.body);
+            if (!created)
+                return internalError(res);
+            res.status(201).json(created);
+        }
+        catch (error) {
+            logger.error('createFirmwareForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.put('/:id', validateBody(updateFirmwareSchema), async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const updated = await updateFirmwareForOwner(userId, getParamId(req), req.body);
+            if (!updated)
+                return firmwareNotFound(res);
+            res.json(updated);
+        }
+        catch (error) {
+            logger.error('updateFirmwareForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.post('/:id/publish', async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const published = await publishFirmwareForOwner(userId, getParamId(req));
+            if (!published)
+                return firmwareNotFound(res);
+            res.json(published);
+        }
+        catch (error) {
+            logger.error('publishFirmwareForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.post('/rollouts', validateBody(createRolloutSchema), async (req, res) => {
+        try {
+            const userId = getUserId(res);
+            if (!userId)
+                return unauthorized(res);
+            const body = req.body;
+            const result = await createRolloutForOwner(userId, body);
+            if (!result.ok) {
+                if (result.reason === 'not_found')
+                    return firmwareNotFound(res);
+                if (result.reason === 'not_published') {
+                    return res.status(400).json({
+                        error: t('firmware.notPublished', undefined, {
+                            defaultValue: 'Firmware must be published before rollout.',
+                        }),
+                    });
+                }
+                return res.status(400).json({
+                    error: t('firmware.rolloutTargetsRequired', undefined, {
+                        defaultValue: 'At least one owned device id or a fleet with members is required.',
+                    }),
+                });
+            }
+            res.status(201).json(result.rollout);
+        }
+        catch (error) {
+            logger.error('createRolloutForOwner failed', { error });
+            internalError(res);
+        }
+    });
+    router.post('/rollouts/:rolloutId/devices/:deviceId/status', opts.requireDeviceToken, validateBody(rolloutDeviceStatusSchema), async (req, res) => {
+        try {
+            const auth = res.locals.deviceAuth;
+            if (!auth) {
+                return res.status(401).json({
+                    error: t('devices.invalidToken', undefined, {
+                        defaultValue: 'Invalid device token.',
+                    }),
+                });
+            }
+            const rolloutId = String(req.params.rolloutId ?? '');
+            const deviceId = String(req.params.deviceId ?? '');
+            if (deviceId !== auth.deviceId) {
+                return res.status(403).json({
+                    error: t('devices.tokenMismatch', undefined, {
+                        defaultValue: 'Token does not match device.',
+                    }),
+                });
+            }
+            const body = req.body;
+            const result = await recordRolloutDeviceStatus({
+                rolloutId,
+                deviceId,
+                ownerId: auth.ownerId,
+                status: body.status,
+                errorMessage: body.error_message,
+            });
+            if (!result.ok) {
+                return res.status(404).json({
+                    error: t('firmware.taskNotFound', undefined, {
+                        defaultValue: 'Firmware update task not found.',
+                    }),
+                });
+            }
+            res.json({ ok: true });
+        }
+        catch (error) {
+            logger.error('recordRolloutDeviceStatus failed', { error });
+            internalError(res);
+        }
+    });
+    return router;
+}

package/dist/service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure service-layer helpers for firmware versions and OTA rollouts.
+ * Reusable outside of HTTP contexts (background jobs, automation runs).
+ *
+ * @module
+ */
+import type { FirmwareRolloutRow, FirmwareVersionRow, RolloutStrategy, RolloutTaskStatus } from './types.js';
+/** Whether a string is a syntactically valid UUID. */
+export declare function isUuid(value: string): boolean;
+/** Owner-scoped firmware list. */
+export declare function listFirmwareForOwner(userId: string, filters?: {
+    device_type?: string;
+    status?: string;
+    page?: number;
+    limit?: number;
+}): Promise<FirmwareVersionRow[]>;
+/** Owner-scoped firmware read — null when missing or not owned. */
+export declare function getFirmwareForOwner(userId: string, id: string): Promise<FirmwareVersionRow | null>;
+/** Create a draft firmware version. */
+export declare function createFirmwareForOwner(userId: string, input: {
+    version: string;
+    device_type: string;
+    release_notes?: string;
+    download_url?: string | null;
+    checksum?: string | null;
+    file_size?: number;
+}): Promise<FirmwareVersionRow | null>;
+/** Patch a firmware version owned by the user. */
+export declare function updateFirmwareForOwner(userId: string, id: string, patch: Record<string, unknown>): Promise<FirmwareVersionRow | null>;
+/** Flip a firmware version to published + stamp `released_at`. */
+export declare function publishFirmwareForOwner(userId: string, id: string): Promise<FirmwareVersionRow | null>;
+/**
+ * Create a rollout, materialize per-device tasks + `firmware_update`
+ * device commands, and best-effort broadcast realtime notifications.
+ */
+export declare function createRolloutForOwner(userId: string, input: {
+    firmware_id: string;
+    device_ids?: string[];
+    fleet_id?: string | null;
+    strategy?: RolloutStrategy;
+}): Promise<{
+    ok: true;
+    rollout: FirmwareRolloutRow;
+    targets: string[];
+} | {
+    ok: false;
+    reason: 'not_found' | 'not_published' | 'no_targets';
+}>;
+/** Owner-scoped rollout list. */
+export declare function listRolloutsForOwner(userId: string, filters?: {
+    firmware_id?: string;
+    status?: string;
+    page?: number;
+    limit?: number;
+}): Promise<FirmwareRolloutRow[]>;
+/**
+ * Record a per-device task status report. Updates the rollout's
+ * completed/failed counters + progress percent; on success bumps the
+ * device's `firmware_version` to the new release.
+ */
+export declare function recordRolloutDeviceStatus(opts: {
+    rolloutId: string;
+    deviceId: string;
+    ownerId: string;
+    status: RolloutTaskStatus;
+    errorMessage?: string | null;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: 'task_not_found';
+}>;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -0,0 +1,257 @@
+/**
+ * Pure service-layer helpers for firmware versions and OTA rollouts.
+ * Reusable outside of HTTP contexts (background jobs, automation runs).
+ *
+ * @module
+ */
+import { create, findById, findMany, updateById } from '@molecule/api-database';
+import { broadcast } from '@molecule/api-realtime';
+const FW_TABLE = 'firmware_versions';
+const ROLLOUT_TABLE = 'firmware_rollouts';
+const TASK_TABLE = 'firmware_update_tasks';
+const DEVICE_TABLE = 'iot_devices';
+const COMMAND_TABLE = 'device_commands';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether a string is a syntactically valid UUID. */
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/** Owner-scoped firmware list. */
+export async function listFirmwareForOwner(userId, filters = {}) {
+    const where = [
+        { field: 'owner_id', operator: '=', value: userId },
+    ];
+    if (filters.device_type) {
+        where.push({ field: 'device_type', operator: '=', value: filters.device_type });
+    }
+    if (filters.status)
+        where.push({ field: 'status', operator: '=', value: filters.status });
+    const limit = filters.limit ?? 50;
+    const page = filters.page ?? 1;
+    return findMany(FW_TABLE, {
+        where,
+        orderBy: [{ field: 'created_at', direction: 'desc' }],
+        limit,
+        offset: (page - 1) * limit,
+    });
+}
+/** Owner-scoped firmware read — null when missing or not owned. */
+export async function getFirmwareForOwner(userId, id) {
+    const row = await findById(FW_TABLE, id);
+    if (!row || row.owner_id !== userId)
+        return null;
+    return row;
+}
+/** Create a draft firmware version. */
+export async function createFirmwareForOwner(userId, input) {
+    const result = await create(FW_TABLE, {
+        owner_id: userId,
+        version: input.version,
+        device_type: input.device_type,
+        release_notes: input.release_notes ?? '',
+        download_url: input.download_url ?? null,
+        checksum: input.checksum ?? null,
+        file_size: input.file_size ?? 0,
+        status: 'draft',
+        released_at: null,
+        created_at: new Date(),
+        updated_at: new Date(),
+    });
+    return result.data ?? null;
+}
+/** Patch a firmware version owned by the user. */
+export async function updateFirmwareForOwner(userId, id, patch) {
+    const existing = await getFirmwareForOwner(userId, id);
+    if (!existing)
+        return null;
+    const result = await updateById(FW_TABLE, id, { ...patch, updated_at: new Date() });
+    return result.data ?? null;
+}
+/** Flip a firmware version to published + stamp `released_at`. */
+export async function publishFirmwareForOwner(userId, id) {
+    const existing = await getFirmwareForOwner(userId, id);
+    if (!existing)
+        return null;
+    const result = await updateById(FW_TABLE, id, {
+        status: 'published',
+        released_at: new Date(),
+        updated_at: new Date(),
+    });
+    return result.data ?? null;
+}
+/** Returns all device IDs owned by the given user. */
+async function ownerDeviceIds(userId) {
+    const rows = await findMany(DEVICE_TABLE, {
+        where: [{ field: 'owner_id', operator: '=', value: userId }],
+        limit: 10_000,
+    });
+    return rows.map((r) => r.id);
+}
+/** Returns all device IDs belonging to a fleet that the given user owns. */
+async function fleetDeviceIds(userId, fleetId) {
+    const fleet = await findById('fleets', fleetId);
+    if (!fleet || fleet.owner_id !== userId)
+        return [];
+    const memberships = await findMany('fleet_memberships', {
+        where: [{ field: 'fleet_id', operator: '=', value: fleetId }],
+        limit: 10_000,
+    });
+    return memberships.map((m) => m.device_id);
+}
+/**
+ * Create a rollout, materialize per-device tasks + `firmware_update`
+ * device commands, and best-effort broadcast realtime notifications.
+ */
+export async function createRolloutForOwner(userId, input) {
+    if (!isUuid(input.firmware_id))
+        return { ok: false, reason: 'not_found' };
+    const firmware = await getFirmwareForOwner(userId, input.firmware_id);
+    if (!firmware)
+        return { ok: false, reason: 'not_found' };
+    if (firmware.status !== 'published')
+        return { ok: false, reason: 'not_published' };
+    const owned = new Set(await ownerDeviceIds(userId));
+    const fromExplicit = (input.device_ids ?? []).filter((id) => owned.has(id));
+    const fromFleet = input.fleet_id ? await fleetDeviceIds(userId, input.fleet_id) : [];
+    const targets = Array.from(new Set([...fromExplicit, ...fromFleet]));
+    if (targets.length === 0)
+        return { ok: false, reason: 'no_targets' };
+    const rollout = await create(ROLLOUT_TABLE, {
+        owner_id: userId,
+        firmware_id: input.firmware_id,
+        fleet_id: input.fleet_id ?? null,
+        device_ids: JSON.stringify(targets),
+        strategy: input.strategy ?? 'immediate',
+        status: 'active',
+        target_count: targets.length,
+        completed_count: 0,
+        failed_count: 0,
+        progress_percent: 0,
+        created_at: new Date(),
+        updated_at: new Date(),
+    });
+    const rolloutRow = rollout.data;
+    for (const deviceId of targets) {
+        try {
+            await create(TASK_TABLE, {
+                rollout_id: rolloutRow.id,
+                firmware_id: input.firmware_id,
+                device_id: deviceId,
+                status: 'pending',
+                error_message: null,
+                completed_at: null,
+                created_at: new Date(),
+                updated_at: new Date(),
+            });
+            const cmd = await create(COMMAND_TABLE, {
+                device_id: deviceId,
+                command_type: 'firmware_update',
+                payload: JSON.stringify({
+                    firmware_id: input.firmware_id,
+                    version: firmware.version,
+                    download_url: firmware.download_url,
+                    checksum: firmware.checksum,
+                    rollout_id: rolloutRow.id,
+                }),
+                priority: 'high',
+                status: 'pending',
+                result: null,
+                error_message: null,
+                acknowledged_at: null,
+                completed_at: null,
+                created_at: new Date(),
+                updated_at: new Date(),
+            });
+            try {
+                await broadcast(`firmware:${deviceId}`, 'rollout', {
+                    firmware,
+                    rollout_id: rolloutRow.id,
+                });
+                await broadcast(`commands:${deviceId}`, 'command', { command: cmd.data });
+            }
+            catch (_error) {
+                /* realtime is best-effort — a failed broadcast does not block the rollout */
+            }
+        }
+        catch (_error) {
+            /* per-target failure already recorded as failed task; continue with remaining targets */
+        }
+    }
+    return { ok: true, rollout: rolloutRow, targets };
+}
+/** Owner-scoped rollout list. */
+export async function listRolloutsForOwner(userId, filters = {}) {
+    const where = [
+        { field: 'owner_id', operator: '=', value: userId },
+    ];
+    if (filters.firmware_id) {
+        where.push({ field: 'firmware_id', operator: '=', value: filters.firmware_id });
+    }
+    if (filters.status)
+        where.push({ field: 'status', operator: '=', value: filters.status });
+    const limit = filters.limit ?? 50;
+    const page = filters.page ?? 1;
+    return findMany(ROLLOUT_TABLE, {
+        where,
+        orderBy: [{ field: 'created_at', direction: 'desc' }],
+        limit,
+        offset: (page - 1) * limit,
+    });
+}
+/**
+ * Record a per-device task status report. Updates the rollout's
+ * completed/failed counters + progress percent; on success bumps the
+ * device's `firmware_version` to the new release.
+ */
+export async function recordRolloutDeviceStatus(opts) {
+    const tasks = await findMany(TASK_TABLE, {
+        where: [
+            { field: 'rollout_id', operator: '=', value: opts.rolloutId },
+            { field: 'device_id', operator: '=', value: opts.deviceId },
+        ],
+        limit: 1,
+    });
+    const task = tasks[0];
+    if (!task)
+        return { ok: false, reason: 'task_not_found' };
+    const taskUpdates = {
+        status: opts.status,
+        error_message: opts.errorMessage ?? null,
+        updated_at: new Date(),
+    };
+    if (opts.status === 'completed' || opts.status === 'failed') {
+        taskUpdates.completed_at = new Date();
+    }
+    await updateById(TASK_TABLE, task.id, taskUpdates);
+    const rollout = await findById(ROLLOUT_TABLE, opts.rolloutId);
+    if (rollout && rollout.owner_id === opts.ownerId) {
+        let completed = Number(rollout.completed_count ?? 0);
+        let failed = Number(rollout.failed_count ?? 0);
+        if (opts.status === 'completed')
+            completed += 1;
+        else if (opts.status === 'failed')
+            failed += 1;
+        const target = Number(rollout.target_count ?? 0);
+        const done = completed + failed;
+        const progress = target > 0 ? Math.min(100, Math.round((done * 100) / target)) : 100;
+        const rolloutUpdates = {
+            completed_count: completed,
+            failed_count: failed,
+            progress_percent: progress,
+            updated_at: new Date(),
+        };
+        if (done >= target)
+            rolloutUpdates.status = failed > 0 ? 'failed' : 'completed';
+        await updateById(ROLLOUT_TABLE, opts.rolloutId, rolloutUpdates);
+    }
+    if (opts.status === 'completed') {
+        const firmware = await findById(FW_TABLE, task.firmware_id);
+        if (firmware) {
+            await updateById(DEVICE_TABLE, opts.deviceId, {
+                firmware_version: firmware.version,
+                updated_at: new Date(),
+            });
+        }
+    }
+    return { ok: true };
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Types for firmware versions + rollouts.
+ *
+ * @module
+ */
+/** Lifecycle state of a firmware version. */
+export type FirmwareStatus = 'draft' | 'published' | 'deprecated';
+/** Deployment strategy used when rolling out a firmware version to devices. */
+export type RolloutStrategy = 'immediate' | 'canary' | 'gradual';
+/** Current state of a firmware rollout operation. */
+export type RolloutStatus = 'pending' | 'active' | 'completed' | 'failed' | 'canceled';
+/** Current state of an individual device update task within a rollout. */
+export type RolloutTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+/** Database row representing a firmware version artifact and its metadata. */
+export interface FirmwareVersionRow {
+    id: string;
+    owner_id: string;
+    version: string;
+    device_type: string;
+    release_notes: string;
+    download_url: string | null;
+    checksum: string | null;
+    file_size: number;
+    status: FirmwareStatus;
+    released_at: string | Date | null;
+    created_at: string | Date;
+    updated_at: string | Date;
+}
+/** Database row representing a firmware rollout targeting a fleet or set of devices. */
+export interface FirmwareRolloutRow {
+    id: string;
+    owner_id: string;
+    firmware_id: string;
+    fleet_id: string | null;
+    device_ids: unknown;
+    strategy: RolloutStrategy;
+    status: RolloutStatus;
+    target_count: number;
+    completed_count: number;
+    failed_count: number;
+    progress_percent: number;
+    created_at: string | Date;
+    updated_at: string | Date;
+}
+/** Database row representing a single device's update task within a rollout. */
+export interface FirmwareUpdateTaskRow {
+    id: string;
+    rollout_id: string;
+    firmware_id: string;
+    device_id: string;
+    status: RolloutTaskStatus;
+    error_message: string | null;
+    completed_at: string | Date | null;
+    created_at: string | Date;
+    updated_at: string | Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,CAAA;AACjE,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;AAChE,qDAAqD;AACrD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAA;AACtF,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElF,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,cAAc,CAAA;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,EAAE,eAAe,CAAA;IACzB,MAAM,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAClC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for firmware versions + rollouts.
+ *
+ * @module
+ */
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Zod schemas for firmware-resource payloads.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Allowed lifecycle states for a firmware version. */
+export declare const firmwareStatusSchema: z.ZodEnum<{
+    draft: "draft";
+    published: "published";
+    deprecated: "deprecated";
+}>;
+/** Allowed rollout delivery strategies. */
+export declare const rolloutStrategySchema: z.ZodEnum<{
+    immediate: "immediate";
+    canary: "canary";
+    gradual: "gradual";
+}>;
+/** Allowed progress states for a firmware rollout. */
+export declare const rolloutStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    active: "active";
+    completed: "completed";
+    failed: "failed";
+    canceled: "canceled";
+}>;
+/** Validator for creating a draft firmware version. */
+export declare const createFirmwareSchema: z.ZodObject<{
+    version: z.ZodString;
+    device_type: z.ZodString;
+    release_notes: z.ZodOptional<z.ZodString>;
+    download_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    checksum: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** Validator for patching a firmware version (release notes, status, etc). */
+export declare const updateFirmwareSchema: z.ZodObject<{
+    release_notes: z.ZodOptional<z.ZodString>;
+    download_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    checksum: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        deprecated: "deprecated";
+    }>>;
+}, z.core.$strip>;
+/** Validator for the firmware-version list query params. */
+export declare const listFirmwareQuerySchema: z.ZodObject<{
+    device_type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        deprecated: "deprecated";
+    }>>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** Validator for creating a rollout. */
+export declare const createRolloutSchema: z.ZodObject<{
+    firmware_id: z.ZodString;
+    device_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fleet_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    strategy: z.ZodOptional<z.ZodEnum<{
+        immediate: "immediate";
+        canary: "canary";
+        gradual: "gradual";
+    }>>;
+}, z.core.$strip>;
+/** Validator for the rollout-list query params. */
+export declare const listRolloutsQuerySchema: z.ZodObject<{
+    firmware_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        active: "active";
+        completed: "completed";
+        failed: "failed";
+        canceled: "canceled";
+    }>>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** Validator for a per-device rollout status report. */
+export declare const rolloutDeviceStatusSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        failed: "failed";
+        in_progress: "in_progress";
+    }>;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,uDAAuD;AACvD,eAAO,MAAM,oBAAoB;;;;EAA+C,CAAA;AAChF,2CAA2C;AAC3C,eAAO,MAAM,qBAAqB;;;;EAA6C,CAAA;AAC/E,sDAAsD;AACtD,eAAO,MAAM,mBAAmB;;;;;;EAAmE,CAAA;AAEnG,uDAAuD;AACvD,eAAO,MAAM,oBAAoB;;;;;;;iBAO/B,CAAA;AAEF,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAM/B,CAAA;AAEF,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB;;;;;;;;;iBAKlC,CAAA;AAEF,wCAAwC;AACxC,eAAO,MAAM,mBAAmB;;;;;;;;;iBAK9B,CAAA;AAEF,mDAAmD;AACnD,eAAO,MAAM,uBAAuB;;;;;;;;;;;iBAKlC,CAAA;AAEF,wDAAwD;AACxD,eAAO,MAAM,yBAAyB;;;;;;;;iBAGpC,CAAA"}

package/dist/validation.js

@@ -0,0 +1,55 @@
+/**
+ * Zod schemas for firmware-resource payloads.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Allowed lifecycle states for a firmware version. */
+export const firmwareStatusSchema = z.enum(['draft', 'published', 'deprecated']);
+/** Allowed rollout delivery strategies. */
+export const rolloutStrategySchema = z.enum(['immediate', 'canary', 'gradual']);
+/** Allowed progress states for a firmware rollout. */
+export const rolloutStatusSchema = z.enum(['pending', 'active', 'completed', 'failed', 'canceled']);
+/** Validator for creating a draft firmware version. */
+export const createFirmwareSchema = z.object({
+    version: z.string().min(1),
+    device_type: z.string().min(1),
+    release_notes: z.string().optional(),
+    download_url: z.string().url().nullable().optional(),
+    checksum: z.string().nullable().optional(),
+    file_size: z.coerce.number().int().nonnegative().optional(),
+});
+/** Validator for patching a firmware version (release notes, status, etc). */
+export const updateFirmwareSchema = z.object({
+    release_notes: z.string().optional(),
+    download_url: z.string().url().nullable().optional(),
+    checksum: z.string().nullable().optional(),
+    file_size: z.coerce.number().int().nonnegative().optional(),
+    status: firmwareStatusSchema.optional(),
+});
+/** Validator for the firmware-version list query params. */
+export const listFirmwareQuerySchema = z.object({
+    device_type: z.string().optional(),
+    status: firmwareStatusSchema.optional(),
+    page: z.coerce.number().int().positive().default(1),
+    limit: z.coerce.number().int().positive().max(500).default(50),
+});
+/** Validator for creating a rollout. */
+export const createRolloutSchema = z.object({
+    firmware_id: z.string().min(1),
+    device_ids: z.array(z.string()).optional(),
+    fleet_id: z.string().nullable().optional(),
+    strategy: rolloutStrategySchema.optional(),
+});
+/** Validator for the rollout-list query params. */
+export const listRolloutsQuerySchema = z.object({
+    firmware_id: z.string().optional(),
+    status: rolloutStatusSchema.optional(),
+    page: z.coerce.number().int().positive().default(1),
+    limit: z.coerce.number().int().positive().max(500).default(50),
+});
+/** Validator for a per-device rollout status report. */
+export const rolloutDeviceStatusSchema = z.object({
+    status: z.enum(['pending', 'in_progress', 'completed', 'failed']),
+    error_message: z.string().nullable().optional(),
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@molecule/api-resource-firmware",
+  "version": "1.0.0",
+  "description": "Owner-scoped firmware versions + OTA rollouts: draft/publish/deprecate, per-device update tasks, realtime command dispatch, device-token-authenticated status reporting. Extracted from iot-device-manager flagship.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "firmware",
+    "ota",
+    "iot",
+    "rollout",
+    "resource"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "26.1.2",
+    "express": "5.2.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@molecule/api-bonds-default-express": "^1.0.0",
+    "@molecule/api-database": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0",
+    "@molecule/api-logger": "^1.0.0",
+    "@molecule/api-middleware-validation": "^1.0.0",
+    "@molecule/api-realtime": "^1.0.0",
+    "express": "^5.0.0",
+    "zod": "^4.0.0"
+  }
+}