@owine/unifi-network-mcp 2.15.0 → 3.1.0

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

@@ -1,8 +1,8 @@
 /**
  * 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
+ * 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.
@@ -21,3 +21,12 @@ export declare function unsupportedFields(updates: JsonObject, allowedFields: re
 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

@@ -2,8 +2,8 @@
 /**
  * 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
+ * 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.
@@ -19,6 +19,7 @@ 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`);
@@ -49,3 +50,25 @@ function missingFields(body, requiredFields) {
 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 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>;
 };
@@ -709,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;
 };
@@ -731,3 +753,218 @@ export declare const listClientSessionsOutputSchema: {
     readonly end: z.ZodNumber;
     readonly coverage: z.ZodString;
 };
+export declare const ClassicNetwork: z.ZodObject<{
+    _id: z.ZodString;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purpose: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    vlan: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    vlan_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    ip_subnet: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    networkgroup: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    dhcpd_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    dhcpd_start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dhcpd_stop: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    igmp_snooping: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    mdns_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    network_isolation_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    internet_access_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    firewall_zone_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_nat: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    ipv6_interface_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    setting_preference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export declare const ClassicFirewallGroup: z.ZodObject<{
+    _id: z.ZodString;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    group_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    group_members: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$loose>;
+export declare const LegacyFirewallRule: z.ZodObject<{
+    _id: z.ZodString;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    ruleset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rule_index: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    action: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    protocol: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    protocol_v6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    protocol_match_excepted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    icmp_typename: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icmpv6_typename: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    logging: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    state_established: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    state_related: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    state_new: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    state_invalid: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    src_firewallgroup_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    src_networkconf_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_networkconf_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_address_ipv6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_mac_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    dst_firewallgroup_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    dst_networkconf_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dst_networkconf_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dst_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dst_address_ipv6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dst_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    ipsec: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    setting_preference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+/** Envelope of a classic REST collection; rows stay unknown until the allowlist is applied. */
+export declare const ClassicEnvelope: z.ZodObject<{
+    meta: z.ZodObject<{
+        rc: z.ZodLiteral<"ok">;
+    }, z.core.$loose>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const listClassicNetworksOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        purpose: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vlan: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        vlan_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        ip_subnet: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        networkgroup: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        dhcpd_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        dhcpd_start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dhcpd_stop: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        domain_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        igmp_snooping: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        mdns_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        network_isolation_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        internet_access_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        firewall_zone_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        is_nat: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        ipv6_interface_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        setting_preference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly siteReference: z.ZodString;
+};
+export declare const listFirewallGroupsOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        group_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        group_members: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly siteReference: z.ZodString;
+};
+export declare const listLegacyFirewallRulesOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        ruleset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        rule_index: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        action: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        protocol: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        protocol_v6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        protocol_match_excepted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        icmp_typename: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        icmpv6_typename: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        logging: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        state_established: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        state_related: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        state_new: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        state_invalid: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        src_firewallgroup_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        src_networkconf_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_networkconf_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_address_ipv6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_mac_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        dst_firewallgroup_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        dst_networkconf_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dst_networkconf_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dst_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dst_address_ipv6: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dst_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        ipsec: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        setting_preference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly siteReference: z.ZodString;
+};
+export declare const PortForwardDestination: z.ZodObject<{
+    destination_ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    interface: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export declare const PortForward: z.ZodObject<{
+    _id: z.ZodString;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    pfwd_interface: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    destination_ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    destination_ips: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        destination_ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        interface: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>>;
+    src: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_limiting_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    src_limiting_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    src_firewall_group_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dst_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    fwd: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fwd_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    proto: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    log: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$loose>;
+export declare const listPortForwardsOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        pfwd_interface: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        destination_ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        destination_ips: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            destination_ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            interface: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>>;
+        src: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_limiting_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        src_limiting_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        src_firewall_group_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dst_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        fwd: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fwd_port: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        proto: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        log: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly enabledCount: z.ZodNumber;
+    readonly siteReference: z.ZodString;
+};
+export declare const getUpnpStatusOutputSchema: {
+    readonly siteReference: z.ZodString;
+    readonly status: z.ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+    }>;
+    readonly source: z.ZodNullable<z.ZodString>;
+    readonly upnp_enabled: z.ZodNullable<z.ZodBoolean>;
+    readonly upnp_nat_pmp_enabled: z.ZodNullable<z.ZodBoolean>;
+    readonly upnp_secure_mode: z.ZodNullable<z.ZodBoolean>;
+    readonly upnp_wan_interface: z.ZodNullable<z.ZodString>;
+    readonly detail: z.ZodString;
+};
+export declare const getDeviceSshSettingsOutputSchema: {
+    readonly siteReference: z.ZodString;
+    readonly status: z.ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+    }>;
+    readonly x_ssh_enabled: z.ZodNullable<z.ZodBoolean>;
+    readonly x_ssh_auth_password_enabled: z.ZodNullable<z.ZodBoolean>;
+    readonly x_ssh_bind_wildcard: z.ZodNullable<z.ZodBoolean>;
+    readonly sshKeyCount: z.ZodNullable<z.ZodNumber>;
+    readonly detail: z.ZodString;
+};