@owine/unifi-network-mcp 2.15.0 → 3.1.0

package/dist/utils/output-schemas.js

@@ -1,22 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listClientSessionsOutputSchema = exports.listClientHistoryOutputSchema = exports.ClientSessionEnvelope = exports.ClientSession = exports.HistoryClient = exports.listPendingDevicesOutputSchema = exports.listCountriesOutputSchema = exports.listDpiApplicationsOutputSchema = exports.listDpiCategoriesOutputSchema = exports.listDeviceTagsOutputSchema = exports.listRadiusProfilesOutputSchema = exports.listVpnTunnelsOutputSchema = exports.listVpnServersOutputSchema = exports.listWansOutputSchema = exports.getWifiOutputSchema = exports.listWifiOutputSchema = exports.getClientOutputSchema = exports.listClientsOutputSchema = exports.getDeviceStatisticsOutputSchema = exports.getDeviceOutputSchema = exports.listDevicesOutputSchema = exports.listTrafficMatchingListsOutputSchema = exports.trafficMatchingListOutputSchema = exports.listDnsPoliciesOutputSchema = exports.dnsPolicyOutputSchema = exports.listLagsOutputSchema = exports.lagOutputSchema = exports.listMcLagDomainsOutputSchema = exports.mcLagDomainOutputSchema = exports.listSwitchStacksOutputSchema = exports.switchStackOutputSchema = exports.aclRuleOrderingOutputSchema = exports.listAclRulesOutputSchema = exports.aclRuleOutputSchema = exports.firewallPolicyOrderingOutputSchema = exports.listFirewallPoliciesOutputSchema = exports.firewallPolicyOutputSchema = exports.listFirewallZonesOutputSchema = exports.firewallZoneOutputSchema = exports.createVouchersOutputSchema = exports.listVouchersOutputSchema = exports.voucherOutputSchema = exports.getNetworkReferencesOutputSchema = exports.listNetworksOutputSchema = exports.networkOutputSchema = exports.listSitesOutputSchema = exports.getInfoOutputSchema = void 0;
+exports.LegacyFirewallRule = exports.ClassicFirewallGroup = exports.ClassicNetwork = exports.listClientSessionsOutputSchema = exports.listClientHistoryOutputSchema = exports.ClientSessionEnvelope = exports.ClientSession = exports.HistoryClient = exports.listPendingDevicesOutputSchema = exports.listCountriesOutputSchema = exports.listDpiApplicationsOutputSchema = exports.listDpiCategoriesOutputSchema = exports.listDeviceTagsOutputSchema = exports.listRadiusProfilesOutputSchema = exports.listVpnTunnelsOutputSchema = exports.listVpnServersOutputSchema = exports.listWansOutputSchema = exports.getWifiOutputSchema = exports.listWifiOutputSchema = exports.getClientOutputSchema = exports.listClientsOutputSchema = exports.getDeviceStatisticsOutputSchema = exports.getDeviceOutputSchema = exports.listDevicesOutputSchema = exports.listTrafficMatchingListsOutputSchema = exports.trafficMatchingListOutputSchema = exports.listDnsPoliciesOutputSchema = exports.dnsPolicyOutputSchema = exports.listLagsOutputSchema = exports.lagOutputSchema = exports.listMcLagDomainsOutputSchema = exports.mcLagDomainOutputSchema = exports.listSwitchStacksOutputSchema = exports.switchStackOutputSchema = exports.aclRuleOrderingOutputSchema = exports.listAclRulesOutputSchema = exports.aclRuleOutputSchema = exports.firewallPolicyOrderingOutputSchema = exports.listFirewallPoliciesOutputSchema = exports.firewallPolicyOutputSchema = exports.listFirewallZonesOutputSchema = exports.firewallZoneOutputSchema = exports.createVouchersOutputSchema = exports.listVouchersOutputSchema = exports.voucherOutputSchema = exports.getNetworkReferencesOutputSchema = exports.listNetworksOutputSchema = exports.networkOutputSchema = exports.listSitesOutputSchema = exports.getInfoOutputSchema = void 0;
+exports.getDeviceSshSettingsOutputSchema = exports.getUpnpStatusOutputSchema = exports.listPortForwardsOutputSchema = exports.PortForward = exports.PortForwardDestination = exports.listLegacyFirewallRulesOutputSchema = exports.listFirewallGroupsOutputSchema = exports.listClassicNetworksOutputSchema = exports.ClassicEnvelope = void 0;
+exports.looseOutput = looseOutput;
+exports.writeResult = writeResult;
 /**
- * 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.
  */
 const zod_1 = require("zod");
 // configurable is live-verified (11.0.83) on system-defined zones, policies,
 // networks and RADIUS profiles; it is absent on user-defined resources.
 const Metadata = zod_1.z
     .object({ origin: zod_1.z.string().optional(), configurable: zod_1.z.boolean().optional() })
-    .passthrough();
+    .loose();
 const PaginationFields = {
     offset: zod_1.z.number().int().optional(),
     limit: zod_1.z.number().int().optional(),
@@ -45,7 +51,7 @@ const DeviceListItem = zod_1.z
     features: zod_1.z.array(zod_1.z.string()).optional(),
     interfaces: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 const DevicePort = zod_1.z
     .object({
     idx: zod_1.z.number(),
@@ -61,10 +67,10 @@ const DevicePort = zod_1.z
         enabled: zod_1.z.boolean().optional(),
         state: zod_1.z.string().optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceRadio = zod_1.z
     .object({
     wlanStandard: zod_1.z.string().optional(),
@@ -72,7 +78,7 @@ const DeviceRadio = zod_1.z
     channelWidthMHz: zod_1.z.number().optional(),
     channel: zod_1.z.number().optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceDetail = zod_1.z
     .object({
     ...DeviceCommon,
@@ -81,7 +87,7 @@ const DeviceDetail = zod_1.z
     configurationId: zod_1.z.string().optional(),
     uplink: zod_1.z
         .object({ deviceId: zod_1.z.string().optional() })
-        .passthrough()
+        .loose()
         .optional(),
     // Detail view: object keyed by capability (switching/accessPoint).
     features: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
@@ -90,10 +96,10 @@ const DeviceDetail = zod_1.z
         ports: zod_1.z.array(DevicePort).optional(),
         radios: zod_1.z.array(DeviceRadio).optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceStatistics = zod_1.z
     .object({
     uptimeSec: zod_1.z.number().optional(),
@@ -109,7 +115,7 @@ const DeviceStatistics = zod_1.z
         txRateBps: zod_1.z.number().optional(),
         rxRateBps: zod_1.z.number().optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
     interfaces: zod_1.z
         .object({
@@ -119,13 +125,13 @@ const DeviceStatistics = zod_1.z
             frequencyGHz: zod_1.z.number().optional(),
             txRetriesPct: zod_1.z.number().optional(),
         })
-            .passthrough())
+            .loose())
             .optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const Client = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -137,10 +143,10 @@ const Client = zod_1.z
     uplinkDeviceId: zod_1.z.string().optional(),
     access: zod_1.z
         .object({ type: zod_1.z.string().optional() })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const WifiBroadcast = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -159,20 +165,20 @@ const WifiBroadcast = zod_1.z
     broadcastingDeviceFilter: zod_1.z.unknown().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const ApplicationInfo = zod_1.z
     .object({
     // Live-verified (11.0.83): only applicationVersion is returned.
     applicationVersion: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const Site = zod_1.z
     .object({
     id: zod_1.z.string(),
     internalReference: zod_1.z.string().optional(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const Network = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -192,12 +198,12 @@ const Network = zod_1.z
     ipv6Configuration: zod_1.z.unknown().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const NetworkReferences = zod_1.z
     .object({
     referenceResources: zod_1.z.array(zod_1.z.unknown()).optional(),
 })
-    .passthrough();
+    .loose();
 const Voucher = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -214,7 +220,7 @@ const Voucher = zod_1.z
     authorizedGuestCount: zod_1.z.number().optional(),
     expired: zod_1.z.boolean().optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallZone = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -222,7 +228,7 @@ const FirewallZone = zod_1.z
     networkIds: zod_1.z.array(zod_1.z.string()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallPolicy = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -244,7 +250,7 @@ const FirewallPolicy = zod_1.z
     description: zod_1.z.string().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallPolicyOrdering = zod_1.z
     .object({
     orderedFirewallPolicyIds: zod_1.z
@@ -252,10 +258,10 @@ const FirewallPolicyOrdering = zod_1.z
         beforeSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
         afterSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const AclRule = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -276,12 +282,12 @@ const AclRule = zod_1.z
     index: zod_1.z.number().int().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const AclRuleOrdering = zod_1.z
     .object({
     orderedAclRuleIds: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 const SwitchStack = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -296,7 +302,7 @@ const SwitchStack = zod_1.z
     lags: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const McLagDomain = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -305,7 +311,7 @@ const McLagDomain = zod_1.z
     lags: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const Lag = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -316,11 +322,11 @@ const Lag = zod_1.z
         deviceId: zod_1.z.string().optional(),
         portIdxs: zod_1.z.array(zod_1.z.number()).optional(),
     })
-        .passthrough())
+        .loose())
         .optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const DnsPolicy = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -344,7 +350,7 @@ const DnsPolicy = zod_1.z
     ipAddress: zod_1.z.string().nullable().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const TrafficMatchingList = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -353,7 +359,7 @@ const TrafficMatchingList = zod_1.z
     items: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 // Verified against the live Integration API (11.0.83). The WAN and
 // site-to-site-tunnel list rows are intentionally minimal in the API.
 const Wan = zod_1.z
@@ -361,7 +367,7 @@ const Wan = zod_1.z
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const VpnServer = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -370,21 +376,21 @@ const VpnServer = zod_1.z
     enabled: zod_1.z.boolean().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 // No tunnels present in the verification environment — keep loose.
 const VpnTunnel = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const RadiusProfile = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 // No tags present in the verification environment — documented shape.
 const DeviceTag = zod_1.z
     .object({
@@ -392,27 +398,27 @@ const DeviceTag = zod_1.z
     name: zod_1.z.string().optional(),
     deviceIds: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 // DPI category/application ids are NUMERIC (verified live).
 const DpiCategory = zod_1.z
     .object({
     id: zod_1.z.number(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const DpiApplication = zod_1.z
     .object({
     id: zod_1.z.number(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 // Countries key on `code` (ISO alpha-2), NOT `id` (verified live).
 const Country = zod_1.z
     .object({
     code: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 // No pending devices in the verification environment — keep loose.
 const PendingDevice = zod_1.z
     .object({
@@ -421,7 +427,31 @@ const PendingDevice = zod_1.z
     ipAddress: zod_1.z.string().optional(),
     firmwareVersion: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
+// A write tool returns either the API's echo of the resource or, with dryRun,
+// a preview of the request it would send. The SDK validates both against the
+// one outputSchema, so the resource's key fields relax to optional alongside
+// the preview fields; read tools keep their stricter schemas.
+const DryRunPreview = {
+    dryRun: zod_1.z.literal(true).optional(),
+    wouldExecute: zod_1.z
+        .object({ method: zod_1.z.string(), path: zod_1.z.string(), body: zod_1.z.unknown().optional() })
+        .loose()
+        .optional(),
+    confirmationRequired: zod_1.z.string().optional(),
+};
+/**
+ * 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.
+ */
+function looseOutput(schema) {
+    return schema instanceof zod_1.z.ZodObject ? schema.loose() : zod_1.z.looseObject(schema);
+}
+function writeResult(shape) {
+    return { ...zod_1.z.object(shape).partial().shape, ...DryRunPreview };
+}
 exports.getInfoOutputSchema = ApplicationInfo.shape;
 exports.listSitesOutputSchema = {
     ...PaginationFields,
@@ -552,7 +582,7 @@ exports.HistoryClient = zod_1.z
     is_wired: zod_1.z.boolean().optional(),
     status: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 exports.ClientSession = zod_1.z
     .object({
     _id: zod_1.z.string(),
@@ -565,15 +595,18 @@ exports.ClientSession = zod_1.z
     is_wired: zod_1.z.boolean().optional(),
     roaming_sessions: zod_1.z.array(zod_1.z.unknown()).optional(),
 })
-    .passthrough();
+    .loose();
 /** Envelope returned by the controller's stat/session endpoint. */
 exports.ClientSessionEnvelope = zod_1.z.object({
-    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).passthrough(),
+    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).loose(),
     data: zod_1.z.array(exports.ClientSession),
 });
 exports.listClientHistoryOutputSchema = {
     data: zod_1.z.array(exports.HistoryClient),
     count: zod_1.z.number(),
+    totalCount: zod_1.z.number(),
+    limit: zod_1.z.number(),
+    truncated: zod_1.z.boolean(),
     withinHours: zod_1.z.number(),
     coverage: zod_1.z.string(),
 };
@@ -586,3 +619,146 @@ exports.listClientSessionsOutputSchema = {
     end: zod_1.z.number(),
     coverage: zod_1.z.string(),
 };
+// Classic controller API reads (rest/networkconf, rest/firewallgroup,
+// rest/firewallrule, rest/portforward, get/setting). Unlike every other schema
+// here, each row shape is also the tool's output allowlist: the tools copy only
+// these fields from a record, so a field the controller adds never reaches the
+// model. networkconf records carry WAN, VPN and RADIUS credentials
+// (x_passphrase, x_wan_password, x_ipsec_*, x_openvpn_*, WireGuard keys, PPPoE
+// logins), and settings sections carry more (x_ssh_password, x_mgmt_key,
+// cloud-access keys); never list one here. Field types vary across controller
+// versions, hence the unions.
+const classicScalar = zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).nullish();
+const classicString = zod_1.z.string().nullish();
+const classicBoolean = zod_1.z.boolean().nullish();
+exports.ClassicNetwork = zod_1.z
+    .object({
+    _id: zod_1.z.string(),
+    name: classicString,
+    purpose: classicString,
+    vlan: classicScalar,
+    vlan_enabled: classicBoolean,
+    ip_subnet: classicString,
+    networkgroup: classicString,
+    enabled: classicBoolean,
+    dhcpd_enabled: classicBoolean,
+    dhcpd_start: classicString,
+    dhcpd_stop: classicString,
+    domain_name: classicString,
+    igmp_snooping: classicBoolean,
+    mdns_enabled: classicBoolean,
+    network_isolation_enabled: classicBoolean,
+    internet_access_enabled: classicBoolean,
+    firewall_zone_id: classicString,
+    is_nat: classicBoolean,
+    ipv6_interface_type: classicString,
+    setting_preference: classicString,
+})
+    .loose();
+exports.ClassicFirewallGroup = zod_1.z
+    .object({
+    _id: zod_1.z.string(),
+    name: classicString,
+    group_type: classicString,
+    group_members: zod_1.z.array(zod_1.z.string()).nullish(),
+})
+    .loose();
+exports.LegacyFirewallRule = zod_1.z
+    .object({
+    _id: zod_1.z.string(),
+    name: classicString,
+    enabled: classicBoolean,
+    ruleset: classicString,
+    rule_index: classicScalar,
+    action: classicString,
+    protocol: classicString,
+    protocol_v6: classicString,
+    protocol_match_excepted: classicBoolean,
+    icmp_typename: classicString,
+    icmpv6_typename: classicString,
+    logging: classicBoolean,
+    state_established: classicBoolean,
+    state_related: classicBoolean,
+    state_new: classicBoolean,
+    state_invalid: classicBoolean,
+    src_firewallgroup_ids: zod_1.z.array(zod_1.z.string()).nullish(),
+    src_networkconf_id: classicString,
+    src_networkconf_type: classicString,
+    src_address: classicString,
+    src_address_ipv6: classicString,
+    src_mac_address: classicString,
+    src_port: classicScalar,
+    dst_firewallgroup_ids: zod_1.z.array(zod_1.z.string()).nullish(),
+    dst_networkconf_id: classicString,
+    dst_networkconf_type: classicString,
+    dst_address: classicString,
+    dst_address_ipv6: classicString,
+    dst_port: classicScalar,
+    ipsec: classicString,
+    setting_preference: classicString,
+})
+    .loose();
+/** Envelope of a classic REST collection; rows stay unknown until the allowlist is applied. */
+exports.ClassicEnvelope = zod_1.z.object({
+    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).loose(),
+    data: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())),
+});
+const classicList = (row) => ({
+    data: zod_1.z.array(row),
+    count: zod_1.z.number(),
+    siteReference: zod_1.z.string(),
+});
+exports.listClassicNetworksOutputSchema = classicList(exports.ClassicNetwork);
+exports.listFirewallGroupsOutputSchema = classicList(exports.ClassicFirewallGroup);
+exports.listLegacyFirewallRulesOutputSchema = classicList(exports.LegacyFirewallRule);
+exports.PortForwardDestination = zod_1.z
+    .object({
+    destination_ip: classicString,
+    interface: classicString,
+})
+    .loose();
+exports.PortForward = zod_1.z
+    .object({
+    _id: zod_1.z.string(),
+    name: classicString,
+    enabled: classicBoolean,
+    pfwd_interface: classicString,
+    destination_ip: classicString,
+    destination_ips: zod_1.z.array(exports.PortForwardDestination).nullish(),
+    src: classicString,
+    src_limiting_enabled: classicBoolean,
+    src_limiting_type: classicString,
+    src_firewall_group_id: classicString,
+    dst_port: classicScalar,
+    fwd: classicString,
+    fwd_port: classicScalar,
+    proto: classicString,
+    log: classicBoolean,
+})
+    .loose();
+exports.listPortForwardsOutputSchema = {
+    data: zod_1.z.array(exports.PortForward),
+    count: zod_1.z.number(),
+    enabledCount: zod_1.z.number(),
+    siteReference: zod_1.z.string(),
+};
+const settingsStatus = zod_1.z.enum(["available", "unavailable"]);
+exports.getUpnpStatusOutputSchema = {
+    siteReference: zod_1.z.string(),
+    status: settingsStatus,
+    source: zod_1.z.string().nullable(),
+    upnp_enabled: zod_1.z.boolean().nullable(),
+    upnp_nat_pmp_enabled: zod_1.z.boolean().nullable(),
+    upnp_secure_mode: zod_1.z.boolean().nullable(),
+    upnp_wan_interface: zod_1.z.string().nullable(),
+    detail: zod_1.z.string(),
+};
+exports.getDeviceSshSettingsOutputSchema = {
+    siteReference: zod_1.z.string(),
+    status: settingsStatus,
+    x_ssh_enabled: zod_1.z.boolean().nullable(),
+    x_ssh_auth_password_enabled: zod_1.z.boolean().nullable(),
+    x_ssh_bind_wildcard: zod_1.z.boolean().nullable(),
+    sshKeyCount: zod_1.z.number().nullable(),
+    detail: zod_1.z.string(),
+};

package/dist/utils/params.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/**
+ * An Integration API resource ID. IDs are interpolated into request paths, so
+ * only the plain ID charset is accepted — anything else could smuggle a query
+ * (`?force=true`), a fragment, or extra path segments into the request.
+ */
+export declare function resourceId(): z.ZodString;
+/**
+ * A site's internalReference (often default), which the controller routes
+ * outside the Integration API take in place of the site UUID.
+ */
+export declare function siteReference(): z.ZodString;

package/dist/utils/params.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceId = resourceId;
+exports.siteReference = siteReference;
+const zod_1 = require("zod");
+/**
+ * An Integration API resource ID. IDs are interpolated into request paths, so
+ * only the plain ID charset is accepted — anything else could smuggle a query
+ * (`?force=true`), a fragment, or extra path segments into the request.
+ */
+function resourceId() {
+    return zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "Use an ID returned by a list or get tool");
+}
+/**
+ * A site's internalReference (often default), which the controller routes
+ * outside the Integration API take in place of the site UUID.
+ */
+function siteReference() {
+    return zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)
+        .describe("Site internalReference from unifi_list_sites (often default), not the Integration API UUID");
+}

package/dist/utils/pick.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copy only the allowlisted fields of a record. Classic records hold
+ * credentials under names no redaction list could anticipate, so the output is
+ * built up from the schema's keys and nothing is ever passed through.
+ */
+export declare function pick(row: Record<string, unknown>, fields: readonly string[]): Record<string, unknown>;

package/dist/utils/pick.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pick = pick;
+/**
+ * Copy only the allowlisted fields of a record. Classic records hold
+ * credentials under names no redaction list could anticipate, so the output is
+ * built up from the schema's keys and nothing is ever passed through.
+ */
+function pick(row, fields) {
+    return Object.fromEntries(fields.filter((field) => Object.hasOwn(row, field)).map((field) => [field, row[field]]));
+}

package/dist/utils/responses.d.ts

@@ -7,6 +7,8 @@ export declare function formatSuccess(data: unknown, opts?: {
     }[];
     structuredContent?: Record<string, unknown>;
 };
+/** The message of a thrown value, which need not be an Error. */
+export declare function errorMessage(err: unknown): string;
 export declare function formatError(err: unknown): {
     content: {
         type: "text";

package/dist/utils/responses.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSuccess = formatSuccess;
+exports.errorMessage = errorMessage;
 exports.formatError = formatError;
 function formatSuccess(data, opts) {
     const result = {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(data) }],
     };
     if (opts?.structured &&
         data !== null &&
@@ -14,10 +15,35 @@ function formatSuccess(data, opts) {
     }
     return result;
 }
+/** The message of a thrown value, which need not be an Error. */
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function formatError(err) {
-    const message = err instanceof Error ? err.message : String(err);
+    let message = errorMessage(err);
+    // fetch reports every network failure as "fetch failed" and keeps the reason
+    // (ECONNREFUSED, ENOTFOUND, a certificate error) in cause.
+    const cause = err instanceof Error ? err.cause : undefined;
+    const code = cause instanceof Error && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+    if (code) {
+        message += ` (${code})`;
+        message += tlsHint(code);
+    }
     return {
         content: [{ type: "text", text: `Error: ${message}` }],
         isError: true,
     };
 }
+/**
+ * What to do about a certificate that did not verify. Pinning makes a
+ * console's own certificate trusted, but it does not lift the validity dates,
+ * so an expired certificate gets its own advice.
+ */
+function tlsHint(code) {
+    if (code === "CERT_HAS_EXPIRED" || code === "CERT_NOT_YET_VALID") {
+        return ". The console's TLS certificate is outside its validity dates; check the clocks on the console and this machine, and renew the certificate if it has expired (pinning it with UNIFI_NETWORK_CA_CERT does not override the dates)";
+    }
+    if (!/CERT|SELF_SIGNED|LEAF_SIGNATURE/.test(code))
+        return "";
+    return ". The console's TLS certificate did not verify. For a local console with a self-signed certificate, save the certificate and point UNIFI_NETWORK_CA_CERT at it; if it is already set, the console has a new certificate, so save it again. Against api.ui.com, something between you and Ubiquiti presented this certificate: do not work around it";
+}