@owine/unifi-network-mcp 2.14.2 → 3.0.0

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

@@ -0,0 +1,32 @@
+/**
+ * Read-merge-write support for UniFi's full-replacement PUT endpoints.
+ *
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies,
+ * ACL rules, DNS 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;
+/**
+ * Run one read-merge-write cycle at a time per resource. Agents often split
+ * "rename X and enable logging" into parallel calls; unserialised, both read
+ * the old resource and the second PUT silently reverts the first change.
+ * The queue is per process and keyed on the exact path string, so every
+ * writer of a resource (including the firewall-policy PATCH) must lock the
+ * same path.
+ */
+export declare function withResourceLock<T>(path: string, fn: () => Promise<T>): Promise<T>;

package/dist/utils/full-put.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Read-merge-write support for UniFi's full-replacement PUT endpoints.
+ *
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies,
+ * ACL rules, DNS 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;
+exports.withResourceLock = withResourceLock;
+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));
+}
+const resourceQueues = new Map();
+/**
+ * Run one read-merge-write cycle at a time per resource. Agents often split
+ * "rename X and enable logging" into parallel calls; unserialised, both read
+ * the old resource and the second PUT silently reverts the first change.
+ * The queue is per process and keyed on the exact path string, so every
+ * writer of a resource (including the firewall-policy PATCH) must lock the
+ * same path.
+ */
+async function withResourceLock(path, fn) {
+    const previous = resourceQueues.get(path) ?? Promise.resolve();
+    const run = previous.then(fn);
+    const settled = run.then(() => undefined, () => undefined);
+    resourceQueues.set(path, settled);
+    try {
+        return await run;
+    }
+    finally {
+        if (resourceQueues.get(path) === settled)
+            resourceQueues.delete(path);
+    }
+}

package/dist/utils/output-schemas.d.ts

@@ -1,14 +1,33 @@
 /**
- * Output schemas for high-value read tools (loose strategy: every non-key
- * field optional, every nested object uses .passthrough() to allow
+ * Output schemas for every read tool, and for write tools whose response
+ * echoes the resource (loose strategy: every non-key
+ * field optional, every nested object uses .loose() to allow
  * firmware/hardware-specific fields to flow through unchanged).
  *
- * Verified against UniFi Network API 10.6.106. Where the docs collapse
+ * Verified against UniFi Network API 11.0.83. Where the docs collapse
  * nested arrays/objects (e.g. interfaces.ports[], radios[]), the schema
- * uses passthrough records so the contract doesn't lock to fields we
- * haven't verified.
+ * uses loose records so the contract doesn't lock to fields we
+ * haven't verified. Tools register these raw shapes, and registerAllTools()
+ * publishes each as a loose object (src/tools/index.ts), so fields a schema
+ * does not list never fail client-side validation.
  */
 import { z } from "zod";
+/**
+ * The outputSchema to publish for a tool: always a loose object, whether the
+ * tool passed a raw shape or a Zod object (the SDK accepts both). Wrapping a
+ * Zod object in z.looseObject() would build a broken schema that makes
+ * tools/list throw for every tool.
+ */
+export declare function looseOutput(schema: z.ZodRawShape | z.ZodObject): z.ZodObject;
+export declare function writeResult<T extends z.ZodRawShape>(shape: T): { -readonly [k in keyof { -readonly [P in keyof T]: T[P]; }]: z.ZodOptional<{ -readonly [P in keyof T]: T[P]; }[k]>; } & {
+    readonly dryRun: z.ZodOptional<z.ZodLiteral<true>>;
+    readonly wouldExecute: z.ZodOptional<z.ZodObject<{
+        method: z.ZodString;
+        path: z.ZodString;
+        body: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>;
+    readonly confirmationRequired: z.ZodOptional<z.ZodString>;
+};
 export declare const getInfoOutputSchema: {
     applicationVersion: z.ZodOptional<z.ZodString>;
 };
@@ -40,6 +59,7 @@ export declare const networkOutputSchema: {
     ipv6Configuration: z.ZodOptional<z.ZodUnknown>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listNetworksOutputSchema: {
@@ -64,6 +84,7 @@ export declare const listNetworksOutputSchema: {
         ipv6Configuration: z.ZodOptional<z.ZodUnknown>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -129,6 +150,7 @@ export declare const firewallZoneOutputSchema: {
     networkIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listFirewallZonesOutputSchema: {
@@ -142,6 +164,7 @@ export declare const listFirewallZonesOutputSchema: {
         networkIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -157,10 +180,12 @@ export declare const firewallPolicyOutputSchema: {
     ipsecFilter: z.ZodOptional<z.ZodUnknown>;
     schedule: z.ZodOptional<z.ZodUnknown>;
     loggingEnabled: z.ZodOptional<z.ZodBoolean>;
+    reportFlowEnabled: z.ZodOptional<z.ZodBoolean>;
     index: z.ZodOptional<z.ZodNumber>;
     description: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listFirewallPoliciesOutputSchema: {
@@ -180,10 +205,12 @@ export declare const listFirewallPoliciesOutputSchema: {
         ipsecFilter: z.ZodOptional<z.ZodUnknown>;
         schedule: z.ZodOptional<z.ZodUnknown>;
         loggingEnabled: z.ZodOptional<z.ZodBoolean>;
+        reportFlowEnabled: z.ZodOptional<z.ZodBoolean>;
         index: z.ZodOptional<z.ZodNumber>;
         description: z.ZodOptional<z.ZodString>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -199,14 +226,15 @@ export declare const aclRuleOutputSchema: {
     name: z.ZodOptional<z.ZodString>;
     enabled: z.ZodOptional<z.ZodBoolean>;
     action: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    protocolFilter: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    protocolFilter: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     sourceFilter: z.ZodOptional<z.ZodUnknown>;
     destinationFilter: z.ZodOptional<z.ZodUnknown>;
     enforcingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
     index: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listAclRulesOutputSchema: {
@@ -220,14 +248,15 @@ export declare const listAclRulesOutputSchema: {
         name: z.ZodOptional<z.ZodString>;
         enabled: z.ZodOptional<z.ZodBoolean>;
         action: z.ZodOptional<z.ZodString>;
-        description: z.ZodOptional<z.ZodString>;
-        protocolFilter: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        protocolFilter: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
         sourceFilter: z.ZodOptional<z.ZodUnknown>;
         destinationFilter: z.ZodOptional<z.ZodUnknown>;
         enforcingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
         index: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -243,6 +272,7 @@ export declare const switchStackOutputSchema: {
     lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listSwitchStacksOutputSchema: {
@@ -259,6 +289,7 @@ export declare const listSwitchStacksOutputSchema: {
         lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -269,6 +300,7 @@ export declare const mcLagDomainOutputSchema: {
     lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listMcLagDomainsOutputSchema: {
@@ -283,6 +315,7 @@ export declare const listMcLagDomainsOutputSchema: {
         lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -295,6 +328,7 @@ export declare const lagOutputSchema: {
     }, z.core.$loose>>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listLagsOutputSchema: {
@@ -311,6 +345,7 @@ export declare const listLagsOutputSchema: {
         }, z.core.$loose>>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -321,8 +356,20 @@ export declare const dnsPolicyOutputSchema: {
     domain: z.ZodOptional<z.ZodString>;
     ipv4Address: z.ZodOptional<z.ZodString>;
     ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    ipv6Address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    targetDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mailServerDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    serverDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    protocol: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    port: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ipAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listDnsPoliciesOutputSchema: {
@@ -337,8 +384,20 @@ export declare const listDnsPoliciesOutputSchema: {
         domain: z.ZodOptional<z.ZodString>;
         ipv4Address: z.ZodOptional<z.ZodString>;
         ttlSeconds: z.ZodOptional<z.ZodNumber>;
+        ipv6Address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        targetDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mailServerDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        serverDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        protocol: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        port: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        priority: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ipAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -349,6 +408,7 @@ export declare const trafficMatchingListOutputSchema: {
     items: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listTrafficMatchingListsOutputSchema: {
@@ -363,6 +423,7 @@ export declare const listTrafficMatchingListsOutputSchema: {
         items: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -495,6 +556,7 @@ export declare const listWifiOutputSchema: {
         broadcastingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -512,6 +574,7 @@ export declare const getWifiOutputSchema: {
     broadcastingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
+        configurable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 };
 export declare const listWansOutputSchema: {
@@ -536,6 +599,7 @@ export declare const listVpnServersOutputSchema: {
         enabled: z.ZodOptional<z.ZodBoolean>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -559,6 +623,7 @@ export declare const listRadiusProfilesOutputSchema: {
         name: z.ZodOptional<z.ZodString>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
+            configurable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 };
@@ -663,6 +728,9 @@ export declare const listClientHistoryOutputSchema: {
         status: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
     readonly count: z.ZodNumber;
+    readonly totalCount: z.ZodNumber;
+    readonly limit: z.ZodNumber;
+    readonly truncated: z.ZodBoolean;
     readonly withinHours: z.ZodNumber;
     readonly coverage: z.ZodString;
 };