@owine/unifi-network-mcp 2.14.1 → 2.15.0

package/dist/tools/wifi.js

@@ -5,10 +5,135 @@ const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
+const full_put_js_1 = require("../utils/full-put.js");
+const secrets_js_1 = require("../utils/secrets.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+// Request-body fields per broadcast type, from the 11.0.83 POST/PUT schemas.
+// IOT_OPTIMIZED accepts a strict subset of STANDARD.
+const IOT_OPTIMIZED_FIELDS = [
+    "type",
+    "name",
+    "network",
+    "enabled",
+    "securityConfiguration",
+    "broadcastingDeviceFilter",
+    "mdnsProxyConfiguration",
+    "multicastFilteringPolicy",
+    "multicastToUnicastConversionEnabled",
+    "clientIsolationEnabled",
+    "hideName",
+    "uapsdEnabled",
+    "channel2gLockedTo6",
+    "dtimPeriod2gLockedTo3",
+    "basicDataRateKbpsByFrequencyGHz",
+    "clientFilteringPolicy",
+    "blackoutScheduleConfiguration",
+];
+const STANDARD_FIELDS = [
+    ...IOT_OPTIMIZED_FIELDS,
+    "broadcastingFrequenciesGHz",
+    "hotspotConfiguration",
+    "mloEnabled",
+    "bandSteeringEnabled",
+    "arpProxyEnabled",
+    "bssTransitionEnabled",
+    "advertiseDeviceName",
+    "dtimPeriodByFrequencyGHzOverride",
+    "dnsAssistanceConfiguration",
+    "handoffSuggestionsConfiguration",
+];
+const IOT_OPTIMIZED_REQUIRED = [
+    "type",
+    "name",
+    "enabled",
+    "securityConfiguration",
+    "multicastToUnicastConversionEnabled",
+    "clientIsolationEnabled",
+    "hideName",
+    "uapsdEnabled",
+    "channel2gLockedTo6",
+    "dtimPeriod2gLockedTo3",
+];
+const STANDARD_REQUIRED = [
+    ...IOT_OPTIMIZED_REQUIRED,
+    "broadcastingFrequenciesGHz",
+    "arpProxyEnabled",
+    "bssTransitionEnabled",
+    "advertiseDeviceName",
+];
+function fieldsForType(type) {
+    if (type === "STANDARD")
+        return { allowed: STANDARD_FIELDS, required: STANDARD_REQUIRED };
+    if (type === "IOT_OPTIMIZED")
+        return { allowed: IOT_OPTIMIZED_FIELDS, required: IOT_OPTIMIZED_REQUIRED };
+    throw new Error(`Unsupported WiFi broadcast type: ${String(type)}`);
+}
+const frequencies = zod_1.z
+    .array(zod_1.z.union([zod_1.z.enum(["2.4", "5", "6"]), zod_1.z.literal(2.4), zod_1.z.literal(5), zod_1.z.literal(6)]))
+    .min(1)
+    .describe("Frequencies to broadcast on: 2.4, 5, 6 (strings or numbers; sent as unique numbers). STANDARD only.");
+const config = (description) => zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional().describe(description);
+const flag = (description) => zod_1.z.boolean().optional().describe(description);
+// Every body field as an optional input. Create tightens the core fields to
+// required; update keeps them optional and fills gaps from the current SSID.
+const wifiFields = {
+    name: zod_1.z.string().min(1).optional().describe("SSID name"),
+    enabled: flag("Enable the WiFi network"),
+    type: zod_1.z.enum(["STANDARD", "IOT_OPTIMIZED"]).optional().describe("WiFi type"),
+    broadcastingFrequenciesGHz: frequencies.optional(),
+    securityConfiguration: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .optional()
+        .describe(`Security configuration object (type, passphrase, presharedKeys[], pmfMode, …). A "${secrets_js_1.REDACTED}" value read from unifi_get_wifi is kept as the existing secret on update.`),
+    multicastToUnicastConversionEnabled: flag("Enable multicast to unicast conversion"),
+    clientIsolationEnabled: flag("Enable client isolation"),
+    hideName: flag("Hide SSID name"),
+    uapsdEnabled: flag("Enable Unscheduled Automatic Power Save Delivery"),
+    channel2gLockedTo6: flag("Lock 2.4GHz channel to 6 on all broadcasting devices"),
+    dtimPeriod2gLockedTo3: flag("Lock 2.4GHz DTIM period to 3"),
+    arpProxyEnabled: flag("Enable ARP proxy. STANDARD only."),
+    bssTransitionEnabled: flag("Enable BSS transition. STANDARD only."),
+    advertiseDeviceName: flag("Advertise device name in beacon frames. STANDARD only."),
+    mloEnabled: flag("Enable MLO (Multi-Link Operation). STANDARD only."),
+    bandSteeringEnabled: flag("Enable band steering. STANDARD only."),
+    network: config("Network reference, e.g. {type:'NATIVE'} or {type:'SPECIFIC', networkId:'<uuid>'} (live-observed). Omitted on PPSK SSIDs, where each presharedKeys[] entry carries its own network."),
+    broadcastingDeviceFilter: config("Custom scope of broadcasting devices. Null = broadcast from all AP-capable devices."),
+    mdnsProxyConfiguration: config("mDNS proxy configuration"),
+    multicastFilteringPolicy: config("Multicast filtering policy"),
+    basicDataRateKbpsByFrequencyGHz: config("Basic data rate in kbps by frequency"),
+    clientFilteringPolicy: config("Client MAC address filtering policy"),
+    blackoutScheduleConfiguration: config("Blackout schedule configuration"),
+    hotspotConfiguration: config("Hotspot configuration, e.g. {type:'CAPTIVE_PORTAL'}. STANDARD only."),
+    dtimPeriodByFrequencyGHzOverride: config("DTIM period override by frequency. STANDARD only."),
+    dnsAssistanceConfiguration: config("DNS assistance configuration. STANDARD only."),
+    handoffSuggestionsConfiguration: config("Handoff suggestions config (band5GHzRssiThreshold, band6GHzRssiThreshold). Null disables. STANDARD only."),
+};
+function toBodyFields(values) {
+    const { broadcastingFrequenciesGHz, ...rest } = values;
+    return (0, full_put_js_1.definedEntries)({
+        ...rest,
+        broadcastingFrequenciesGHz: broadcastingFrequenciesGHz && [...new Set(broadcastingFrequenciesGHz.map(Number))],
+    });
+}
+function checkBody(body, updates) {
+    const { allowed, required } = fieldsForType(body.type);
+    const rejected = (0, full_put_js_1.unsupportedFields)(updates, allowed);
+    if (rejected.length > 0) {
+        throw new Error(`Fields not accepted for type ${String(body.type)}: ${rejected.join(", ")}`);
+    }
+    const missing = (0, full_put_js_1.missingFields)(body, required);
+    if (missing.length > 0) {
+        throw new Error(`Missing required fields for type ${String(body.type)}: ${missing.join(", ")}`);
+    }
+}
+const includeSecrets = zod_1.z
+    .boolean()
+    .optional()
+    .describe(`Return WiFi passphrases in plaintext instead of "${secrets_js_1.REDACTED}" (default: false). Only set this when the user explicitly needs the key.`);
+const readRedaction = `Passphrases (securityConfiguration.passphrase, presharedKeys[].passphrase) are returned as "${secrets_js_1.REDACTED}" unless includeSecrets is true.`;
 function registerWifiTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_wifi", {
-        description: "List all WiFi broadcasts (SSIDs) at a site. Returns: id, name (SSID), enabled, type (STANDARD/IOT_OPTIMIZED), broadcastingFrequenciesGHz (2.4/5/6), securityConfiguration, hideName, bandSteeringEnabled, mloEnabled, network reference, broadcastingDeviceFilter (which APs broadcast it). Use for: SSID inventory. For per-AP radio state (channel, txPower), use unifi_get_device on the AP.",
+        description: `List all WiFi broadcasts (SSIDs) at a site. Returns (sparse list view, live-verified on 11.0.83): id, name (SSID), type (STANDARD/IOT_OPTIMIZED), enabled, metadata.origin, network reference (absent on PPSK SSIDs), securityConfiguration.type, broadcastingFrequenciesGHz, hotspotConfiguration (empty object when set). Booleans such as hideName/bandSteeringEnabled/clientIsolationEnabled, the full security configuration and optional configs are only returned by unifi_get_wifi. ${readRedaction} Use for: SSID inventory. For per-AP radio state (channel, txPower), use unifi_get_device on the AP.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -27,32 +152,34 @@ function registerWifiTools(server, client, readOnly = false) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. enabled.eq(true)"),
+            includeSecrets,
         },
         outputSchema: output_schemas_js_1.listWifiOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async ({ siteId, offset, limit, filter }) => {
+    }, async ({ siteId, offset, limit, filter, includeSecrets }) => {
         try {
             const query = (0, query_js_1.buildQuery)({ offset, limit, filter });
             const data = await client.get(`/sites/${siteId}/wifi/broadcasts${query}`);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            return (0, responses_js_1.formatSuccess)(includeSecrets ? data : (0, secrets_js_1.redactSecrets)(data), { structured: true });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
     server.registerTool("unifi_get_wifi", {
-        description: "Get full configuration for a WiFi broadcast (SSID), including all optional fields not always returned by list: clientFilteringPolicy, blackoutScheduleConfiguration, hotspotConfiguration, mdnsProxyConfiguration, handoffSuggestionsConfiguration, dtimPeriodByFrequencyGHzOverride, etc.",
+        description: `Get full configuration for a WiFi broadcast (SSID). Returns the list fields plus the booleans (hideName, clientIsolationEnabled, uapsdEnabled, multicastToUnicastConversionEnabled, bandSteeringEnabled, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName, channel2gLockedTo6, dtimPeriod2gLockedTo3), the full securityConfiguration (type, pmfMode, fastRoamingEnabled, saeConfiguration, presharedKeys[] on PPSK SSIDs, …), and optional configs when configured (omitted otherwise): clientFilteringPolicy, blackoutScheduleConfiguration, hotspotConfiguration, mdnsProxyConfiguration, handoffSuggestionsConfiguration, dtimPeriodByFrequencyGHzOverride, broadcastingDeviceFilter, mloEnabled. ${readRedaction}`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+            includeSecrets,
         },
         outputSchema: output_schemas_js_1.getWifiOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async ({ siteId, wifiBroadcastId }) => {
+    }, async ({ siteId, wifiBroadcastId, includeSecrets }) => {
         try {
             const data = await client.get(`/sites/${siteId}/wifi/broadcasts/${wifiBroadcastId}`);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            return (0, responses_js_1.formatSuccess)(includeSecrets ? data : (0, secrets_js_1.redactSecrets)(data), { structured: true });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
@@ -61,93 +188,22 @@ function registerWifiTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_create_wifi", {
-        description: "Create a new WiFi network (SSID)",
+        description: `Create a new WiFi network (SSID). Required for both types: type, name, enabled, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, channel2gLockedTo6, dtimPeriod2gLockedTo3. STANDARD additionally requires broadcastingFrequenciesGHz, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName; fields marked "STANDARD only" are rejected for IOT_OPTIMIZED (per 11.0.83 docs). The response echo has passphrases redacted. Idempotency: not safe to retry — re-running creates a duplicate SSID.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
-            name: zod_1.z.string().describe("SSID name"),
+            ...wifiFields,
+            name: zod_1.z.string().min(1).describe("SSID name"),
             enabled: zod_1.z.boolean().describe("Enable the WiFi network"),
             type: zod_1.z.enum(["STANDARD", "IOT_OPTIMIZED"]).describe("WiFi type"),
-            broadcastingFrequenciesGHz: zod_1.z
-                .array(zod_1.z.enum(["2.4", "5", "6"]))
-                .describe("Frequencies to broadcast on. Accepted as strings and sent to the API as numbers (2.4, 5, 6)."),
             securityConfiguration: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Security configuration object"),
-            multicastToUnicastConversionEnabled: zod_1.z
-                .boolean()
-                .describe("Enable multicast to unicast conversion"),
-            clientIsolationEnabled: zod_1.z
-                .boolean()
-                .describe("Enable client isolation"),
+                .describe("Security configuration object (type, passphrase, …)"),
+            multicastToUnicastConversionEnabled: zod_1.z.boolean().describe("Enable multicast to unicast conversion"),
+            clientIsolationEnabled: zod_1.z.boolean().describe("Enable client isolation"),
             hideName: zod_1.z.boolean().describe("Hide SSID name"),
-            uapsdEnabled: zod_1.z
-                .boolean()
-                .describe("Enable Unscheduled Automatic Power Save Delivery"),
-            arpProxyEnabled: zod_1.z.boolean().describe("Enable ARP proxy"),
-            bssTransitionEnabled: zod_1.z
-                .boolean()
-                .describe("Enable BSS transition"),
-            advertiseDeviceName: zod_1.z
-                .boolean()
-                .describe("Advertise device name in beacon frames"),
-            channel2gLockedTo6: zod_1.z
-                .boolean()
-                .describe("Lock 2.4GHz channel to 6 on all broadcasting devices"),
-            dtimPeriod2gLockedTo3: zod_1.z
-                .boolean()
-                .describe("Lock 2.4GHz DTIM period to 3"),
-            network: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Network reference"),
-            broadcastingDeviceFilter: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Custom scope of broadcasting devices"),
-            mdnsProxyConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("mDNS proxy configuration"),
-            multicastFilteringPolicy: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Multicast filtering policy"),
-            basicDataRateKbpsByFrequencyGHz: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Basic data rate in kbps by frequency"),
-            clientFilteringPolicy: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Client MAC address filtering policy"),
-            blackoutScheduleConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Blackout schedule configuration"),
-            hotspotConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Hotspot configuration"),
-            mloEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable MLO (Multi-Link Operation)"),
-            bandSteeringEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable band steering"),
-            dtimPeriodByFrequencyGHzOverride: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DTIM period override by frequency"),
-            dnsAssistanceConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DNS assistance configuration"),
-            handoffSuggestionsConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Handoff suggestions config (band5GHzRssiThreshold, band6GHzRssiThreshold). Null disables"),
+            uapsdEnabled: zod_1.z.boolean().describe("Enable Unscheduled Automatic Power Save Delivery"),
+            channel2gLockedTo6: zod_1.z.boolean().describe("Lock 2.4GHz channel to 6 on all broadcasting devices"),
+            dtimPeriod2gLockedTo3: zod_1.z.boolean().describe("Lock 2.4GHz DTIM period to 3"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -155,232 +211,47 @@ function registerWifiTools(server, client, readOnly = false) {
         },
         outputSchema: output_schemas_js_1.getWifiOutputSchema,
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, name, enabled, type, broadcastingFrequenciesGHz, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName, channel2gLockedTo6, dtimPeriod2gLockedTo3, network, broadcastingDeviceFilter, mdnsProxyConfiguration, multicastFilteringPolicy, basicDataRateKbpsByFrequencyGHz, clientFilteringPolicy, blackoutScheduleConfiguration, hotspotConfiguration, mloEnabled, bandSteeringEnabled, dtimPeriodByFrequencyGHzOverride, dnsAssistanceConfiguration, handoffSuggestionsConfiguration, dryRun, }) => {
+    }, async ({ siteId, dryRun, ...fields }) => {
         try {
-            const body = {
-                name,
-                enabled,
-                type,
-                broadcastingFrequenciesGHz: broadcastingFrequenciesGHz.map(Number),
-                securityConfiguration,
-                multicastToUnicastConversionEnabled,
-                clientIsolationEnabled,
-                hideName,
-                uapsdEnabled,
-                arpProxyEnabled,
-                bssTransitionEnabled,
-                advertiseDeviceName,
-                channel2gLockedTo6,
-                dtimPeriod2gLockedTo3,
-            };
-            if (network !== undefined)
-                body.network = network;
-            if (broadcastingDeviceFilter !== undefined)
-                body.broadcastingDeviceFilter = broadcastingDeviceFilter;
-            if (mdnsProxyConfiguration !== undefined)
-                body.mdnsProxyConfiguration = mdnsProxyConfiguration;
-            if (multicastFilteringPolicy !== undefined)
-                body.multicastFilteringPolicy = multicastFilteringPolicy;
-            if (basicDataRateKbpsByFrequencyGHz !== undefined)
-                body.basicDataRateKbpsByFrequencyGHz = basicDataRateKbpsByFrequencyGHz;
-            if (clientFilteringPolicy !== undefined)
-                body.clientFilteringPolicy = clientFilteringPolicy;
-            if (blackoutScheduleConfiguration !== undefined)
-                body.blackoutScheduleConfiguration = blackoutScheduleConfiguration;
-            if (hotspotConfiguration !== undefined)
-                body.hotspotConfiguration = hotspotConfiguration;
-            if (mloEnabled !== undefined)
-                body.mloEnabled = mloEnabled;
-            if (bandSteeringEnabled !== undefined)
-                body.bandSteeringEnabled = bandSteeringEnabled;
-            if (dtimPeriodByFrequencyGHzOverride !== undefined)
-                body.dtimPeriodByFrequencyGHzOverride = dtimPeriodByFrequencyGHzOverride;
-            if (dnsAssistanceConfiguration !== undefined)
-                body.dnsAssistanceConfiguration = dnsAssistanceConfiguration;
-            if (handoffSuggestionsConfiguration !== undefined)
-                body.handoffSuggestionsConfiguration = handoffSuggestionsConfiguration;
+            const body = toBodyFields(fields);
+            checkBody(body, body);
+            if ((0, secrets_js_1.containsRedacted)(body)) {
+                throw new Error(`securityConfiguration contains "${secrets_js_1.REDACTED}" — a new SSID needs the real passphrase`);
+            }
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/wifi/broadcasts`, body);
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/wifi/broadcasts`, (0, secrets_js_1.redactSecrets)(body));
             const data = await client.post(`/sites/${siteId}/wifi/broadcasts`, body);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            return (0, responses_js_1.formatSuccess)((0, secrets_js_1.redactSecrets)(data), { structured: true });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
     server.registerTool("unifi_update_wifi", {
-        description: "Update an existing WiFi network. NOTE: this is a full PUT — API 10.6.106 documents 14 of these fields as required (type, name, enabled, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, channel2gLockedTo6, dtimPeriod2gLockedTo3, broadcastingFrequenciesGHz, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName). They are optional here for convenience, but a sparse update may be rejected by the API — read the current values with unifi_get_wifi and resend the full set if you get a 400.",
+        description: `Update an existing WiFi network. Pass only the fields to change. The API's PUT replaces the whole SSID (11.0.83 documents 14 required fields for STANDARD, 10 for IOT_OPTIMIZED), so this tool reads the current SSID, keeps every documented body field, overlays your changes and sends the full body — omitted fields keep their current values instead of being reset. Pass null to clear an optional config (e.g. broadcastingDeviceFilter: null broadcasts from all APs). Passphrases are kept unless you send a new one; "${secrets_js_1.REDACTED}" values are treated as "keep". dryRun shows the merged body (secrets redacted).`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
-            name: zod_1.z.string().optional().describe("SSID name"),
-            enabled: zod_1.z.boolean().optional().describe("Enable the WiFi network"),
-            type: zod_1.z
-                .enum(["STANDARD", "IOT_OPTIMIZED"])
-                .optional()
-                .describe("WiFi type"),
-            broadcastingFrequenciesGHz: zod_1.z
-                .array(zod_1.z.enum(["2.4", "5", "6"]))
-                .optional()
-                .describe("Frequencies to broadcast on. Accepted as strings and sent to the API as numbers (2.4, 5, 6)."),
-            securityConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Security configuration object"),
-            multicastToUnicastConversionEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable multicast to unicast conversion"),
-            clientIsolationEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable client isolation"),
-            hideName: zod_1.z.boolean().optional().describe("Hide SSID name"),
-            uapsdEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable Unscheduled Automatic Power Save Delivery"),
-            arpProxyEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable ARP proxy"),
-            bssTransitionEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable BSS transition"),
-            advertiseDeviceName: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Advertise device name in beacon frames"),
-            channel2gLockedTo6: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Lock 2.4GHz channel to 6 on all broadcasting devices"),
-            dtimPeriod2gLockedTo3: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Lock 2.4GHz DTIM period to 3"),
-            network: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Network reference"),
-            broadcastingDeviceFilter: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Custom scope of broadcasting devices"),
-            mdnsProxyConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("mDNS proxy configuration"),
-            multicastFilteringPolicy: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Multicast filtering policy"),
-            basicDataRateKbpsByFrequencyGHz: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Basic data rate in kbps by frequency"),
-            clientFilteringPolicy: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Client MAC address filtering policy"),
-            blackoutScheduleConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Blackout schedule configuration"),
-            hotspotConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Hotspot configuration"),
-            mloEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable MLO (Multi-Link Operation)"),
-            bandSteeringEnabled: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Enable band steering"),
-            dtimPeriodByFrequencyGHzOverride: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DTIM period override by frequency"),
-            dnsAssistanceConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DNS assistance configuration"),
-            handoffSuggestionsConfiguration: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("Handoff suggestions config (band5GHzRssiThreshold, band6GHzRssiThreshold). Null disables"),
+            ...wifiFields,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
-                .describe("Preview this action without executing it"),
+                .describe("Preview the merged PUT body without executing it (still reads the current SSID)"),
         },
         outputSchema: output_schemas_js_1.getWifiOutputSchema,
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, wifiBroadcastId, name, enabled, type, broadcastingFrequenciesGHz, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName, channel2gLockedTo6, dtimPeriod2gLockedTo3, network, broadcastingDeviceFilter, mdnsProxyConfiguration, multicastFilteringPolicy, basicDataRateKbpsByFrequencyGHz, clientFilteringPolicy, blackoutScheduleConfiguration, hotspotConfiguration, mloEnabled, bandSteeringEnabled, dtimPeriodByFrequencyGHzOverride, dnsAssistanceConfiguration, handoffSuggestionsConfiguration, dryRun, }) => {
+    }, async ({ siteId, wifiBroadcastId, dryRun, ...fields }) => {
         try {
-            const body = {};
-            if (name !== undefined)
-                body.name = name;
-            if (enabled !== undefined)
-                body.enabled = enabled;
-            if (type !== undefined)
-                body.type = type;
-            if (broadcastingFrequenciesGHz !== undefined)
-                body.broadcastingFrequenciesGHz = broadcastingFrequenciesGHz.map(Number);
-            if (securityConfiguration !== undefined)
-                body.securityConfiguration = securityConfiguration;
-            if (multicastToUnicastConversionEnabled !== undefined)
-                body.multicastToUnicastConversionEnabled =
-                    multicastToUnicastConversionEnabled;
-            if (clientIsolationEnabled !== undefined)
-                body.clientIsolationEnabled = clientIsolationEnabled;
-            if (hideName !== undefined)
-                body.hideName = hideName;
-            if (uapsdEnabled !== undefined)
-                body.uapsdEnabled = uapsdEnabled;
-            if (arpProxyEnabled !== undefined)
-                body.arpProxyEnabled = arpProxyEnabled;
-            if (bssTransitionEnabled !== undefined)
-                body.bssTransitionEnabled = bssTransitionEnabled;
-            if (advertiseDeviceName !== undefined)
-                body.advertiseDeviceName = advertiseDeviceName;
-            if (channel2gLockedTo6 !== undefined)
-                body.channel2gLockedTo6 = channel2gLockedTo6;
-            if (dtimPeriod2gLockedTo3 !== undefined)
-                body.dtimPeriod2gLockedTo3 = dtimPeriod2gLockedTo3;
-            if (network !== undefined)
-                body.network = network;
-            if (broadcastingDeviceFilter !== undefined)
-                body.broadcastingDeviceFilter = broadcastingDeviceFilter;
-            if (mdnsProxyConfiguration !== undefined)
-                body.mdnsProxyConfiguration = mdnsProxyConfiguration;
-            if (multicastFilteringPolicy !== undefined)
-                body.multicastFilteringPolicy = multicastFilteringPolicy;
-            if (basicDataRateKbpsByFrequencyGHz !== undefined)
-                body.basicDataRateKbpsByFrequencyGHz = basicDataRateKbpsByFrequencyGHz;
-            if (clientFilteringPolicy !== undefined)
-                body.clientFilteringPolicy = clientFilteringPolicy;
-            if (blackoutScheduleConfiguration !== undefined)
-                body.blackoutScheduleConfiguration = blackoutScheduleConfiguration;
-            if (hotspotConfiguration !== undefined)
-                body.hotspotConfiguration = hotspotConfiguration;
-            if (mloEnabled !== undefined)
-                body.mloEnabled = mloEnabled;
-            if (bandSteeringEnabled !== undefined)
-                body.bandSteeringEnabled = bandSteeringEnabled;
-            if (dtimPeriodByFrequencyGHzOverride !== undefined)
-                body.dtimPeriodByFrequencyGHzOverride = dtimPeriodByFrequencyGHzOverride;
-            if (dnsAssistanceConfiguration !== undefined)
-                body.dnsAssistanceConfiguration = dnsAssistanceConfiguration;
-            if (handoffSuggestionsConfiguration !== undefined)
-                body.handoffSuggestionsConfiguration = handoffSuggestionsConfiguration;
+            const path = `/sites/${siteId}/wifi/broadcasts/${wifiBroadcastId}`;
+            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current WiFi broadcast");
+            const updates = (0, secrets_js_1.restoreRedacted)(toBodyFields(fields), current);
+            const { allowed } = fieldsForType(updates.type ?? current.type);
+            const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
+            checkBody(body, updates);
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/wifi/broadcasts/${wifiBroadcastId}`, body);
-            const data = await client.put(`/sites/${siteId}/wifi/broadcasts/${wifiBroadcastId}`, body);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+                return (0, safety_js_1.formatDryRun)("PUT", path, (0, secrets_js_1.redactSecrets)(body));
+            const data = await client.put(path, body);
+            return (0, responses_js_1.formatSuccess)((0, secrets_js_1.redactSecrets)(data), { structured: true });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);

package/dist/utils/full-put.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read-merge-write support for UniFi's full-replacement PUT endpoints.
+ *
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies)
+ * replace the whole resource: required fields must all be present, and some
+ * optional fields carry meaning when omitted (a missing `dhcpGuarding`
+ * disables DHCP guarding; a missing `reportFlowEnabled` reverts to true). A
+ * sparse body therefore either fails or silently resets settings.
+ *
+ * Instead, tools GET the current resource, keep only the fields the PUT body
+ * documents (so read-only response fields like id/metadata never leak into the
+ * request), and overlay the caller's changes. `undefined` keeps the current
+ * value; `null` is sent as an explicit null, which the API uses to clear.
+ */
+export type JsonObject = Record<string, unknown>;
+export declare function asObject(value: unknown, what: string): JsonObject;
+export declare function mergeForPut(current: JsonObject, updates: JsonObject, allowedFields: readonly string[]): JsonObject;
+/** Fields the caller set that the target variant's PUT body does not accept. */
+export declare function unsupportedFields(updates: JsonObject, allowedFields: readonly string[]): string[];
+/** Required fields that are absent (undefined or null) from a request body. */
+export declare function missingFields(body: JsonObject, requiredFields: readonly string[]): string[];
+/** Copy only the defined entries, so optional inputs the caller skipped are not sent. */
+export declare function definedEntries(values: JsonObject): JsonObject;

package/dist/utils/full-put.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Read-merge-write support for UniFi's full-replacement PUT endpoints.
+ *
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies)
+ * replace the whole resource: required fields must all be present, and some
+ * optional fields carry meaning when omitted (a missing `dhcpGuarding`
+ * disables DHCP guarding; a missing `reportFlowEnabled` reverts to true). A
+ * sparse body therefore either fails or silently resets settings.
+ *
+ * Instead, tools GET the current resource, keep only the fields the PUT body
+ * documents (so read-only response fields like id/metadata never leak into the
+ * request), and overlay the caller's changes. `undefined` keeps the current
+ * value; `null` is sent as an explicit null, which the API uses to clear.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asObject = asObject;
+exports.mergeForPut = mergeForPut;
+exports.unsupportedFields = unsupportedFields;
+exports.missingFields = missingFields;
+exports.definedEntries = definedEntries;
+function asObject(value, what) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Expected ${what} to be a JSON object`);
+    }
+    return value;
+}
+function mergeForPut(current, updates, allowedFields) {
+    const body = {};
+    for (const field of allowedFields) {
+        if (current[field] !== undefined)
+            body[field] = current[field];
+    }
+    for (const [field, value] of Object.entries(updates)) {
+        if (value !== undefined && allowedFields.includes(field))
+            body[field] = value;
+    }
+    return body;
+}
+/** Fields the caller set that the target variant's PUT body does not accept. */
+function unsupportedFields(updates, allowedFields) {
+    return Object.keys(updates).filter((field) => updates[field] !== undefined && !allowedFields.includes(field));
+}
+/** Required fields that are absent (undefined or null) from a request body. */
+function missingFields(body, requiredFields) {
+    return requiredFields.filter((field) => body[field] === undefined || body[field] === null);
+}
+/** Copy only the defined entries, so optional inputs the caller skipped are not sent. */
+function definedEntries(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}