@alchemy-unifi/network 0.0.1 → 0.1.0

package/src/TrafficMatchingList.ts

@@ -0,0 +1,250 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import { Unowned } from "alchemy/AdoptPolicy";
+import type { Diff } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { UserFacingError } from "alchemy/UserFacingError";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { withConnection } from "./Connection.ts";
+import { type DistributiveOmit, isCurrent, omitKeys } from "./internal/Fields.ts";
+import { plannedString, UNKNOWN } from "./internal/Plan.ts";
+import { captureServices } from "./internal/Services.ts";
+import { describeQuery, LookupNotFound } from "./Lookup.ts";
+import type { Providers } from "./Providers.ts";
+import * as ReadCache from "./ReadCache.ts";
+import { checkSameSite, resolveSite, type Site } from "./Site.ts";
+
+/**
+ * Props are the Integration API's list body plus `site`. `type` picks what
+ * it holds: `"IPV4_ADDRESSES"`, `"IPV6_ADDRESSES"` or `"PORTS"` (no MACs).
+ */
+export type TrafficMatchingListProps = Sdk.CreateOrUpdateTrafficMatchingList & {
+	/** Site to create the list in. @default the profile's site, else the console's only site */
+	site?: string;
+};
+
+/** A list: a `TrafficMatchingList` resource, a {@link TrafficMatchingList.lookup} result, or `{ trafficMatchingListId }`. */
+export interface TrafficMatchingListReference {
+	readonly trafficMatchingListId: string;
+	readonly siteId?: string | undefined;
+}
+
+export interface TrafficMatchingListAttributes {
+	siteId: string;
+	trafficMatchingListId: string;
+	name: string;
+	type: TrafficMatchingListProps["type"];
+	/** The whole list as the console reports it, so `alchemy drift` sees any change. */
+	config: DistributiveOmit<Sdk.TrafficMatchingList, "id">;
+}
+
+export interface TrafficMatchingList extends Resource<
+	"UnifiNetwork.TrafficMatchingList",
+	TrafficMatchingListProps,
+	TrafficMatchingListAttributes,
+	never,
+	Providers
+> {}
+
+const loadLists = (siteId: string) => withConnection(Stream.runCollect(Sdk.getTrafficMatchingLists.items({ siteId })));
+const listsKey = ReadCache.key<ReadonlyArray<Sdk.TrafficMatchingList>, Effect.Error<ReturnType<typeof loadLists>>>(
+	"trafficMatchingLists",
+);
+
+/** A site's traffic-matching lists, listed once per run. */
+export const listTrafficMatchingLists = (siteId: string) => ReadCache.cached(listsKey, siteId, loadLists(siteId));
+
+const toAttributes = (siteId: string, list: Sdk.TrafficMatchingList): TrafficMatchingListAttributes => {
+	const { id, ...config } = list;
+	return { siteId, trafficMatchingListId: id, name: list.name, type: list.type, config };
+};
+
+/** Fields the console reports but rejects in request bodies. */
+const READ_ONLY = ["id"];
+
+/** A list can't be deleted while something references it. */
+export class TrafficMatchingListInUse extends Data.TaggedError("TrafficMatchingListInUse")<{
+	readonly listName: string;
+	/** Names of the firewall policies referencing it, as far as they could be found. */
+	readonly referencedBy: ReadonlyArray<string>;
+	readonly detail: string;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		const by =
+			this.referencedBy.length > 0
+				? `firewall policies ${this.referencedBy.map((name) => `"${name}"`).join(", ")}`
+				: `something the provider couldn't identify (${this.detail})`;
+		return `Can't delete traffic-matching list "${this.listName}": it's still referenced by ${by}. Those references aren't managed by this stack (e.g. made in the UI); remove them, then deploy again.`;
+	}
+}
+
+/** User-defined firewall policies that mention `trafficMatchingListId` in a filter. */
+const policiesReferencing = (siteId: string, trafficMatchingListId: string) =>
+	withConnection(Stream.runCollect(Sdk.getFirewallPolicies.items({ siteId }))).pipe(
+		Effect.map((policies) =>
+			policies
+				.filter(
+					(p) =>
+						p.metadata.origin === "USER_DEFINED" &&
+						JSON.stringify([p.source, p.destination]).includes(trafficMatchingListId),
+				)
+				.map((p) => p.name),
+		),
+		Effect.orElseSucceed((): ReadonlyArray<string> => []),
+	);
+
+/** The list ID a reference means in `site`. */
+export const resolveTrafficMatchingList = (reference: TrafficMatchingListReference, site: Site) =>
+	checkSameSite("traffic-matching list", reference.siteId, site).pipe(Effect.as(reference.trafficMatchingListId));
+
+/** A list by ID, from the run's cached lists, which come whole (one request for every list in a plan). */
+const getList = (siteId: string, trafficMatchingListId: string) =>
+	listTrafficMatchingLists(siteId).pipe(Effect.map((lists) => lists.find((l) => l.id === trafficMatchingListId)));
+
+/**
+ * A named list of IPv4 addresses, IPv6 addresses or ports, which firewall
+ * policies reference instead of repeating values inline. Names are unique
+ * per site, so existing lists are adopted by name with `--adopt`. Changing
+ * `type` updates the list in place.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@alchemy-unifi/network";
+ * import * as Alchemy from "alchemy";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ * 	"HomeNetwork",
+ * 	{ providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
+ * 	Effect.gen(function* () {
+ * 		const haHosts = yield* UnifiNetwork.TrafficMatchingList("ha-hosts", {
+ * 			type: "IPV4_ADDRESSES",
+ * 			name: "Home Assistant hosts",
+ * 			items: [{ type: "IP_ADDRESS", value: "192.168.2.20" }],
+ * 		});
+ * 		// Reference it from a policy's filter: { type: "TRAFFIC_MATCHING_LIST", matchOpposite: false, trafficMatchingList: haHosts }
+ * 	}),
+ * );
+ * ```
+ */
+export const TrafficMatchingList = Resource<TrafficMatchingList>("UnifiNetwork.TrafficMatchingList")({
+	/**
+	 * A list in the site by name. Dies with a user-facing `LookupNotFound`:
+	 * stack bodies can't fail with typed errors.
+	 */
+	lookup: Effect.fn("UnifiNetwork.TrafficMatchingList.lookup")(function* (query: {
+		readonly name: string;
+		readonly site?: string;
+	}) {
+		const site = yield* resolveSite(query.site);
+		const list = (yield* listTrafficMatchingLists(site.id)).find((l) => l.name === query.name);
+		if (list === undefined) {
+			return yield* new LookupNotFound({ resource: "traffic-matching list", query: describeQuery(query), site });
+		}
+		return toAttributes(site.id, list);
+	}, Effect.orDie),
+});
+
+export const TrafficMatchingListProvider = () =>
+	Provider.effect(
+		TrafficMatchingList,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return TrafficMatchingList.Provider.of({
+				list: () =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite();
+							return (yield* listTrafficMatchingLists(site.id)).map((list) =>
+								toAttributes(site.id, list),
+							);
+						}),
+					),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								const list = yield* getList(output.siteId, output.trafficMatchingListId);
+								return list === undefined ? undefined : toAttributes(output.siteId, list);
+							}
+							const site = yield* resolveSite(olds.site);
+							const list = (yield* listTrafficMatchingLists(site.id)).find((l) => l.name === olds.name);
+							return list === undefined ? undefined : Unowned(toAttributes(site.id, list));
+						}),
+					),
+
+				diff: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const siteProp = plannedString(news, "site");
+							if (output === undefined || siteProp === UNKNOWN) return undefined;
+							const site = yield* resolveSite(siteProp);
+							if (site.id !== output.siteId) return { action: "replace" } satisfies Diff;
+							return undefined;
+						}),
+					),
+
+				reconcile: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite(news.site);
+							const { site: _site, ...body } = news;
+							const observed =
+								output !== undefined && output.siteId === site.id
+									? yield* getList(site.id, output.trafficMatchingListId)
+									: undefined;
+							const write = ReadCache.invalidating(listsKey, site.id);
+							if (observed === undefined) {
+								const created = yield* withConnection(
+									Sdk.createTrafficMatchingList({ siteId: site.id, body }),
+								).pipe(write);
+								return toAttributes(site.id, created);
+							}
+							if (isCurrent(body, omitKeys(observed, READ_ONLY))) return toAttributes(site.id, observed);
+							const updated = yield* withConnection(
+								Sdk.updateTrafficMatchingList({
+									siteId: site.id,
+									trafficMatchingListId: observed.id,
+									body,
+								}),
+							).pipe(write);
+							return toAttributes(site.id, updated);
+						}),
+					),
+
+				delete: ({ output }) =>
+					run(
+						withConnection(
+							Sdk.deleteTrafficMatchingList({
+								siteId: output.siteId,
+								trafficMatchingListId: output.trafficMatchingListId,
+							}),
+						).pipe(
+							Effect.asVoid,
+							Effect.catchTags({
+								NotFound: () => Effect.void,
+								// 422 "Selected traffic matching list is referenced by other resources".
+								UnprocessableEntity: (error) =>
+									policiesReferencing(output.siteId, output.trafficMatchingListId).pipe(
+										Effect.flatMap((referencedBy) =>
+											Effect.fail(
+												new TrafficMatchingListInUse({
+													listName: output.name,
+													referencedBy,
+													detail: error.message,
+												}),
+											),
+										),
+									),
+							}),
+							ReadCache.invalidating(listsKey, output.siteId),
+						),
+					),
+			});
+		}),
+	);

package/src/WifiBroadcast.ts

@@ -0,0 +1,318 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import { Unowned } from "alchemy/AdoptPolicy";
+import type { Diff } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { withConnection } from "./Connection.ts";
+import { type DistributiveOmit, isCurrent, omitKeys } from "./internal/Fields.ts";
+import { planned, plannedString, UNKNOWN } from "./internal/Plan.ts";
+import { captureServices } from "./internal/Services.ts";
+import { describeQuery, LookupAmbiguous, LookupNotFound } from "./Lookup.ts";
+import { type NetworkReference, resolveNetwork } from "./Network.ts";
+import type { Providers } from "./Providers.ts";
+import * as ReadCache from "./ReadCache.ts";
+import { resolveSite, type Site } from "./Site.ts";
+
+/** The site's native (untagged) network. */
+export interface NativeNetwork {
+	readonly type: "NATIVE";
+}
+
+interface CommonProps {
+	/** Site to create the broadcast in. @default the profile's site, else the console's only site */
+	site?: string;
+	/**
+	 * The network clients join: a network reference, or
+	 * `WifiBroadcast.NATIVE_NETWORK` for the site's default network (a
+	 * `Network` resource or lookup for the default network works too).
+	 */
+	network?: NetworkReference | NativeNetwork;
+}
+
+/** WPA security on a standard broadcast must set `fastRoamingEnabled` (the console rejects it otherwise). */
+type WithFastRoaming<S> = S extends { fastRoamingEnabled?: boolean } ? S & { fastRoamingEnabled: boolean } : S;
+
+export type StandardWifiSecurityConfiguration = WithFastRoaming<Sdk.WifiSecurityConfigurationDetailObject>;
+
+/**
+ * An ordinary SSID. Pass passphrases as `Redacted` (e.g. from
+ * `Config.Redacted`) to keep them out of logs.
+ */
+export interface StandardWifiBroadcastProps
+	extends
+		Omit<Sdk.IntegrationStandardWifiBroadcastCreateUpdateDto, "network" | "securityConfiguration">,
+		CommonProps {
+	securityConfiguration: StandardWifiSecurityConfiguration;
+}
+
+/** An SSID tuned for IoT devices (2.4 GHz only, longer DTIM). */
+export interface IotWifiBroadcastProps
+	extends Omit<Sdk.IntegrationIotOptimizedWifiBroadcastCreateUpdateDto, "network">, CommonProps {}
+
+/** Props are the Integration API's Wi-Fi body, plus `site` and references; `type` picks the kind. */
+export type WifiBroadcastProps = StandardWifiBroadcastProps | IotWifiBroadcastProps;
+
+export interface WifiBroadcastAttributes {
+	siteId: string;
+	wifiBroadcastId: string;
+	name: string;
+	type: WifiBroadcastProps["type"];
+	/** The network clients join, when it isn't the native one. */
+	networkId: string | undefined;
+	/** The whole broadcast as the console reports it (passphrases `Redacted`), so `alchemy drift` sees any change. */
+	config: DistributiveOmit<Sdk.WifiBroadcastDetails, "id" | "metadata">;
+}
+
+export interface WifiBroadcast extends Resource<
+	"UnifiNetwork.WifiBroadcast",
+	WifiBroadcastProps,
+	WifiBroadcastAttributes,
+	never,
+	Providers
+> {}
+
+const loadBroadcasts = (siteId: string) =>
+	withConnection(Stream.runCollect(Sdk.getWifiBroadcastPage.items({ siteId })));
+const broadcastsKey = ReadCache.key<
+	ReadonlyArray<Sdk.WifiBroadcastOverview>,
+	Effect.Error<ReturnType<typeof loadBroadcasts>>
+>("wifiBroadcasts");
+
+/** A site's Wi-Fi broadcasts, listed once per run. */
+export const listWifiBroadcasts = (siteId: string) => ReadCache.cached(broadcastsKey, siteId, loadBroadcasts(siteId));
+
+const toAttributes = (siteId: string, broadcast: Sdk.WifiBroadcastDetails): WifiBroadcastAttributes => {
+	const { id, metadata: _metadata, ...config } = broadcast;
+	return {
+		siteId,
+		wifiBroadcastId: id,
+		name: broadcast.name,
+		type: broadcast.type,
+		networkId: broadcast.network?.type === "SPECIFIC" ? broadcast.network.networkId : undefined,
+		config,
+	};
+};
+
+const byFrequency = (bands: ReadonlyArray<number>) => bands.toSorted((a, b) => a - b);
+
+/**
+ * `body` with its bands sorted (their order means nothing; see
+ * {@link comparable}), and an explicit value for the one unset field that
+ * can't simply be left out (verified): a standard broadcast's
+ * `bandSteeringEnabled`, which the console reports as `false` when unset,
+ * so without the default the body would never match and every deploy would
+ * update it (and drift would report it) forever.
+ */
+const withDefaults = (body: Sdk.WifiBroadcastCreateOrUpdate): Sdk.WifiBroadcastCreateOrUpdate =>
+	body.type === "STANDARD"
+		? {
+				...body,
+				bandSteeringEnabled: body.bandSteeringEnabled ?? false,
+				broadcastingFrequenciesGHz: byFrequency(body.broadcastingFrequenciesGHz),
+			}
+		: body;
+
+/** Fields the console reports but rejects in request bodies. */
+const READ_ONLY = ["id", "metadata"];
+
+const toBody = Effect.fn(function* (props: WifiBroadcastProps, site: Site) {
+	const { site: _site, network, ...rest } = props;
+	if (network === undefined) return rest satisfies Sdk.WifiBroadcastCreateOrUpdate;
+	// The console only accepts the default network as NATIVE; referencing it by ID is rejected.
+	if ("type" in network || network.default === true) {
+		return { ...rest, network: { type: "NATIVE" } } satisfies Sdk.WifiBroadcastCreateOrUpdate;
+	}
+	const networkId = yield* resolveNetwork(network, site);
+	return { ...rest, network: { type: "SPECIFIC", networkId } } satisfies Sdk.WifiBroadcastCreateOrUpdate;
+});
+
+/**
+ * The console's broadcast in body form, with its bands sorted: consoles keep
+ * them in an order of their own (not the one sent; the test controller
+ * sorts them), so order mustn't count as a difference.
+ */
+const comparable = (observed: Sdk.WifiBroadcastDetails) => {
+	const body = omitKeys(observed, READ_ONLY);
+	return observed.type === "STANDARD"
+		? { ...body, broadcastingFrequenciesGHz: byFrequency(observed.broadcastingFrequenciesGHz) }
+		: body;
+};
+
+const getBroadcast = (siteId: string, wifiBroadcastId: string) =>
+	withConnection(Sdk.getWifiBroadcastDetails({ siteId, wifiBroadcastId })).pipe(
+		Effect.catchTag("NotFound", () => Effect.undefined),
+	);
+
+/** The attributes of a broadcast known to exist (e.g. from a list). */
+const attributesOf = (siteId: string, wifiBroadcastId: string) =>
+	withConnection(Sdk.getWifiBroadcastDetails({ siteId, wifiBroadcastId })).pipe(
+		Effect.map((broadcast) => toAttributes(siteId, broadcast)),
+	);
+
+const NATIVE_NETWORK: NativeNetwork = { type: "NATIVE" };
+
+/**
+ * A Wi-Fi network (SSID). `type` picks a standard or an IoT-optimised
+ * broadcast; changing it, or the site, replaces the broadcast.
+ *
+ * Props are authoritative: every update sends the whole broadcast, with
+ * explicit defaults for unset fields (a standard broadcast's
+ * `bandSteeringEnabled: false`), so changes made in the UI, passphrases
+ * included, are put back. The `config` attribute mirrors the console's
+ * object, so `alchemy drift` sees them. Existing broadcasts are adopted by name with
+ * `--adopt`.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@alchemy-unifi/network";
+ * import * as Alchemy from "alchemy";
+ * import * as Config from "effect/Config";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ * 	"HomeNetwork",
+ * 	{ providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
+ * 	Effect.gen(function* () {
+ * 		const lan = yield* UnifiNetwork.Network.lookup({ vlanId: 1 });
+ * 		yield* UnifiNetwork.WifiBroadcast("home", {
+ * 			type: "STANDARD",
+ * 			name: "Home",
+ * 			enabled: true,
+ * 			network: lan,
+ * 			securityConfiguration: {
+ * 				type: "WPA2_PERSONAL",
+ * 				passphrase: yield* Config.Redacted("WIFI_PASSPHRASE"),
+ * 				fastRoamingEnabled: false,
+ * 			},
+ * 			broadcastingFrequenciesGHz: [2.4, 5],
+ * 			hideName: false,
+ * 			clientIsolationEnabled: false,
+ * 			multicastToUnicastConversionEnabled: false,
+ * 			uapsdEnabled: false,
+ * 			channel2gLockedTo6: false,
+ * 			dtimPeriod2gLockedTo3: false,
+ * 			advertiseDeviceName: false,
+ * 			arpProxyEnabled: false,
+ * 			bssTransitionEnabled: true,
+ * 		});
+ * 	}),
+ * );
+ * ```
+ */
+export const WifiBroadcast = Resource<WifiBroadcast>("UnifiNetwork.WifiBroadcast")({
+	NATIVE_NETWORK,
+	/**
+	 * A broadcast in the site by name. Dies with a user-facing
+	 * `LookupNotFound` or `LookupAmbiguous`: stack bodies can't fail with typed
+	 * errors.
+	 */
+	lookup: Effect.fn("UnifiNetwork.WifiBroadcast.lookup")(function* (query: {
+		readonly name: string;
+		readonly site?: string;
+	}) {
+		const site = yield* resolveSite(query.site);
+		const broadcasts = (yield* listWifiBroadcasts(site.id)).filter((b) => b.name === query.name);
+		const [broadcast] = broadcasts;
+		if (broadcast === undefined) {
+			return yield* new LookupNotFound({ resource: "Wi-Fi broadcast", query: describeQuery(query), site });
+		}
+		if (broadcasts.length > 1) {
+			return yield* new LookupAmbiguous({
+				resource: "Wi-Fi broadcast",
+				query: describeQuery(query),
+				site,
+				count: broadcasts.length,
+			});
+		}
+		return yield* attributesOf(site.id, broadcast.id);
+	}, Effect.orDie),
+});
+
+export const WifiBroadcastProvider = () =>
+	Provider.effect(
+		WifiBroadcast,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return WifiBroadcast.Provider.of({
+				list: () =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite();
+							const broadcasts = yield* listWifiBroadcasts(site.id);
+							return yield* Effect.forEach(
+								broadcasts.filter((b) => b.metadata.origin === "USER_DEFINED"),
+								(b) => attributesOf(site.id, b.id),
+							);
+						}),
+					),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								const broadcast = yield* getBroadcast(output.siteId, output.wifiBroadcastId);
+								return broadcast === undefined ? undefined : toAttributes(output.siteId, broadcast);
+							}
+							const site = yield* resolveSite(olds.site);
+							const matching = (yield* listWifiBroadcasts(site.id)).filter((b) => b.name === olds.name);
+							const [broadcast] = matching;
+							return broadcast === undefined || matching.length > 1
+								? undefined
+								: Unowned(yield* attributesOf(site.id, broadcast.id));
+						}),
+					),
+
+				diff: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output === undefined) return undefined;
+							const type = planned(news, "type");
+							if (type !== UNKNOWN && type !== output.type) return { action: "replace" } satisfies Diff;
+							const siteProp = plannedString(news, "site");
+							if (siteProp === UNKNOWN) return undefined;
+							const site = yield* resolveSite(siteProp);
+							if (site.id !== output.siteId) return { action: "replace" } satisfies Diff;
+							return undefined;
+						}),
+					),
+
+				reconcile: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite(news.site);
+							const body = withDefaults(yield* toBody(news, site));
+							const observed =
+								output !== undefined && output.siteId === site.id
+									? yield* getBroadcast(site.id, output.wifiBroadcastId)
+									: undefined;
+							const write = ReadCache.invalidating(broadcastsKey, site.id);
+							if (observed === undefined) {
+								const created = yield* withConnection(
+									Sdk.createWifiBroadcast({ siteId: site.id, body }),
+								).pipe(write);
+								return toAttributes(site.id, created);
+							}
+							if (isCurrent(body, comparable(observed))) return toAttributes(site.id, observed);
+							const updated = yield* withConnection(
+								Sdk.updateWifiBroadcast({ siteId: site.id, wifiBroadcastId: observed.id, body }),
+							).pipe(write);
+							return toAttributes(site.id, updated);
+						}),
+					),
+
+				delete: ({ output }) =>
+					run(
+						withConnection(
+							Sdk.deleteWifiBroadcast({ siteId: output.siteId, wifiBroadcastId: output.wifiBroadcastId }),
+						).pipe(
+							Effect.asVoid,
+							Effect.catchTag("NotFound", () => Effect.void),
+							ReadCache.invalidating(broadcastsKey, output.siteId),
+						),
+					),
+			});
+		}),
+	);

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./AuthConfig.ts";
+export { UnifiNetworkAuth } from "./AuthProvider.ts";
+export { type Established, UnifiNetworkConnection, withConnection } from "./Connection.ts";
+export * from "./Credentials.ts";
+export { Providers, providers } from "./Providers.ts";
+export * as ReadCache from "./ReadCache.ts";
+export { UnifiNetworkReadCache } from "./ReadCache.ts";
+export * from "./Site.ts";
+export { DEFAULT_WARN_AT, state, type UnifiStateOptions } from "./State.ts";
+export * from "./DnsPolicy.ts";
+export * from "./FirewallPolicy.ts";
+export * from "./FirewallPolicyOrdering.ts";
+export * from "./FirewallZone.ts";
+export * from "./Lookup.ts";
+export * from "./Network.ts";
+export * from "./TrafficMatchingList.ts";
+export * from "./WifiBroadcast.ts";

package/src/internal/Fields.ts

@@ -0,0 +1,49 @@
+import { deepEqual } from "alchemy/Diff";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * Comparison of request bodies with what the console reports. Props are
+ * authoritative: a resource's desired body is its props with explicit
+ * defaults for anything unset, sent whole on every update, and the console's
+ * object must equal it field for field.
+ */
+
+/** `Omit` applied to each member of a union, keeping the discriminant. */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
+/** `value` with every `Redacted` unwrapped, recursively, so passphrases compare by contents. */
+const unwrap = (value: unknown): unknown => {
+	if (Redacted.isRedacted(value)) return Redacted.value(value);
+	if (Array.isArray(value)) return value.map(unwrap);
+	if (typeof value === "object" && value !== null) {
+		return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, unwrap(nested)]));
+	}
+	return value;
+};
+
+/**
+ * Whether the console's object is exactly the desired body: same fields,
+ * same values, recursively (key order and `Redacted` wrappers aside; unset
+ * fields must be absent on both sides). Leave read-only fields out of
+ * `observed` first.
+ */
+export const isCurrent = (desired: unknown, observed: unknown) => deepEqual(unwrap(desired), unwrap(observed));
+
+/**
+ * `value` with every array sorted, recursively, for fields whose arrays are
+ * sets: the console keeps them in an order of its own (e.g. a firewall
+ * policy's port list), so order mustn't count as a difference.
+ */
+export const sortArrays = (value: unknown): unknown => {
+	if (Array.isArray(value)) {
+		return value.map(sortArrays).toSorted((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+	}
+	if (typeof value === "object" && value !== null && !Redacted.isRedacted(value)) {
+		return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, sortArrays(nested)]));
+	}
+	return value;
+};
+
+/** `record` without `keys`, e.g. read-only fields the console rejects in request bodies. */
+export const omitKeys = (record: object, keys: ReadonlyArray<string>): Record<string, unknown> =>
+	Object.fromEntries(Object.entries(record).filter(([key]) => !keys.includes(key)));

package/src/internal/Networks.ts

@@ -0,0 +1,7 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import * as Stream from "effect/Stream";
+import { withConnection } from "../Connection.ts";
+
+/** A site's networks, uncached. */
+export const loadNetworks = (siteId: string) =>
+	withConnection(Stream.runCollect(Sdk.getNetworksOverviewPage.items({ siteId })));

package/src/internal/Plan.ts

@@ -0,0 +1,22 @@
+import { isResolved } from "alchemy/Diff";
+import * as Predicate from "effect/Predicate";
+
+/** A prop whose value depends on another resource's output, so isn't known while planning. */
+export const UNKNOWN: unique symbol = Symbol("UnifiNetwork.unknown");
+
+/**
+ * A top-level prop of `diff`'s `news` (props that may still hold outputs of
+ * resources not yet deployed): its value, `undefined` when unset, or
+ * {@link UNKNOWN}.
+ */
+export const planned = (news: unknown, key: string): unknown => {
+	if (typeof news !== "object" || news === null) return UNKNOWN;
+	const value = Predicate.hasProperty(news, key) ? news[key] : undefined;
+	return isResolved(value) ? value : UNKNOWN;
+};
+
+/** {@link planned} for string props such as `site`. */
+export const plannedString = (news: unknown, key: string): string | undefined | typeof UNKNOWN => {
+	const value = planned(news, key);
+	return value === UNKNOWN || value === undefined || typeof value === "string" ? value : UNKNOWN;
+};

package/src/internal/Services.ts

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import type { UnifiNetworkConnection } from "../Connection.ts";
+import type { UnifiNetworkCredentials } from "../Credentials.ts";
+import type { UnifiNetworkReadCache } from "../ReadCache.ts";
+
+/** What resource lifecycle handlers and lookups need. `providers()` provides all of them. */
+export type Services = UnifiNetworkCredentials | UnifiNetworkConnection | UnifiNetworkReadCache;
+
+/**
+ * The provider's services, captured when the provider is built, as a
+ * function that runs a handler with them. Handlers then don't depend on
+ * what the stack's merged context happens to hold when they run.
+ */
+export const captureServices = Effect.map(
+	Effect.context<Services>(),
+	(services) =>
+		<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, Services>> =>
+			Effect.provide(effect, services),
+);