@alchemy-unifi/network 0.0.1 → 0.1.0

package/src/Lookup.ts

@@ -0,0 +1,34 @@
+import { UserFacingError } from "alchemy/UserFacingError";
+import * as Data from "effect/Data";
+import type { Site } from "./Site.ts";
+
+/** A `lookup` found nothing matching its query. */
+export class LookupNotFound extends Data.TaggedError("LookupNotFound")<{
+	readonly resource: string;
+	readonly query: string;
+	readonly site: Site;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `No ${this.resource} matches ${this.query} in site ${this.site.internalReference} (${this.site.name}).`;
+	}
+}
+
+/** A `lookup` matched several objects, e.g. networks sharing a name. */
+export class LookupAmbiguous extends Data.TaggedError("LookupAmbiguous")<{
+	readonly resource: string;
+	readonly query: string;
+	readonly site: Site;
+	readonly count: number;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `${this.count} ${this.resource}s match ${this.query} in site ${this.site.internalReference} (${this.site.name}). Use a more specific query.`;
+	}
+}
+
+export const describeQuery = (query: object) =>
+	Object.entries(query)
+		.filter(([key, value]) => key !== "site" && value !== undefined)
+		.map(([key, value]) => `${key} ${JSON.stringify(value)}`)
+		.join(" and ");

package/src/Network.ts

@@ -0,0 +1,335 @@
+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 { withConnection } from "./Connection.ts";
+import { type FirewallZoneReference, resolveFirewallZone } from "./FirewallZone.ts";
+import { type DistributiveOmit, isCurrent, omitKeys } from "./internal/Fields.ts";
+import { loadNetworks } from "./internal/Networks.ts";
+import { planned, plannedString, UNKNOWN } from "./internal/Plan.ts";
+import { captureServices } from "./internal/Services.ts";
+import { describeQuery, LookupAmbiguous, LookupNotFound } from "./Lookup.ts";
+import type { Providers } from "./Providers.ts";
+import * as ReadCache from "./ReadCache.ts";
+import { checkSameSite, resolveSite, type Site } from "./Site.ts";
+
+interface SiteProp {
+	/** Site to create the network in. @default the profile's site, else the console's only site */
+	site?: string;
+}
+
+/** A device, e.g. the switch routing a switch-managed network. */
+export interface DeviceReference {
+	readonly deviceId: string;
+}
+
+/** A network routed by the gateway: the usual kind, with DHCP, zones and internet access. */
+export interface GatewayNetworkProps
+	extends Omit<Sdk.IntegrationGatewayManagedNetworkCreateUpdateDto, "zoneId">, SiteProp {
+	/**
+	 * The network's firewall zone, e.g. `FirewallZone.INTERNAL` or a
+	 * `FirewallZone` resource. Required once the site uses the zone-based
+	 * firewall.
+	 */
+	zone?: FirewallZoneReference;
+}
+
+/** A network routed by a layer-3 switch. */
+export interface SwitchNetworkProps
+	extends Omit<Sdk.IntegrationSwitchManagedNetworkCreateUpdateDto, "deviceId">, SiteProp {
+	/** The switch routing the network. */
+	device: DeviceReference;
+}
+
+/** A VLAN that UniFi carries but doesn't route; something else on it does. */
+export interface UnmanagedNetworkProps extends Sdk.IntegrationUnmanagedNetworkCreateUpdateDto, SiteProp {}
+
+/** Props are the Integration API's network body, plus `site` and references; `management` picks the kind. */
+export type NetworkProps = GatewayNetworkProps | SwitchNetworkProps | UnmanagedNetworkProps;
+
+/** A network: a `Network` resource, a {@link Network.lookup} result, or `{ networkId }`. */
+export interface NetworkReference {
+	readonly networkId: string;
+	readonly siteId?: string | undefined;
+	/** Set by resources and lookups. Some objects must reference the default network differently. */
+	readonly default?: boolean | undefined;
+}
+
+/** A change that would replace the site's default network, which can't be deleted. */
+export class DefaultNetworkReplacement extends Data.TaggedError("DefaultNetworkReplacement")<{
+	readonly networkName: string;
+	readonly reason: string;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `${this.networkName} is the site's default network, which can't be replaced (${this.reason}). It must stay gateway-managed in its site.`;
+	}
+}
+
+export interface NetworkAttributes {
+	siteId: string;
+	networkId: string;
+	name: string;
+	vlanId: number;
+	management: NetworkProps["management"];
+	/** The network's firewall zone (gateway networks). */
+	zoneId: string | undefined;
+	/** Whether this is the site's default network, which is never deleted. */
+	default: boolean;
+	/** The whole network as the console reports it, so `alchemy drift` sees any change. */
+	config: DistributiveOmit<Sdk.NetworkDetails, "id" | "metadata" | "default">;
+}
+
+export interface Network extends Resource<"UnifiNetwork.Network", NetworkProps, NetworkAttributes, never, Providers> {}
+
+const networksKey = ReadCache.key<ReadonlyArray<Sdk.NetworkOverview>, Effect.Error<ReturnType<typeof loadNetworks>>>(
+	"networks",
+);
+
+/** A site's networks, listed once per run. */
+export const listNetworks = (siteId: string) => ReadCache.cached(networksKey, siteId, loadNetworks(siteId));
+
+const toAttributes = (siteId: string, network: Sdk.NetworkDetails): NetworkAttributes => {
+	const { id, metadata: _metadata, default: isDefault, ...config } = network;
+	return {
+		siteId,
+		networkId: id,
+		name: network.name,
+		vlanId: network.vlanId,
+		management: network.management,
+		zoneId: "zoneId" in network ? network.zoneId : undefined,
+		default: isDefault,
+		config,
+	};
+};
+
+/** Fields the console reports but rejects in request bodies. */
+const READ_ONLY = ["id", "metadata", "default"];
+
+/**
+ * `body` with explicit values for the two unset fields that can't simply be
+ * left out (both verified):
+ * - `mdnsForwardingEnabled`: a `PUT` without it keeps the console's value
+ *   instead of resetting it, so the default (`true`, what the console sets on
+ *   create) is always sent;
+ * - a DHCP server's `domainName`: the console reports `""` when it's 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.CreateOrUpdateNetwork): Sdk.CreateOrUpdateNetwork => {
+	if (body.management !== "GATEWAY") return body;
+	const dhcp = body.ipv4Configuration.dhcpConfiguration;
+	return {
+		...body,
+		mdnsForwardingEnabled: body.mdnsForwardingEnabled ?? true,
+		ipv4Configuration: {
+			...body.ipv4Configuration,
+			...(dhcp?.mode === "SERVER" ? { dhcpConfiguration: { ...dhcp, domainName: dhcp.domainName ?? "" } } : {}),
+		},
+	};
+};
+
+/** The request body for `props`, with references resolved to IDs. */
+const toBody = Effect.fn(function* (props: NetworkProps, site: Site) {
+	switch (props.management) {
+		case "GATEWAY": {
+			const { site: _site, zone, ...rest } = props;
+			if (zone === undefined) return rest satisfies Sdk.CreateOrUpdateNetwork;
+			const zoneId = yield* resolveFirewallZone(zone, site);
+			return { ...rest, zoneId } satisfies Sdk.CreateOrUpdateNetwork;
+		}
+		case "SWITCH": {
+			const { site: _site, device, ...rest } = props;
+			return { ...rest, deviceId: device.deviceId } satisfies Sdk.CreateOrUpdateNetwork;
+		}
+		case "UNMANAGED": {
+			const { site: _site, ...rest } = props;
+			return rest satisfies Sdk.CreateOrUpdateNetwork;
+		}
+	}
+});
+
+/** The network ID a reference means in `site`. */
+export const resolveNetwork = (reference: NetworkReference, site: Site) =>
+	checkSameSite("network", reference.siteId, site).pipe(Effect.as(reference.networkId));
+
+const getNetwork = (siteId: string, networkId: string) =>
+	withConnection(Sdk.getNetworkDetails({ siteId, networkId })).pipe(
+		Effect.catchTag("NotFound", () => Effect.undefined),
+	);
+
+/** The attributes of a network known to exist (e.g. from a list). */
+const attributesOf = (siteId: string, networkId: string) =>
+	withConnection(Sdk.getNetworkDetails({ siteId, networkId })).pipe(
+		Effect.map((network) => toAttributes(siteId, network)),
+	);
+
+const isUserDefined = (network: Sdk.NetworkOverview) => network.metadata.origin === "USER_DEFINED";
+
+/**
+ * A network (VLAN). `management` picks the kind: `"GATEWAY"` (routed by the
+ * gateway), `"SWITCH"` (routed by a layer-3 switch) or `"UNMANAGED"`.
+ * Changing it, or the site, replaces the network: the old one is deleted
+ * first, since VLAN IDs must be unique.
+ *
+ * Props are authoritative: every update sends the whole network, with
+ * explicit defaults for unset fields (`mdnsForwardingEnabled: true`, and a
+ * DHCP server's `domainName: ""`), so changes made in the UI are put back.
+ * The `config` attribute mirrors the console's object, so `alchemy drift`
+ * sees them.
+ * Existing networks are adopted by VLAN ID
+ * with `--adopt` (and renamed to match), including the site's default
+ * network (VLAN 1), which is never deleted or replaced.
+ *
+ * @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* () {
+ * 		yield* UnifiNetwork.Network("guest", {
+ * 			management: "GATEWAY",
+ * 			name: "Guest",
+ * 			vlanId: 12,
+ * 			enabled: true,
+ * 			cellularBackupEnabled: false,
+ * 			internetAccessEnabled: true,
+ * 			isolationEnabled: true,
+ * 			zone: UnifiNetwork.FirewallZone.HOTSPOT,
+ * 			ipv4Configuration: { autoScaleEnabled: false, hostIpAddress: "192.168.12.1", prefixLength: 24 },
+ * 		});
+ * 	}),
+ * );
+ * ```
+ */
+export const Network = Resource<Network>("UnifiNetwork.Network")({
+	/**
+	 * A network in the site by name or VLAN ID. Dies with a user-facing
+	 * `LookupNotFound` or `LookupAmbiguous`: stack bodies can't fail with typed
+	 * errors.
+	 */
+	lookup: Effect.fn("UnifiNetwork.Network.lookup")(function* (
+		query: ({ readonly name: string } | { readonly vlanId: number }) & { readonly site?: string },
+	) {
+		const site = yield* resolveSite(query.site);
+		const networks = (yield* listNetworks(site.id)).filter((n) =>
+			"vlanId" in query ? n.vlanId === query.vlanId : n.name === query.name,
+		);
+		const [network] = networks;
+		if (network === undefined) {
+			return yield* new LookupNotFound({ resource: "network", query: describeQuery(query), site });
+		}
+		if (networks.length > 1) {
+			return yield* new LookupAmbiguous({
+				resource: "network",
+				query: describeQuery(query),
+				site,
+				count: networks.length,
+			});
+		}
+		return yield* attributesOf(site.id, network.id);
+	}, Effect.orDie),
+});
+
+export const NetworkProvider = () =>
+	Provider.effect(
+		Network,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return Network.Provider.of({
+				list: () =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite();
+							const networks = yield* listNetworks(site.id);
+							return yield* Effect.forEach(networks.filter(isUserDefined), (network) =>
+								attributesOf(site.id, network.id),
+							);
+						}),
+					),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								const network = yield* getNetwork(output.siteId, output.networkId);
+								return network === undefined ? undefined : toAttributes(output.siteId, network);
+							}
+							const site = yield* resolveSite(olds.site);
+							// VLAN IDs are unique per site, so the VLAN alone identifies the network, and adopting renames it.
+							const network = (yield* listNetworks(site.id)).find((n) => n.vlanId === olds.vlanId);
+							return network === undefined
+								? undefined
+								: Unowned(yield* attributesOf(site.id, network.id));
+						}),
+					),
+
+				diff: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output === undefined) return undefined;
+							const replace = (reason: string) =>
+								output.default
+									? Effect.fail(new DefaultNetworkReplacement({ networkName: output.name, reason }))
+									: Effect.succeed({ action: "replace", deleteFirst: true } satisfies Diff);
+							const management = planned(news, "management");
+							if (management !== UNKNOWN && management !== output.management) {
+								return yield* replace(`its management would change to ${String(management)}`);
+							}
+							const siteProp = plannedString(news, "site");
+							if (siteProp === UNKNOWN) return undefined;
+							const site = yield* resolveSite(siteProp);
+							if (site.id !== output.siteId)
+								return yield* replace(`it would move to site ${site.internalReference}`);
+							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* getNetwork(site.id, output.networkId)
+									: undefined;
+							const write = ReadCache.invalidating(networksKey, site.id);
+							if (observed === undefined) {
+								const created = yield* withConnection(
+									Sdk.createNetwork({ 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.updateNetwork({ siteId: site.id, networkId: observed.id, body }),
+							).pipe(write);
+							return toAttributes(site.id, updated);
+						}),
+					),
+
+				delete: ({ output }) =>
+					output.default
+						? Effect.logInfo(`Leaving ${output.name}, the site's default network, in place.`)
+						: run(
+								withConnection(
+									Sdk.deleteNetwork({ siteId: output.siteId, networkId: output.networkId }),
+								).pipe(
+									Effect.asVoid,
+									Effect.catchTag("NotFound", () => Effect.void),
+									ReadCache.invalidating(networksKey, output.siteId),
+								),
+							),
+			});
+		}),
+	);

package/src/Providers.ts

@@ -0,0 +1,59 @@
+import * as Provider from "alchemy/Provider";
+import * as Layer from "effect/Layer";
+import { UnifiNetworkAuth } from "./AuthProvider.ts";
+import * as Connection from "./Connection.ts";
+import * as Credentials from "./Credentials.ts";
+import { DnsPolicy, DnsPolicyProvider } from "./DnsPolicy.ts";
+import { FirewallPolicy, FirewallPolicyProvider } from "./FirewallPolicy.ts";
+import { FirewallPolicyOrdering, FirewallPolicyOrderingProvider } from "./FirewallPolicyOrdering.ts";
+import { FirewallZone, FirewallZoneProvider } from "./FirewallZone.ts";
+import { Network, NetworkProvider } from "./Network.ts";
+import { TrafficMatchingList, TrafficMatchingListProvider } from "./TrafficMatchingList.ts";
+import { WifiBroadcast, WifiBroadcastProvider } from "./WifiBroadcast.ts";
+import * as ReadCache from "./ReadCache.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()("UnifiNetwork") {}
+
+/**
+ * Registers every UniFi Network resource provider, the `UnifiNetwork` auth
+ * provider, the lazily-resolved credentials and connection, and the per-run
+ * read cache. Merge
+ * alongside other cloud `providers()` layers in a Stack.
+ *
+ * Its requirements (`AuthProviders`, `ProfileStore`, `FileSystem`, `Path`)
+ * come from Alchemy's runtime; it provides only its own services.
+ *
+ * Unlike most providers this doesn't provide an `HttpClient`: ours carries
+ * the console's TLS settings, and lifecycle operations run in the stack's
+ * merged context, so it would replace other providers' clients. SDK calls
+ * get it through `UnifiNetworkConnection` instead.
+ */
+export const providers = () =>
+	Layer.effect(
+		Providers,
+		Provider.collection([
+			FirewallZone,
+			Network,
+			WifiBroadcast,
+			TrafficMatchingList,
+			FirewallPolicy,
+			FirewallPolicyOrdering,
+			DnsPolicy,
+		]),
+	).pipe(
+		Layer.provide(
+			Layer.mergeAll(
+				FirewallZoneProvider(),
+				NetworkProvider(),
+				WifiBroadcastProvider(),
+				TrafficMatchingListProvider(),
+				FirewallPolicyProvider(),
+				FirewallPolicyOrderingProvider(),
+				DnsPolicyProvider(),
+			),
+		),
+		Layer.provideMerge(Layer.merge(Connection.layer, ReadCache.layer)),
+		Layer.provideMerge(Credentials.fromAuthProvider()),
+		Layer.provideMerge(UnifiNetworkAuth),
+		Layer.orDie,
+	);

package/src/ReadCache.ts

@@ -0,0 +1,79 @@
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+
+/**
+ * Per-run memo of API reads, so a plan touching many resources lists each
+ * collection once instead of once per resource. One instance per
+ * `providers()` build, i.e. per CLI run or test file. The value is only an
+ * identity: entries live on each {@link Key}, keyed by it.
+ */
+export class UnifiNetworkReadCache extends Context.Service<UnifiNetworkReadCache, { readonly run: object }>()(
+	"UnifiNetwork::ReadCache",
+) {
+	/** Alchemy's tag for environment services, which lets stack bodies (and so lookups) require this one. */
+	declare readonly kind: "Environment";
+}
+
+export const layer = Layer.sync(UnifiNetworkReadCache, () => ({ run: {} }));
+
+/**
+ * One kind of cached read, e.g. a resource type's list. `scope` arguments
+ * separate its entries, e.g. by site ID.
+ */
+export interface Key<A, E> {
+	readonly name: string;
+	readonly entries: WeakMap<object, Map<string, Deferred.Deferred<A, E>>>;
+}
+
+export const key = <A, E = never>(name: string): Key<A, E> => ({ name, entries: new WeakMap() });
+
+const entriesFor = <A, E>(cacheKey: Key<A, E>, run: object) => {
+	const existing = cacheKey.entries.get(run);
+	if (existing !== undefined) return existing;
+	const entries = new Map<string, Deferred.Deferred<A, E>>();
+	cacheKey.entries.set(run, entries);
+	return entries;
+};
+
+/**
+ * `load`'s result, shared by every caller in this run until invalidated.
+ * Concurrent callers wait for one load. Failures aren't cached.
+ */
+export const cached = <A, E, R>(
+	cacheKey: Key<A, E>,
+	scope: string,
+	load: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R | UnifiNetworkReadCache> =>
+	Effect.gen(function* () {
+		const { run } = yield* UnifiNetworkReadCache;
+		const entries = entriesFor(cacheKey, run);
+		const existing = entries.get(scope);
+		if (existing !== undefined) return yield* Deferred.await(existing);
+		const deferred = Deferred.makeUnsafe<A, E>();
+		entries.set(scope, deferred);
+		return yield* load.pipe(
+			Effect.onExit((exit) => {
+				if (Exit.isFailure(exit) && entries.get(scope) === deferred) entries.delete(scope);
+				return Deferred.done(deferred, exit);
+			}),
+		);
+	});
+
+/** Drops an entry, so the next read loads afresh. */
+export const invalidate = <A, E>(
+	cacheKey: Key<A, E>,
+	scope: string,
+): Effect.Effect<void, never, UnifiNetworkReadCache> =>
+	Effect.gen(function* () {
+		const { run } = yield* UnifiNetworkReadCache;
+		cacheKey.entries.get(run)?.delete(scope);
+	});
+
+/** Runs a write, then invalidates the entry it affects, whether or not the write succeeded. */
+export const invalidating =
+	<A, E>(cacheKey: Key<A, E>, scope: string) =>
+	<B, E2, R>(write: Effect.Effect<B, E2, R>): Effect.Effect<B, E2, R | UnifiNetworkReadCache> =>
+		Effect.ensuring(write, invalidate(cacheKey, scope));

package/src/Site.ts

@@ -0,0 +1,100 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+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 { UnifiNetworkCredentials } from "./Credentials.ts";
+import * as ReadCache from "./ReadCache.ts";
+
+/** A UniFi site: a namespace within one console. */
+export interface Site {
+	/** The ID other Integration API calls take. */
+	readonly id: string;
+	/** Stable reference that survives renames: `default`, or a generated one like `x7k2m9q1`. */
+	readonly internalReference: string;
+	readonly name: string;
+}
+
+const describeSites = (sites: ReadonlyArray<Site>) =>
+	sites.map((site) => `${site.internalReference} (${site.name})`).join(", ") || "none";
+
+export class SiteNotFound extends Data.TaggedError("SiteNotFound")<{
+	readonly site: string;
+	readonly available: ReadonlyArray<Site>;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `The console has no site "${this.site}". Its sites: ${describeSites(this.available)}. Point the profile's site, or the resource's site prop, at one of them.`;
+	}
+}
+
+export class SiteRequired extends Data.TaggedError("SiteRequired")<{ readonly available: ReadonlyArray<Site> }> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `The console hosts several sites (${describeSites(this.available)}), so resources need one: set site in the profile (alchemy profile edit --reconfigure UnifiNetwork), or the resource's site prop.`;
+	}
+}
+
+export class AmbiguousSite extends Data.TaggedError("AmbiguousSite")<{
+	readonly site: string;
+	readonly matches: ReadonlyArray<Site>;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `Several sites are named "${this.site}" (${describeSites(this.matches)}). Use the internal reference instead.`;
+	}
+}
+
+/** A resource referenced another that lives in a different site. */
+export class CrossSiteReference extends Data.TaggedError("CrossSiteReference")<{
+	readonly what: string;
+	readonly referencedSiteId: string;
+	readonly site: Site;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `The referenced ${this.what} is in another site (${this.referencedSiteId}), not ${this.site.internalReference} (${this.site.name}). UniFi objects can only reference objects in their own site.`;
+	}
+}
+
+/** Fails if a reference carries a site ID (resources and lookups do) other than `site`'s. */
+export const checkSameSite = (what: string, referencedSiteId: string | undefined, site: Site) =>
+	referencedSiteId === undefined || referencedSiteId === site.id
+		? Effect.void
+		: Effect.fail(new CrossSiteReference({ what, referencedSiteId, site }));
+
+const loadSites = withConnection(
+	Sdk.getSiteOverviewPage.items({}).pipe(
+		Stream.map(({ id, internalReference, name }): Site => ({ id, internalReference, name })),
+		Stream.runCollect,
+	),
+);
+
+export const sitesKey = ReadCache.key<ReadonlyArray<Site>, Effect.Error<typeof loadSites>>("sites");
+
+/** The console's sites, listed once per run. */
+export const listSites = ReadCache.cached(sitesKey, "", loadSites);
+
+/**
+ * The site a resource belongs to: `site` (an ID, internal reference or
+ * name), else the profile's site, else the console's only site. Fails,
+ * listing the console's sites, when it doesn't exist or is ambiguous, so a
+ * plan stops before changing anything.
+ */
+export const resolveSite = Effect.fn("UnifiNetwork.resolveSite")(function* (site?: string) {
+	const requested = site ?? (yield* yield* UnifiNetworkCredentials).site;
+	const sites = yield* listSites;
+	if (requested === undefined) {
+		const [only] = sites;
+		if (only !== undefined && sites.length === 1) return only;
+		return yield* new SiteRequired({ available: sites });
+	}
+	const byReference = sites.find((s) => s.id === requested || s.internalReference === requested);
+	if (byReference !== undefined) return byReference;
+	const byName = sites.filter((s) => s.name === requested);
+	const [match] = byName;
+	if (match !== undefined && byName.length === 1) return match;
+	if (byName.length > 1) return yield* new AmbiguousSite({ site: requested, matches: byName });
+	return yield* new SiteNotFound({ site: requested, available: sites });
+});

package/src/SiteManager.ts

@@ -0,0 +1,68 @@
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { SITE_MANAGER_URL } from "./Connection.ts";
+
+/**
+ * Just enough of the Site Manager API (`GET /v1/hosts`) for `configure` to
+ * list the consoles a key can reach. A full SDK belongs in its own package.
+ */
+const Host = Schema.Struct({
+	id: Schema.String,
+	type: Schema.optional(Schema.NullOr(Schema.String)),
+	reportedState: Schema.optional(
+		Schema.NullOr(
+			Schema.Struct({
+				name: Schema.optional(Schema.NullOr(Schema.String)),
+				hostname: Schema.optional(Schema.NullOr(Schema.String)),
+			}),
+		),
+	),
+});
+
+const HostsPage = Schema.Struct({
+	data: Schema.Array(Host),
+	nextToken: Schema.optional(Schema.NullOr(Schema.String)),
+});
+
+export interface Console {
+	/** The host ID, which the cloud connector takes as the console ID. */
+	readonly id: string;
+	readonly name: string;
+	/** Host type as reported by Site Manager, e.g. `console`. */
+	readonly type: string | undefined;
+}
+
+export const listConsoles = (
+	apiKey: Redacted.Redacted<string>,
+): Effect.Effect<ReadonlyArray<Console>, unknown, HttpClient.HttpClient> =>
+	Effect.gen(function* () {
+		const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
+		const consoles: Console[] = [];
+		let nextToken: string | undefined;
+		do {
+			const page = yield* client
+				.execute(
+					HttpClientRequest.get(`${SITE_MANAGER_URL}/v1/hosts`).pipe(
+						HttpClientRequest.setHeaders({
+							"X-API-KEY": Redacted.value(apiKey),
+							Accept: "application/json",
+						}),
+						HttpClientRequest.setUrlParams(nextToken === undefined ? {} : { nextToken }),
+					),
+				)
+				.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(HostsPage)));
+			for (const host of page.data) {
+				consoles.push({
+					id: host.id,
+					name: host.reportedState?.name ?? host.reportedState?.hostname ?? host.id,
+					type: host.type ?? undefined,
+				});
+			}
+			nextToken = page.nextToken ?? undefined;
+		} while (nextToken !== undefined);
+		return consoles;
+	});